chore: consolidate project updates and documentation

- Update CLI implementations across all commands
- Refresh context files (TASKS, DECISIONS, LEARNINGS, etc.)
- Update specs and documentation for accuracy
- Add site images for documentation
- Update templates and hooks
- Remove PROMPT_plan.md (consolidated)
- Update dependencies (go.mod/go.sum)

Signed-off-by: Jose Alekhinne <alekhinejose@gmail.com>

Author: josealekhine

.claude/hooks/auto-save-session.sh

@@ -1,10 +1,10 @@
 #!/bin/bash
 
-#   /    Context:
+#   /    Context:                     https://ctx.ist
 # ,'`./    do you remember?
 # `.,'\
 #   \    Copyright 2025-present Context contributors.
-#        SPDX-License-Identifier: Apache-2.0
+#                 SPDX-License-Identifier: Apache-2.0
 
 # Auto-save session transcript on exit (including Ctrl+C)
 # This hook is triggered by Claude Code's SessionEnd event

.context/AGENT_PLAYBOOK.md

@@ -12,16 +12,20 @@
 
 ## Session History
 
-**IMPORTANT**: Check `.context/sessions/` for full conversation dumps from previous sessions.
+**IMPORTANT**: Check `.context/sessions/` for full conversation dumps from 
+previous sessions.
 
 If you're confused about context or need a deep dive into past discussions:
 ```
 ls .context/sessions/
 ```
 
-**Curated session files** are named `YYYY-MM-DD-HHMMSS-<topic>.md` (e.g., `2025-01-20-164600-feature-discussion.md`). These are updated throughout the session.
+**Curated session files** are named `YYYY-MM-DD-HHMMSS-<topic>.md`
+(e.g., `2026-01-20-164600-feature-discussion.md`). 
+These are updated throughout the session.
 
-**Auto-snapshot files** are named `YYYY-MM-DD-HHMMSS-<event>.jsonl` (e.g., `2025-01-20-170830-pre-compact.jsonl`). These are immutable once created.
+**Auto-snapshot files** are named `YYYY-MM-DD-HHMMSS-<event>.jsonl` 
+(e.g., `2026-01-20-170830-pre-compact.jsonl`). These are immutable once created.
 
 **Auto-save triggers** (for Claude Code users):
 - **SessionEnd hook** → auto-saves transcript on exit, including Ctrl+C
@@ -32,7 +36,8 @@ See `.claude/hooks/auto-save-session.sh` for the implementation.
 
 ## Session File Structure (Suggested)
 
-Adapt this structure based on session type. Not all sections are needed for every session.
+Adapt this structure based on session type. 
+Not all sections are needed for every session.
 
 ### Core Sections (Always Include)
 ```markdown
@@ -56,14 +61,14 @@ What to pick up next
 
 ### Context-Dependent Sections
 
-| Session Type | Additional Sections |
-|--------------|---------------------|
-| **Feature discussion** | Requirements, Design options, Implementation plan |
-| **Bug investigation** | Symptoms, Root cause, Fix applied, Prevention |
+| Session Type              | Additional Sections                               |
+|---------------------------|---------------------------------------------------|
+| **Feature discussion**    | Requirements, Design options, Implementation plan |
+| **Bug investigation**     | Symptoms, Root cause, Fix applied, Prevention     |
 | **Architecture decision** | Context, Options considered, Trade-offs, Decision |
-| **Exploration/Research** | Questions, Findings, Open questions |
-| **Planning** | Goals, Milestones, Dependencies, Risks |
-| **Quick fix** | Problem, Solution, Files changed (minimal format) |
+| **Exploration/Research**  | Questions, Findings, Open questions               |
+| **Planning**              | Goals, Milestones, Dependencies, Risks            |
+| **Quick fix**             | Problem, Solution, Files changed (minimal format) |
 
 ### When to Go Minimal
 
@@ -87,13 +92,13 @@ For complex sessions (architecture, debugging), include:
 
 ## When to Update Memory
 
-| Event | Action |
-|-------|--------|
-| Made architectural decision | Add to DECISIONS.md |
-| Discovered gotcha/bug | Add to LEARNINGS.md |
-| Established new pattern | Add to CONVENTIONS.md |
-| Completed task | Mark [x] in TASKS.md |
-| Had important discussion | Save to sessions/ |
+| Event                       | Action                |
+|-----------------------------|-----------------------|
+| Made architectural decision | Add to DECISIONS.md   |
+| Discovered gotcha/bug       | Add to LEARNINGS.md   |
+| Established new pattern     | Add to CONVENTIONS.md |
+| Completed task              | Mark [x] in TASKS.md  |
+| Had important discussion    | Save to sessions/     |
 
 ## Before Session Ends
 
@@ -103,7 +108,7 @@ For complex sessions (architecture, debugging), include:
 
 ## How to Avoid Hallucinating Memory
 
-Never assume. If you don't see it in files, you don't know it.
+Never assume: If you don't see it in files, you don't know it.
 
 - Don't claim "we discussed X" without file evidence
 - Don't invent history - check sessions/ for actual discussions

.context/CONSTITUTION.md

@@ -18,7 +18,8 @@ These rules are INVIOLABLE. If a task requires violating these, the task is wron
 
 ## TASKS.md Structure Invariants
 
-TASKS.md must remain a replayable checklist. Uncheck all items and re-run the loop = verify/redo all tasks in order.
+TASKS.md must remain a replayable checklist. Uncheck all items and re-run 
+the loop = verify/redo all tasks in order.
 
 - [ ] **Never move tasks** — tasks stay in their Phase section permanently
 - [ ] **Never remove Phase headers** — Phase labels provide structure and order

.context/CONVENTIONS.md

@@ -10,16 +10,20 @@
 
 ### Doc-Impact Rule
 
-**When to update docs:** Any change to CLI commands, flags, or behavior requires updating the corresponding documentation in `docs/`.
+**When to update docs:** Any change to CLI commands, flags, or behavior 
+requires updating the corresponding documentation in `docs/`.
 
 **Mapping:**
-| Code Change | Doc Update Required |
-|-------------|---------------------|
-| `internal/cli/*.go` command changes | `docs/cli-reference.md` |
-| `.context/` file format changes | `docs/context-files.md` |
-| AI tool integration changes | `docs/integrations.md` |
-| New features | `docs/index.md` (if user-facing) |
 
-**How to remember:** When marking a CLI-related task complete, check if `docs/` needs updating. Add `#doc-impact` tag to tasks that affect documentation.
+| Code Change                         | Doc Update Required              |
+|-------------------------------------|----------------------------------|
+| `internal/cli/*.go` command changes | `docs/cli-reference.md`          |
+| `.context/` file format changes     | `docs/context-files.md`          |
+| AI tool integration changes         | `docs/integrations.md`           |
+| New features                        | `docs/index.md` (if user-facing) |
 
-**Drift detection:** Run `ctx drift` — it will warn if `internal/cli/` is newer than `docs/cli-reference.md`.
+**How to remember:** When marking a CLI-related task complete, check if `docs/`
+needs updating. Add `#doc-impact` tag to tasks that affect documentation.
+
+**Drift detection:** Run `ctx drift` — it will warn if `internal/cli/` 
+is newer than `docs/cli-reference.md`.

.context/DECISIONS.md

@@ -1,12 +1,14 @@
 # Decisions
 
-## [2025-01-20] Generic Core with Optional Claude Code Enhancements
+## [2026-01-20] Generic Core with Optional Claude Code Enhancements
 
 **Status**: Accepted
 
-**Context**: `ctx` should work with any AI tool, but Claude Code users could benefit from deeper integration (auto-load, auto-save via hooks).
+**Context**: `ctx` should work with any AI tool, but Claude Code users could 
+benefit from deeper integration (auto-load, auto-save via hooks).
 
-**Decision**: Keep `ctx` generic as the core tool, but provide optional Claude Code-specific enhancements:
+**Decision**: Keep `ctx` generic as the core tool, but provide optional 
+Claude Code-specific enhancements:
 - `ctx hook claude-code` generates Claude-specific configs
 - `.claude/hooks/` contains Claude Code hook scripts
 - Features work without Claude Code, but are enhanced with it
@@ -24,11 +26,12 @@
 
 ---
 
-## [2025-01-20] Always Generate Claude Hooks in Init (No Flag Needed)
+## [2026-01-20] Always Generate Claude Hooks in Init (No Flag Needed)
 
 **Status**: Accepted (to be implemented)
 
-**Context**: Setting up Claude Code hooks manually is error-prone. Considered `--claude` flag but realized it's unnecessary.
+**Context**: Setting up Claude Code hooks manually is error-prone. 
+Considered `--claude` flag but realized it's unnecessary.
 
 **Decision**: `ctx init` ALWAYS creates `.claude/hooks/` alongside `.context/`:
 ```bash
@@ -50,17 +53,18 @@ ctx init    # Creates BOTH .context/ AND .claude/hooks/
 
 ---
 
-## [2025-01-20] Two-Tier Context Persistence Model
+## [2026-01-20] Two-Tier Context Persistence Model
 
 **Status**: Accepted
 
-**Context**: Need to persist context across sessions. Token budgets limit what can be loaded. But nothing should be truly lost.
+**Context**: Need to persist context across sessions. Token budgets limit
+what can be loaded. But nothing should be truly lost.
 
 **Decision**: Implement two tiers of persistence:
 
-| Tier | Purpose | Location | Token Cost |
-|------|---------|----------|------------|
-| **Curated** | Quick context reload | `.context/*.md` | Low (budgeted) |
+| Tier          | Purpose                 | Location                 | Token Cost             |
+|---------------|-------------------------|--------------------------|------------------------|
+| **Curated**   | Quick context reload    | `.context/*.md`          | Low (budgeted)         |
 | **Full dump** | Safety net, archaeology | `.context/sessions/*.md` | Zero (not auto-loaded) |
 
 **Rationale**:
@@ -76,13 +80,15 @@ ctx init    # Creates BOTH .context/ AND .claude/hooks/
 
 ---
 
-## [2025-01-20] Session Filename Format: YYYY-MM-DD-HHMMSS-topic.md
+## [2026-01-20] Session Filename Format: YYYY-MM-DD-HHMMSS-topic.md
 
 **Status**: Accepted
 
-**Context**: Multiple sessions per day would overwrite each other. Also, multiple compacts in the same minute could collide.
+**Context**: Multiple sessions per day would overwrite each other. 
+Also, multiple compacts in the same minute could collide.
 
-**Decision**: Use `YYYY-MM-DD-HHMMSS-<topic>.md` format for session files. Two file types:
+**Decision**: Use `YYYY-MM-DD-HHMMSS-<topic>.md` format for session files. 
+Two file types:
 - **Curated sessions**: `HHMMSS-<topic>.md` - updated throughout session
 - **Auto-snapshots**: `HHMMSS-<event>.jsonl` - immutable once created
 
@@ -99,11 +105,12 @@ ctx init    # Creates BOTH .context/ AND .claude/hooks/
 
 ---
 
-## [2025-01-20] Auto-Save Before Compact
+## [2026-01-20] Auto-Save Before Compact
 
 **Status**: Accepted (to be implemented)
 
-**Context**: `ctx compact` archives old tasks. Information could be lost if not captured.
+**Context**: `ctx compact` archives old tasks. Information could be 
+lost if not captured.
 
 **Decision**: `ctx compact` should auto-save a session dump before archiving:
 1. Save current state to `.context/sessions/YYYY-MM-DD-HHMM-pre-compact.md`
@@ -121,16 +128,19 @@ ctx init    # Creates BOTH .context/ AND .claude/hooks/
 
 ---
 
-## [2025-01-20] Handle CLAUDE.md Creation/Merge in ctx init
+## [2026-01-20] Handle CLAUDE.md Creation/Merge in ctx init
 
 **Status**: Accepted (to be implemented)
 
-**Context**: Both `claude init` and `ctx init` want to create/modify CLAUDE.md. Users of ctx will likely want ctx's context-aware version, but may already have a CLAUDE.md from `claude init`.
+**Context**: Both `claude init` and `ctx init` want to create/modify CLAUDE.md. 
+Users of ctx will likely want ctx's context-aware version, 
+but may already have a CLAUDE.md from `claude init`.
 
 **Decision**: `ctx init` handles CLAUDE.md intelligently:
 - **No CLAUDE.md exists** → Create it with ctx's context-loading template
 - **CLAUDE.md exists** → Don't overwrite. Instead:
-  1. **Backup first** → Copy to `CLAUDE.md.<unix_timestamp>.bak` (e.g., `CLAUDE.md.1737399000.bak`)
+  1. **Backup first** → Copy to `CLAUDE.md.<unix_timestamp>.bak` 
+     (e.g., `CLAUDE.md.1737399000.bak`)
   2. Check if it already has ctx content (idempotent check via marker comment)
   3. If not, output the snippet to append and offer to merge
   4. `ctx init --merge` flag to auto-append without prompting
@@ -154,7 +164,9 @@ ctx init    # Creates BOTH .context/ AND .claude/hooks/
 
 **Status**: Accepted (implemented)
 
-**Context**: Original implementation hardcoded absolute paths in hooks (e.g., `/home/parallels/WORKSPACE/ActiveMemory/dist/ctx-linux-arm64`). This breaks when:
+**Context**: Original implementation hardcoded absolute paths in hooks 
+(e.g., `/home/parallels/WORKSPACE/ActiveMemory/dist/ctx-linux-arm64`). 
+This breaks when:
 - Sharing configs with other developers
 - Moving projects
 - Dogfooding in separate directories
@@ -177,7 +189,7 @@ ctx init    # Creates BOTH .context/ AND .claude/hooks/
 
 ---
 
-## [2025-01-20] Use SessionEnd Hook for Auto-Save
+## [2026-01-20] Use SessionEnd Hook for Auto-Save
 
 **Status**: Accepted (implemented)
 
@@ -201,17 +213,22 @@ ctx init    # Creates BOTH .context/ AND .claude/hooks/
 
 ---
 
-## [2025-01-21] Separate Orchestrator Directive from Agent Tasks
+## [2026-01-21] Separate Orchestrator Directive from Agent Tasks
 
 **Status**: Accepted
 
-**Context**: Two task systems existed: `IMPLEMENTATION_PLAN.md` (Ralph Loop orchestrator) and `.context/TASKS.md` (ctx's own context). Ralph would find IMPLEMENTATION_PLAN.md complete and exit, ignoring .context/TASKS.md.
+**Context**: Two task systems existed: `IMPLEMENTATION_PLAN.md` 
+(Ralph Loop orchestrator) and `.context/TASKS.md` (ctx's own context). 
+Ralph would find IMPLEMENTATION_PLAN.md complete and exit, 
+ignoring .context/TASKS.md.
 
 **Decision**: Clean separation of concerns:
 - **`.context/TASKS.md`** = Agent's mind. Tasks the agent decided need doing.
-- **`IMPLEMENTATION_PLAN.md`** = Orchestrator's directive. A single meta-task: "Check your tasks."
+- **`IMPLEMENTATION_PLAN.md`** = Orchestrator's directive. 
+  A single meta-task: "Check your tasks."
 
-The orchestrator doesn't maintain a parallel ledger — it just tells the agent to check its own mind.
+The orchestrator doesn't maintain a parallel ledger — it just tells the 
+agent to check its own mind.
 
 **Rationale**:
 - Agent autonomy: the agent owns its task list

.context/DRIFT.md

@@ -19,8 +19,8 @@
 
 ## Staleness Indicators
 
-| File | Stale If | Action |
-|------|----------|--------|
-| `docs/cli-reference.md` | CLI source newer | Review and update |
-| `docs/context-files.md` | Templates changed | Review and update |
-| `docs/integrations.md` | Hook logic changed | Review and update |
+| File                    | Stale If           | Action            |
+|-------------------------|--------------------|-------------------|
+| `docs/cli-reference.md` | CLI source newer   | Review and update |
+| `docs/context-files.md` | Templates changed  | Review and update |
+| `docs/integrations.md`  | Hook logic changed | Review and update |

.context/TASKS.md

@@ -42,6 +42,7 @@
 - [x] Document session persistence in AGENT_PLAYBOOK.md
 
 ### Phase 7: Testing & Verification `#priority:high` `#area:quality`
+- [ ] Add headers to all files
 - [ ] Add integration tests — invoke actual binary, verify output
   - [ ] `ctx init` creates expected files
   - [ ] `ctx status` returns valid status (not just help text)
@@ -95,13 +96,21 @@
 - [x] Document Claude Code integration in README
 - [x] Add "Dogfooding Guide" — how to use ctx on ctx itself
 - [x] Document session auto-save setup for new users
-- [ ] Create actual documentation site in `docs/` folder
-  - [ ] Getting started guide
-  - [ ] CLI command reference
-  - [ ] Context file format reference
-  - [ ] Integration guides (Claude Code, Cursor, Aider, etc.)
-  - [ ] Ralph Loop pairing guide
+- [x] Create actual documentation site in `docs/` folder
+  - [x] Getting started guide
+  - [x] CLI command reference
+  - [x] Context file format reference
+  - [x] Integration guides (Claude Code, Cursor, Aider, etc.)
+  - [x] Ralph Loop pairing guide
 - [ ] Set up Cloudflare Pages to serve docs at ctx.ist
+- [ ] Review docs/ and README.md for accuracy and completeness `#human-in-the-loop`
+  - Verify CLI examples work as documented
+  - Check for inconsistencies between README.md and docs/
+  - Requires human confirmation before marking complete
+- [ ] Simplify `docs/index.md` to avoid README.md duplication `#blocked-by:ctx.ist-live`
+  - Keep minimal intro + installation
+  - Link to full docs at ctx.ist for details
+  - Reduces drift between README.md and docs/
 
 ## Blocked
 

AGENTS.md

@@ -4,7 +4,8 @@
 
 **You have NO conversational memory. Your memory IS the file system.**
 
-Everything important must be written to files. Future iterations depend entirely on what you write now.
+Everything important must be written to files. Future iterations depend 
+entirely on what you write now.
 
 ## Context Read Order
 

CLAUDE.md

@@ -23,14 +23,14 @@ This project uses Context (ctx) for context persistence across sessions.
 
 ## Context Files
 
-| File | Purpose |
-|------|---------|
-| `.context/CONSTITUTION.md` | Hard rules - NEVER violate |
-| `.context/TASKS.md` | Current work items |
-| `.context/DECISIONS.md` | Architectural decisions with rationale |
-| `.context/LEARNINGS.md` | Gotchas, tips, lessons learned |
-| `.context/CONVENTIONS.md` | Code patterns and standards |
-| `.context/sessions/` | **Full conversation dumps** - check here for deep context |
+| File                       | Purpose                                                   |
+|----------------------------|-----------------------------------------------------------|
+| `.context/CONSTITUTION.md` | Hard rules - NEVER violate                                |
+| `.context/TASKS.md`        | Current work items                                        |
+| `.context/DECISIONS.md`    | Architectural decisions with rationale                    |
+| `.context/LEARNINGS.md`    | Gotchas, tips, lessons learned                            |
+| `.context/CONVENTIONS.md`  | Code patterns and standards                               |
+| `.context/sessions/`       | **Full conversation dumps** - check here for deep context |
 
 ## Before Session Ends
 
@@ -50,7 +50,8 @@ CGO_ENABLED=0 go test ./...                   # Run tests
 
 ## This Project
 
-Context (`ctx`) is a CLI tool for persistent AI context. It was built using the Ralph Loop technique.
+Context (`ctx`) is a CLI tool for persistent AI context. It was built using 
+the Ralph Loop technique.
 
 - **ctx** = context management tool (creates `.context/`)
 - **Ralph Loop** = iterative AI development workflow (uses PROMPT.md)