@aladac/hu 0.1.0-a1

package/commands/docs/check-internal.md

@@ -0,0 +1,53 @@
+Check status of system documents. No arguments.
+
+Reports on the presence and status of system documents that are normally ignored by docs commands.
+
+## System Documents
+
+These files are ignored by other docs commands unless explicitly requested:
+
+**Internal project files:**
+- `MODELS.md` - Model definitions, schemas, data structures
+- `PLAN.md` - Project planning, roadmap, milestones
+- `TODO.md` - Task tracking, action items
+- `TEST.md` - Test plans, test results, coverage notes
+- `REFACTOR.md` - Refactoring notes, technical debt tracking
+
+**Standard repo files:**
+- `README.md` - Project readme
+- `CLAUDE.md` - Claude configuration
+- `LICENSE.md` - License file
+- `CHANGELOG.md` - Change history
+- `CONTRIBUTING.md` - Contribution guidelines
+
+**Not documentation:**
+- `.claude/commands/**/*.md` - These are slash commands, NOT docs
+
+## Implementation
+
+Use `hu docs check`:
+
+```bash
+# Default: markdown table output
+hu docs check
+
+# JSON output for parsing
+hu docs check -j
+```
+
+The script automatically:
+- Scans repo root for all system documents
+- Reports size, lines, modified date
+- Counts checkboxes in TODO.md/PLAN.md
+- Outputs summary of found documents
+
+## Manifest
+
+The document manifest at `./document-manifest.toml` (repo root) tracks external documentation.
+System documents are NOT tracked in the manifest - they are repo-specific files.
+
+## Notes
+
+- This command is READ-ONLY - it never modifies any files
+- Use this to check project status before running cleanup/archive commands
+- To work with these files, explicitly name them in other commands

package/commands/docs/cleanup.md

@@ -0,0 +1,65 @@
+Clean up markdown files in current repo. Arguments: [file...] or no args for auto-detect
+
+## ⚠️ SYSTEM DOCUMENTS - DO NOT TOUCH
+
+The following are **SYSTEM DOCUMENTS** and are **OFF-LIMITS** unless the user explicitly asks you to work with them:
+
+**Internal project files:**
+- `MODELS.md` - Model definitions, schemas
+- `PLAN.md` - Project planning, roadmap
+- `TODO.md` - Task tracking
+- `TEST.md` - Test plans, results
+- `REFACTOR.md` - Refactoring notes, tech debt
+
+**Standard repo files:**
+- `README.md` - Project readme
+- `CLAUDE.md` - Claude configuration
+- `LICENSE.md` - License file
+- `CHANGELOG.md` - Change history
+- `CONTRIBUTING.md` - Contribution guidelines
+
+**Not documentation:**
+- `.claude/commands/**/*.md` - These are slash commands, NOT docs
+
+All system documents must be completely ignored unless specifically named by the user.
+
+- With files: process specified files
+- Without: find and process all stray markdown in repo root
+
+Example: `/docs:cleanup` or `/docs:cleanup NOTES.md TODO.md`
+
+## Auto-detect mode
+
+1. Find markdown files in repo root
+2. Exclude: README.md, CLAUDE.md, LICENSE.md, CHANGELOG.md, CONTRIBUTING.md
+3. Process each file found
+
+## For each file
+
+1. Read and analyze content
+2. Check if outdated, deprecated, or stale
+3. Remove redundancy, trim verbose sections
+
+**TODO.md and PLAN.md** (progress trackers):
+- Remove completed items (`[x]`)
+- Keep only incomplete items (`[ ]`)
+- Update summary tables
+- If ALL complete: DELETE file
+- If incomplete remain: rewrite with only pending
+
+**Standard docs**:
+- If valuable: refine and move to `./doc/` with clean name
+- If no value: delete
+
+## Manifest
+
+Update `./document-manifest.toml` (repo root) when:
+- Moving files to `./doc/` - add new entry
+- Deleting files - remove entry if present
+
+## Commits
+
+After each file change:
+```
+git add <file> && git commit -m "docs: clean up {filename}"
+```

package/commands/docs/consolidate.md

@@ -0,0 +1,72 @@
+Consolidate and merge documentation files. Arguments: [location]
+
+## ⚠️ SYSTEM DOCUMENTS - DO NOT TOUCH
+
+The following are **SYSTEM DOCUMENTS** and are **OFF-LIMITS** unless the user explicitly asks you to work with them:
+
+**Internal project files:**
+- `MODELS.md` - Model definitions, schemas
+- `PLAN.md` - Project planning, roadmap
+- `TODO.md` - Task tracking
+- `TEST.md` - Test plans, results
+- `REFACTOR.md` - Refactoring notes, tech debt
+
+**Standard repo files:**
+- `README.md` - Project readme
+- `CLAUDE.md` - Claude configuration
+- `LICENSE.md` - License file
+- `CHANGELOG.md` - Change history
+- `CONTRIBUTING.md` - Contribution guidelines
+
+**Not documentation:**
+- `.claude/commands/**/*.md` - These are slash commands, NOT docs
+
+All system documents must be completely ignored by this command.
+
+- No argument: consolidate `./doc/`
+- "global": consolidate `~/.claude/documents/`
+
+Example: `/docs:consolidate` or `/docs:consolidate global`
+
+## Process
+
+1. Read all markdown files in target directory
+2. Analyze each file:
+   - Still relevant?
+   - Redundant with another file?
+   - Can merge with related file?
+
+## Consolidation rules
+
+- **Merge related**: Same topic = merge into one
+- **Single-word names**: Rename to uppercase words (`EXTRACTION.md`, `MODELS.md`)
+- **Delete outdated**: Remove obsolete content
+- **Delete stubs**: Remove minimal-value files
+
+## For global docs
+
+Cross-project consolidation:
+- If files across projects share themes, merge into `_consolidated/`
+- Use descriptive names: `PATTERNS.md`, `LEARNINGS.md`
+
+## Subdirectories
+
+Create when 3+ files share a theme:
+- `doc/arch/` - Architecture docs
+- `doc/plans/` - Implementation plans
+- `doc/testing/` - Test reports
+
+## Manifest
+
+Update the manifest when consolidating:
+- Project: `./document-manifest.toml` (repo root)
+- Global: `~/.claude/documents/manifest.toml`
+
+When merging/renaming/deleting, update manifest entries accordingly.
+
+## Commits
+
+After each change:
+- Merge: `git add <files> && git commit -m "docs: merge {source} into {target}"`
+- Rename: `git mv <old> <new> && git commit -m "docs: rename {old} to {new}"`
+- Delete: `git rm <file> && git commit -m "docs: remove {filename}"`

package/commands/docs/get.md

@@ -0,0 +1,101 @@
+Fetch documentation from the web and store locally. Arguments: subject [location]
+
+## ⚠️ SYSTEM DOCUMENTS - DO NOT TOUCH
+
+The following are **SYSTEM DOCUMENTS** and are **OFF-LIMITS** unless the user explicitly asks you to work with them:
+
+**Internal project files:**
+- `MODELS.md` - Model definitions, schemas
+- `PLAN.md` - Project planning, roadmap
+- `TODO.md` - Task tracking
+- `TEST.md` - Test plans, results
+- `REFACTOR.md` - Refactoring notes, tech debt
+
+**Standard repo files:**
+- `README.md` - Project readme
+- `CLAUDE.md` - Claude configuration
+- `LICENSE.md` - License file
+- `CHANGELOG.md` - Change history
+- `CONTRIBUTING.md` - Contribution guidelines
+
+**Not documentation:**
+- `.claude/commands/**/*.md` - These are slash commands, NOT docs
+
+All system documents must be completely ignored by this command.
+
+- `location` can be a category name or "global"
+- Without location: stores in `./doc/{slug}.md`
+- With category: stores in `./doc/{category}/{slug}.md`  
+- With "global": stores in `~/.claude/documents/{slug}.md`
+
+Example: `/docs:get "React hooks"` or `/docs:get "JWT auth" auth` or `/docs:get "Claude API" global`
+
+## Process
+
+1. **Parse arguments**:
+   - `subject`: Topic to search for (required)
+   - `location`: Category subfolder, or "global" for `~/.claude/documents/`
+
+2. **Determine destination**:
+   - No location: `./doc/{slug}.md`
+   - Category: `./doc/{category}/{slug}.md`
+   - "global": `~/.claude/documents/{slug}.md`
+
+3. **Search the web** using WebSearch
+   - Prefer official docs over blog posts
+
+4. **Fetch primary source** using `hu utils fetch-html`:
+   ```bash
+   hu utils fetch-html <url> -c
+   ```
+   - The `-c` flag enables extra cleaning (removes nav, footer, ads)
+   - For specific content areas, use `-s <selector>`: `hu utils fetch-html <url> -c -s "article.main"`
+   - Start with the best/most authoritative result
+
+5. **Follow reference links** for completeness:
+   - Identify key reference links in the fetched content (e.g., "See also", API references, tutorials)
+   - Fetch 1-3 additional links using `hu utils fetch-html <url> -c`
+   - Skip links that would duplicate content or are too verbose
+   - Merge useful content into a single cohesive document
+   - Note: Only follow links that add distinct value (examples, API details, configuration options)
+
+6. **Generate filename**: Slugify the subject
+   - Lowercase, hyphens, no special chars
+   - Example: "PostgreSQL indexes" → `postgresql-indexes.md`
+
+7. **Format the file**:
+   ```markdown
+   ---
+   source: {primary_url}
+   additional_sources:
+     - {url2}
+     - {url3}
+   fetched: {YYYY-MM-DD}
+   ---
+
+   # {Subject Title}
+
+   {content}
+   ```
+   Note: `additional_sources` only included if reference links were followed
+
+8. **Update manifest**:
+   - Project: `./document-manifest.toml` (repo root)
+   - Global: `~/.claude/documents/manifest.toml`
+   - Format (TOML):
+     ```toml
+     [[docs]]
+     path = "{path}"
+     source = "{url}"
+     fetched = "{YYYY-MM-DD}"
+     ```
+
+9. **Update README** (project only):
+    - Add to tree structure in `./doc/README.md`
+    - Add row to appropriate table
+
+10. **Commit**:
+    - Project: `git add ./doc/ && git commit -m "docs: add {subject} reference"`
+    - Global: no commit needed
+
+11. **Report** saved location and summary

package/commands/docs/list.md

@@ -0,0 +1,61 @@
+List documentation files. Arguments: [location]
+
+## ⚠️ SYSTEM DOCUMENTS - DO NOT TOUCH
+
+The following are **SYSTEM DOCUMENTS** and are **OFF-LIMITS** unless the user explicitly asks you to work with them:
+
+**Internal project files:**
+- `MODELS.md` - Model definitions, schemas
+- `PLAN.md` - Project planning, roadmap
+- `TODO.md` - Task tracking
+- `TEST.md` - Test plans, results
+- `REFACTOR.md` - Refactoring notes, tech debt
+
+**Standard repo files:**
+- `README.md` - Project readme
+- `CLAUDE.md` - Claude configuration
+- `LICENSE.md` - License file
+- `CHANGELOG.md` - Change history
+- `CONTRIBUTING.md` - Contribution guidelines
+
+**Not documentation:**
+- `.claude/commands/**/*.md` - These are slash commands, NOT docs
+
+All system documents must be completely ignored by this command.
+
+- No argument: list project docs (`./doc/`)
+- "global": list global docs (`~/.claude/documents/`)
+- "all": list both locations
+- "repo": list all markdown in current repo
+
+Example: `/docs:list` or `/docs:list global` or `/docs:list repo`
+
+## Implementation
+
+Use `hu docs list`:
+
+```bash
+# Project docs (default)
+hu docs list
+
+# Global docs
+hu docs list global
+
+# Both locations
+hu docs list all
+
+# All repo markdown (excludes system docs)
+hu docs list repo
+
+# JSON output for parsing
+hu docs list -j
+hu docs list repo -j
+```
+
+The script outputs a markdown table with: File, Title, Size, Lines, Modified, Source
+
+## Manifest
+
+The document manifest is located at:
+- Project: `./document-manifest.toml` (repo root)
+- Global: `~/.claude/documents/manifest.toml`

package/commands/docs/sync.md

@@ -0,0 +1,64 @@
+Sync and update downloaded documentation. Arguments: [file|category|"all"]
+
+Re-fetches documentation sources to expand and update with new information.
+
+## Usage
+
+- `/docs:sync` - Sync all docs in current project
+- `/docs:sync all` - Sync all docs (project + global)
+- `/docs:sync auth` - Sync all docs in `./doc/auth/` category
+- `/docs:sync ./doc/react-hooks.md` - Sync specific file
+- `/docs:sync global` - Sync only global docs (`~/.claude/documents/`)
+
+## CLI Tools Available
+
+```bash
+# Scan docs to see what needs updating
+hu docs scan [target] [-j]
+
+# Fetch fresh content from a URL
+hu utils fetch-html <url> -c
+```
+
+## Process
+
+1. **Identify targets** using `hu docs scan [target] -j`:
+   - Returns JSON with source URLs, fetched dates, staleness status
+   - Focus on docs where `source` exists and status is "stale"
+
+2. **For each stale doc**:
+   - Fetch fresh content: `hu utils fetch-html <source_url> -c`
+   - Compare with existing content
+   - If meaningfully changed, update the file
+
+3. **Check for new reference links**:
+   - Identify links in fetched content not in `additional_sources`
+   - Fetch 1-3 promising new links
+   - Add valuable new content
+
+4. **Re-fetch existing additional sources**:
+   - Fetch each additional source URL
+   - Update if changed, remove if 404
+
+5. **Update frontmatter**:
+   - Set `fetched` date to today (YYYY-MM-DD)
+   - Add/remove `additional_sources` as needed
+
+6. **Commit changes** (project only):
+   ```bash
+   git add ./doc/ ./document-manifest.toml
+   git commit -m "docs: sync {n} documents"
+   ```
+
+## Change Detection
+
+Consider content "changed" if:
+- New sections or headings added
+- Code examples modified
+- API signatures changed
+- Deprecation notices added
+
+Ignore:
+- Minor wording tweaks
+- Formatting/whitespace changes
+- Navigation elements

package/commands/docs/update.md

@@ -0,0 +1,49 @@
+Update downloaded documentation from sources. Arguments: [target]
+
+Simple refresh of existing docs from their source URLs.
+
+## Usage
+
+- `/docs:update` - Update project docs
+- `/docs:update global` - Update global docs
+- `/docs:update all` - Update everything
+- `/docs:update doc/api.md` - Update specific file
+
+## CLI Tools Available
+
+```bash
+# Scan to find docs with sources
+hu docs scan [target] [-j]
+
+# Fetch fresh content
+hu utils fetch-html <url> -c
+```
+
+## Process
+
+1. **Scan targets**: `hu docs scan [target] -j`
+   - Get list of docs with source URLs
+
+2. **For each doc with a source**:
+   - Fetch: `hu utils fetch-html <source_url> -c`
+   - Compare with existing file
+   - If changed: update content and `fetched` date in frontmatter
+
+3. **Update frontmatter**:
+   ```yaml
+   ---
+   source: https://example.com/docs
+   fetched: 2026-01-13
+   ---
+   ```
+
+4. **Commit** (project only):
+   ```bash
+   git add ./doc/
+   git commit -m "docs: update documentation"
+   ```
+
+## Difference from /docs:sync
+
+- **update**: Simple refresh from existing sources only
+- **sync**: Also follows new links, expands content, more intelligent merging

package/commands/plans/clear.md

@@ -0,0 +1,23 @@
+Delete all plans from `~/.claude/plans/`.
+
+## Process
+
+1. List all `.md` files in `~/.claude/plans/`
+2. If none exist, inform user and stop
+3. Show plans to delete (filename and title)
+4. Ask for confirmation
+5. Delete all `.md` files
+6. Confirm with count
+
+## Example
+
+```
+Found 3 plans to delete:
+- crispy-crafting-pnueli.md - Generate GLaDOS Persona
+- magical-nibbling-spark.md - Context Detection
+- mellow-kindling-acorn.md - Documentation Indexing
+
+Delete all 3 plans? (This cannot be undone)
+```
+
+Run this now.

