feat: scaffold howtos project

Collection of usage guides and cheatsheets. Includes project docs,
topic template, and directory structure.

.gitignore

@@ -0,0 +1,4 @@
+*.swp
+*.swo
+*~
+.DS_Store

PROJECT.md

@@ -0,0 +1,31 @@
+# Project: howtos
+
+## Motivation
+
+Scattered notes, bookmarks, and `history | grep` are poor substitutes for well-organized reference material. This project centralizes practical knowledge into a consistent, maintainable format.
+
+## Goals
+
+- Provide quick-reference guides for daily tools and workflows
+- Maintain a consistent structure across all topics
+- Keep content concise and actionable — no tutorials, just references
+- Make it easy to add new topics via a template
+
+## Architecture
+
+Flat file collection — no build step, no dependencies. Plain Markdown rendered by any viewer (terminal, browser, editor).
+
+```
+topics/<topic>.md     # Individual howto files
+docs/TEMPLATE.md      # Template for new topics
+```
+
+## Dependencies
+
+None. Plain Markdown files. Optionally viewed with `glow`, `bat`, or any Markdown renderer.
+
+## Non-Goals
+
+- Not a tutorial site or blog
+- Not a wiki with cross-linking
+- Not auto-generated from `--help` output

README.md

@@ -0,0 +1,41 @@
+# howtos
+
+A curated collection of usage guides and cheatsheets for tools, languages, and workflows.
+
+## Purpose
+
+Quick-reference documentation — concise, searchable, copy-pasteable. Each topic lives in its own file under `topics/`.
+
+## Structure
+
+```
+topics/
+  <topic>.md        # One file per subject
+docs/
+  USAGE.md          # How to use this collection
+  CHEATSHEET.md     # Meta cheatsheet (formatting conventions)
+  INSTALL.md        # Setup (minimal)
+```
+
+## Quick Start
+
+Browse `topics/` and open any `.md` file. Each howto follows a consistent format:
+
+- **Title** — what the tool/topic is
+- **Common commands** — the 20% you use 80% of the time
+- **Examples** — real-world usage
+- **Gotchas** — things that bite
+
+## Adding a New Topic
+
+```bash
+cp docs/TEMPLATE.md topics/<topic>.md
+# Edit and fill in sections
+```
+
+## Conventions
+
+- One topic per file, lowercase hyphenated names (`docker-compose.md`, `git-rebase.md`)
+- Code blocks with language hints for syntax highlighting
+- Keep each file under 200 lines — split if larger
+- Mark optional flags/args with `[]`

ROADMAP.md

@@ -0,0 +1,24 @@
+# Roadmap
+
+## v0.1 — Foundation
+
+- [x] Project scaffold (README, docs, template)
+- [ ] First batch of topics (5-10 core tools)
+- [ ] Establish formatting conventions
+
+## v0.2 — Core Coverage
+
+- [ ] 20+ topics covering daily workflow
+- [ ] Index/table of contents generation
+- [ ] Tagging system (categories in frontmatter)
+
+## v1.0 — Complete Reference
+
+- [ ] 50+ topics
+- [ ] Search script or integration
+- [ ] Consistent quality across all files
+
+## Future
+
+- Topic freshness tracking (last-reviewed dates)
+- Automated linting for format consistency

TASKS.md

@@ -0,0 +1,12 @@
+# Tasks
+
+## Current
+
+- [x] Scaffold project structure
+- [ ] Create topic template
+- [ ] Write first topic
+
+## Backlog
+
+- [ ] Decide on category/tagging approach
+- [ ] Add table of contents to README

TODO.md

@@ -0,0 +1,20 @@
+# TODO
+
+## Topics to Write
+
+- [ ] git — common workflows, rebase, stash, bisect
+- [ ] ansible — playbook patterns, inventory, vault
+- [ ] podman — build, run, compose, volumes
+- [ ] jq — filters, select, map, slurp
+- [ ] curl — headers, auth, methods, output
+- [ ] systemd — units, journalctl, timers
+- [ ] ssh — config, tunnels, keys, agent
+- [ ] bash — parameter expansion, arrays, traps
+- [ ] make — targets, variables, patterns
+- [ ] vim — motions, registers, macros
+
+## Improvements
+
+- [ ] Format linter script
+- [ ] Auto-generate index from topics/
+- [ ] Add last-reviewed date to template

docs/CHEATSHEET.md

@@ -0,0 +1,23 @@
+# Cheatsheet
+
+## Quick Reference
+
+| Action              | Command                              |
+|---------------------|--------------------------------------|
+| List topics         | `ls topics/`                         |
+| Read topic          | `bat topics/<name>.md`               |
+| Add topic           | `cp docs/TEMPLATE.md topics/<n>.md`  |
+| Search across all   | `grep -ri <term> topics/`            |
+
+## File Format
+
+Each topic file follows `docs/TEMPLATE.md`:
+
+```
+# <Topic>
+## Overview        — one-liner description
+## Common Commands — daily-driver commands
+## Examples        — real-world patterns
+## Gotchas         — pitfalls and edge cases
+## See Also        — related topics, links
+```

docs/INSTALL.md

@@ -0,0 +1,23 @@
+# Install
+
+## Prerequisites
+
+None. This is a plain Markdown collection.
+
+## Optional Tools
+
+For better terminal rendering:
+
+```bash
+# bat — syntax-highlighted cat
+sudo apt install bat
+
+# glow — terminal markdown renderer
+sudo apt install glow
+```
+
+## Clone
+
+```bash
+git clone <repo-url> ~/git/howtos
+```

docs/TEMPLATE.md

@@ -0,0 +1,26 @@
+# Topic Name
+
+> One-line description of what this tool/subject is.
+
+## Common Commands
+
+```bash
+# description
+command --flag argument
+```
+
+## Examples
+
+```bash
+# Practical example with context
+command --option value
+```
+
+## Gotchas
+
+- Known pitfall or surprising behavior
+
+## See Also
+
+- `related-topic` — brief note
+- [External reference](https://example.com)

docs/USAGE.md

@@ -0,0 +1,29 @@
+# Usage
+
+## Browsing Topics
+
+Each topic is a standalone Markdown file in `topics/`:
+
+```bash
+# List available topics
+ls topics/
+
+# Read a topic in terminal
+cat topics/git.md        # plain
+bat topics/git.md        # syntax highlighted
+glow topics/git.md       # rendered markdown
+```
+
+## Adding a New Topic
+
+```bash
+cp docs/TEMPLATE.md topics/<name>.md
+```
+
+Edit the file following the template structure. Keep it under 200 lines.
+
+## Naming Conventions
+
+- Lowercase, hyphenated: `docker-compose.md`, `git-rebase.md`
+- One topic per file
+- Use the tool/subject name as the filename