Merge pull request #5 from ActiveMemory/feature/cleanup-2

cleanup before v0.2.0 release cut.

Author: josealekhine

.context/TASKS.md

@@ -1,3 +1,5 @@
+- [ ] Add integration tests for CLI commands (drift, sync, decision, learnings, serve, recall) - test actual file operations and command execution #added:2026-02-01-062541
+
 # Tasks — Context CLI
 
 # Tasks

VERSION

@@ -1 +1 @@
-0.1.3
+0.2.0

docs/blog/2026-01-27-building-ctx-using-ctx.md

@@ -4,12 +4,17 @@ date: 2026-01-27
 author: Jose Alekhinne
 ---
 
-*Jose Alekhinne / 2026-01-27*
+# Building ctx Using ctx
+
+![ctx](../images/ctx-banner.png)
 
-# Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development
+## A Meta-Experiment in AI-Assisted Development
 
-> What happens when you build a tool designed to give AI memory, using that very 
-same tool to remember what you are building? 
+*Jose Alekhinne / 2026-01-27*
+
+!!! question "Can a tool design itself?"
+    What happens when you build a tool designed to give AI memory, 
+    using that very same tool to remember what you are building? 
 
 This is the story of `ctx`, how it evolved from a hasty "*YOLO mode*" experiment 
 to a disciplined system for **persistent AI context**, and what I have 
@@ -29,7 +34,7 @@ Every developer who works with AI code generators knows the frustration:
 you have a deep, productive session where the AI understands your codebase, 
 your conventions, your decisions. And then you close the terminal. 
 
-Tomorrow it's a blank slate. The AI has forgotten everything.
+Tomorrow; it's a blank slate. The AI has forgotten everything.
 
 That is "*reset amnesia*", and it's not just annoying: it's expensive. 
 
@@ -52,7 +57,10 @@ Markdown files for decisions, learnings, tasks, and conventions.
 The AI reads these at session start and writes to them before the session ends.
 
 **The first commit** was just scaffolding. But within hours, the 
-**Ralph Loop**—an iterative AI development workflow—had produced a working CLI:
+[**Ralph Loop**][ralph]—an iterative AI development workflow—had produced 
+a working CLI:
+
+[ralph]: https://ctx.ist/autonomous-loop/ "Autonomous Loop"
 
 ```
 feat(cli): implement amem init command
@@ -62,10 +70,14 @@ feat(cli): implement amem agent command
 ...
 ```
 
-Fourteen core commands shipped in rapid succession. 
+Not one, not two, but a whopping **fourteen** core commands shipped in rapid 
+succession!
 
 I was YOLO'ing like there was no tomorrow:
-auto-accept every change, let the AI run free, ship features fast.
+
+* auto-accept every change, 
+* let the AI run free, 
+* ship features fast.
 
 ## The Meta-Experiment: Using `amem` to Build `amem`
 
@@ -75,8 +87,8 @@ Here's where it gets interesting: On January 20th, I asked:
 
 The answer was yes—but with a gap: 
 