package/commands/plans/create.md

@@ -0,0 +1,71 @@
+Create implementation plan from user requirements.
+
+## Pre-Check
+
+If `./PLAN.md` or `./TODO.md` exist and are non-empty:
+1. Read existing file(s)
+2. Output summary before proceeding:
+   ```
+   ## Existing Plan Summary
+   - **Feature**: [name from existing plan]
+   - **Phases**: [count] ([list phase names])
+   - **Steps**: [total count]
+   - **Status**: [count completed]/[total] steps done (from TODO.md checkboxes)
+   ```
+3. Ask user: "Overwrite existing plan or append new phase?"
+
+## Task
+
+1. Create or overwrite `./PLAN.md` with structured implementation plan
+2. Create or overwrite `./TODO.md` with checklist summary
+
+## Output Format
+
+### PLAN.md Structure
+
+```markdown
+# Plan: [Feature Name]
+
+## Phase 1: [Phase Name]
+
+### Description
+[One paragraph explaining phase objective and deliverables]
+
+### Steps
+
+#### Step 1.1: [Step Name]
+- **Objective**: [Single sentence goal]
+- **Files**: [List of files to create/modify]
+- **Dependencies**: [Prerequisites or None]
+- **Implementation**:
+  - [Specific action 1]
+  - [Specific action 2]
+
+#### Step 1.2: [Step Name]
+[Same structure]
+
+## Phase 2: [Phase Name]
+[Same structure]
+```
+
+### TODO.md Structure
+
+```markdown
+# TODO: [Feature Name]
+
+## Phase 1: [Phase Name]
+- [ ] Step 1.1: [Step Name]
+- [ ] Step 1.2: [Step Name]
+
+## Phase 2: [Phase Name]
+- [ ] Step 2.1: [Step Name]
+```
+
+## Guidelines
+
+- Split phases by logical milestones or deployable increments
+- Each step should be completable in one focused session
+- Include file paths relative to project root
+- List dependencies explicitly between steps
+- Use imperative verbs: Create, Implement, Add, Update, Configure
+- Omit explanatory prose; prioritize actionable specifics

package/commands/plans/list.md

@@ -0,0 +1,21 @@
+List saved plans from `~/.claude/plans/`.
+
+## Implementation
+
+Use `hu plans list`:
+
+```bash
+# Default: formatted output with titles and bullets
+hu plans list
+
+# Full preview (more bullets)
+hu plans list -f
+
+# Simple list (filenames only)
+hu plans list -s
+
+# JSON output
+hu plans list -j
+```
+
+Run the command now and display its output.

package/commands/plans/sync.md

@@ -0,0 +1,38 @@
+Sync TODO.md and PLAN.md progress trackers in current repo.
+
+Removes completed items, keeps only pending work.
+
+## Implementation
+
+Use `hu utils sync-checkboxes`:
+
+```bash
+# Process TODO.md and PLAN.md (default)
+hu utils sync-checkboxes
+
+# Dry run - show what would change
+hu utils sync-checkboxes -d
+
+# Verbose output
+hu utils sync-checkboxes -v
+
+# Process specific files
+hu utils sync-checkboxes TODO.md
+hu utils sync-checkboxes ./path/to/file.md
+
+# JSON output
+hu utils sync-checkboxes -j
+```
+
+## Cleanup rules
+
+- Section ALL complete → remove entire section
+- Section SOME complete → keep section, remove completed items
+- File ALL complete → DELETE file
+- Preserve structure for remaining work
+
+## Commits
+
+After running the script, commit changes:
+- Modified: `git add <file> && git commit -m "sync: remove completed from {filename}"`
+- Deleted: `git rm <file> && git commit -m "sync: {filename} complete, removing"`

package/commands/reinstall.md

@@ -0,0 +1,20 @@
+Reinstall hu from source.
+
+## Command
+
+```bash
+cd ~/.claude && npm install && npm link
+```
+
+This will:
+1. Install/update dependencies from package.json
+2. Rebuild TypeScript via tsx
+3. Update global symlink for `hu` binary
+
+## Verify
+
+```bash
+hu --help
+```
+
+Run the reinstall now.