-Auto-load worked (*via Claude Code's `PreToolUse` hook*), but auto-save was 
-missing. If the user quit with Ctrl+C, everything since the last manual save 
+Autoload worked (*via Claude Code's `PreToolUse` hook*), but auto-save was 
+missing. If the user quit, with Ctrl+C, everything since the last manual save 
 was lost.
 
 That session became the first real test of the system. 
@@ -95,10 +107,15 @@ development workflow. They're complementary but separate.
 
 ### 2. Two Tiers of Context Persistence
 
-| Tier      | What                        | Why                           | Where                  |
-|-----------|-----------------------------|-------------------------------|------------------------|
-| Curated   | Learnings, decisions, tasks | Quick reload, token-efficient | .context/*.md          |
-| Full dump | Entire conversation         | Safety net, nothing lost      | .context/sessions/*.md |
+| Tier      | What                        | Why                           |
+|-----------|-----------------------------|-------------------------------|
+| Curated   | Learnings, decisions, tasks | Quick reload, token-efficient |
+| Full dump | Entire conversation         | Safety net, nothing lost      |
+
+| Where                  |
+|------------------------|
+| .context/*.md          |
+| .context/sessions/*.md |
 ```
 
 This session file—written by the AI to preserve its own context—became the 
@@ -161,7 +178,8 @@ Human-Guided Mode (Post-040ce99)
 - Canonical naming: Package name = folder name
 ```
 
-The fix required a human-guided refactoring session.
+The fix required a **human-guided refactoring session**. I continued to do
+that before every major release, from that point on.
 
 We introduced `internal/config/config.go` with semantic prefixes:
 
@@ -178,8 +196,7 @@ const (
 What I begrudgingly learned was: 
 **YOLO mode is effective for velocity but accumulates debt**. 
 
-So I took a mental note to schedule **periodic consolidation sessions** 
-from that point onward.
+So I took a mental note to schedule **periodic consolidation sessions**.
 
 ## The Dogfooding Test That Failed
 
@@ -220,7 +237,7 @@ So I added:
 ## The Constitution versus Conventions
 
 As lessons accumulated, there was the temptation to add everything to 
-`CONSTITUTION.md` as "inviolable rules". 
+`CONSTITUTION.md` as "*inviolable rules*". 
 
 But I resisted.
 
@@ -307,7 +324,7 @@ Each **session file** is a timestamped Markdown with:
 * Tasks for the next session
 * Technical context (*platform, versions*)
 
-These files are **not auto-loaded** (*that would bust the token budget*). 
+These files are **not autoloaded** (*that would bust the token budget*). 
 
 They are what I see as the "*archaeological record*" of `ctx`:
 When the AI needs deeper information about why something was done, it
@@ -347,7 +364,8 @@ and LEARNINGS.md.
 **Context**: Original implementation hardcoded absolute paths in hooks.
 This breaks when sharing configs with other developers.
 
-**Decision**: Hooks use `ctx` from PATH. `ctx init` checks PATH before proceeding.
+**Decision**: Hooks use `ctx` from PATH. `ctx init` checks PATH before 
+proceeding.
 ```
 
 **Generic core with Claude enhancements (2026-01-20)**
@@ -368,8 +386,10 @@ forgotten. Each has Context, Lesson, and Application sections:
 **CGO on ARM64**
 
 ```markdown
-**Context**: `go test` failed with `gcc: error: unrecognized command-line option '-m64'`
-**Lesson**: On ARM64 Linux, CGO causes cross-compilation issues. Always use `CGO_ENABLED=0`.
+**Context**: `go test` failed with 
+`gcc: error: unrecognized command-line option '-m64'`
+**Lesson**: On ARM64 Linux, CGO causes cross-compilation issues. 
+Always use `CGO_ENABLED=0`.
 ```
 
 **Claude Code skills format**
@@ -382,7 +402,8 @@ frontmatter (*description, argument-hint, allowed-tools*). Body is the prompt.
 **"Do you remember?" handling**
 
 ```markdown
-**Lesson**: In a `ctx`-enabled project, "*do you remember?*" has an obvious meaning:
+**Lesson**: In a `ctx`-enabled project, "*do you remember?*" 
+has an obvious meaning:
 check the `.context/` files. Don't ask for clarification—just do it.
 ```
 
@@ -487,7 +508,16 @@ If you are reading this, chances are that you already have heard about `ctx`.
 [github.com/ActiveMemory/ctx](https://github.com/ActiveMemory/ctx),
 * and the documentation lives at [ctx.ist](https://ctx.ist).
 
-If you're a mere mortal tired of reset amnesia, give `ctx` a try. 
+!!! note "Session Records are a Gold Mine"
+By the time of this writing, I have **more than 70 megabytes** of
+**text-only** session capture, spread across >100 markdown and JSONL
+files.
+
+    I am analyzing, synthesizing, encriching them with AI, running RAG
+    (*Retrieval-Augmented Generation*) models on them, and the outcome
+    surprises me every day.
+
+If you are a mere mortal tired of reset amnesia, give `ctx` a try. 
 
 And when you do, check `.context/sessions/` sometime. 
 

docs/blog/index.md

@@ -3,7 +3,7 @@ title: Blog
 icon: lucide/newspaper
 ---
 
-# Blog
+![ctx](../images/ctx-banner.png)
 
 Stories, insights, and lessons learned from building and using ctx.
 
@@ -25,4 +25,4 @@ persistence, architectural decisions
 
 ---
 
-*More posts coming soon.*
+*more posts are coming soon*

docs/cli-reference.md

@@ -348,6 +348,49 @@ ctx compact --no-auto-save
 
 ---
 
+### `ctx completion`
+
+Generate shell autocompletion scripts.
+
+```bash
+ctx completion <shell>
+```
+
+#### Subcommands
+
+| Shell        | Command                  |
+|--------------|--------------------------|
+| `bash`       | `ctx completion bash`    |
+| `zsh`        | `ctx completion zsh`     |
+| `fish`       | `ctx completion fish`    |
+| `powershell` | `ctx completion powershell` |
+
+#### Installation
+
+=== "Bash"
+
+    ```bash
+    # Add to ~/.bashrc
+    source <(ctx completion bash)
+    ```
+
+=== "Zsh"
+
+    ```bash
+    # Add to ~/.zshrc
+    source <(ctx completion zsh)
+    ```
+
+=== "Fish"
+
+    ```bash
+    ctx completion fish | source
+    # Or save to completions directory
+    ctx completion fish > ~/.config/fish/completions/ctx.fish
+    ```
+
+---
+
 ### `ctx tasks`
 
 Manage task archival and snapshots.
@@ -485,11 +528,12 @@ ctx recall list [flags]
 
 **Flags**:
 
-| Flag              | Short | Description                              |
-|-------------------|-------|------------------------------------------|
-| `--limit`         | `-n`  | Maximum sessions to display (default: 20)|
-| `--project`       | `-p`  | Filter by project name                   |
-| `--tool`          | `-t`  | Filter by tool (e.g., `claude-code`)     |
+| Flag             | Short | Description                               |
+|------------------|-------|-------------------------------------------|
+| `--limit`        | `-n`  | Maximum sessions to display (default: 20) |
+| `--project`      | `-p`  | Filter by project name                    |
+| `--tool`         | `-t`  | Filter by tool (e.g., `claude-code`)      |
+| `--all-projects` |       | Include sessions from all projects        |
 
 Sessions are sorted by date (newest first) and display slug, project,
 start time, duration, turn count, and token usage.
@@ -513,10 +557,11 @@ ctx recall show [session-id] [flags]
 
 **Flags**:
 
-| Flag       | Description                        |
-|------------|------------------------------------|
-| `--latest` | Show the most recent session       |
-| `--full`   | Show full message content          |
+| Flag             | Description                        |
+|------------------|------------------------------------|
+| `--latest`       | Show the most recent session       |
+| `--full`         | Show full message content          |
+| `--all-projects` | Search across all projects         |
 
 The session ID can be a full UUID, partial match, or session slug name.
 
@@ -539,10 +584,11 @@ ctx recall export [session-id] [flags]
 
 **Flags**:
 
-| Flag      | Description                              |
-|-----------|------------------------------------------|
-| `--all`   | Export all sessions                      |
-| `--force` | Overwrite existing files                 |
+| Flag             | Description                              |
+|------------------|------------------------------------------|
+| `--all`          | Export all sessions                      |
+| `--force`        | Overwrite existing files                 |
+| `--all-projects` | Export from all projects                 |
 
 Exported files include session metadata, tool usage summary, and the full
 conversation. Existing files are skipped by default to preserve your edits.
@@ -578,16 +624,17 @@ ctx journal site [flags]
 
 **Flags**:
 
-| Flag       | Short | Description                              |
-|------------|-------|------------------------------------------|
+| Flag       | Short | Description                                       |
+|------------|-------|---------------------------------------------------|
 | `--output` | `-o`  | Output directory (default: .context/journal-site) |
-| `--build`  |       | Run zensical build after generating      |
-| `--serve`  |       | Run zensical serve after generating      |
+| `--build`  |       | Run zensical build after generating               |
+| `--serve`  |       | Run zensical serve after generating               |
 
-Creates a zensical-compatible site structure with an index page listing
+Creates a `zensical`-compatible site structure with an index page listing
 all sessions by date, and individual pages for each journal entry.
 
-Requires zensical to be installed for `--build` or `--serve`:
+Requires `zensical` to be installed for `--build` or `--serve`:
+
 ```bash
 pip install zensical
 ```
@@ -605,15 +652,16 @@ ctx journal site --serve            # Generate and serve locally
 
 ### `ctx serve`
 
-Serve a static site locally via zensical.
+Serve a static site locally via `zensical`.
 
 ```bash
 ctx serve [directory]
 ```
 
 If no directory is specified, serves the journal site (`.context/journal-site`).
 
-Requires zensical to be installed:
+Requires `zensical` to be installed:
+
 ```bash
 pip install zensical
 ```
@@ -800,13 +848,13 @@ ctx loop [flags]
 
 **Flags**:
 
-| Flag                     | Short | Description                                     | Default            |
-|--------------------------|-------|-------------------------------------------------|--------------------|
-| `--tool <tool>`          | `-t`  | AI tool: `claude`, `aider`, or `generic`        | `claude`           |
-| `--prompt <file>`        | `-p`  | Prompt file to use                              | `PROMPT.md`        |
-| `--max-iterations <n>`   | `-n`  | Maximum iterations (0 = unlimited)              | `0`                |
-| `--completion <signal>`  | `-c`  | Completion signal to detect                     | `SYSTEM_CONVERGED` |
-| `--output <file>`        | `-o`  | Output script filename                          | `loop.sh`          |
+| Flag                     | Short | Description                              | Default            |
+|--------------------------|-------|------------------------------------------|--------------------|
+| `--tool <tool>`          | `-t`  | AI tool: `claude`, `aider`, or `generic` | `claude`           |
+| `--prompt <file>`        | `-p`  | Prompt file to use                       | `PROMPT.md`        |
+| `--max-iterations <n>`   | `-n`  | Maximum iterations (0 = unlimited)       | `0`                |
+| `--completion <signal>`  | `-c`  | Completion signal to detect              | `SYSTEM_CONVERGED` |
+| `--output <file>`        | `-o`  | Output script filename                   | `loop.sh`          |
 
 **Example**: