docs: update documentation and regenerate site

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

Author: josealekhine

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

@@ -485,11 +485,11 @@ 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`)      |
 
 Sessions are sorted by date (newest first) and display slug, project,
 start time, duration, turn count, and token usage.
@@ -578,16 +578,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 +606,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 +802,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**:
 

docs/context-files.md

@@ -64,7 +64,7 @@ The priority order follows a logical progression for AI tools:
 
 ---
 
-## CONSTITUTION.md
+## `CONSTITUTION.md`
 
 **Purpose:** Define hard invariants—rules that must **NEVER** be violated, 
 regardless of the task.
@@ -107,7 +107,7 @@ is wrong.
 
 ---
 
-## TASKS.md
+## `TASKS.md`
 
 **Purpose:** Track current work, planned work, and blockers.
 
@@ -183,7 +183,7 @@ session started vs completed work.
 
 ---
 
-## DECISIONS.md
+## `DECISIONS.md`
 
 **Purpose:** Record architectural decisions with rationale so they don't
 get re-debated.
@@ -242,7 +242,7 @@ third-party libraries need type assertions.
 
 ---
 
-## LEARNINGS.md
+## `LEARNINGS.md`
 
 **Purpose:** Capture lessons learned, gotchas, and tips that shouldn't
 be forgotten.
@@ -296,7 +296,7 @@ Organize learnings by topic:
 
 ---
 
-## CONVENTIONS.md
+## `CONVENTIONS.md`
 
 **Purpose**: Document project patterns, naming conventions, and standards.
 
@@ -333,7 +333,7 @@ Organize learnings by topic:
 
 ---
 
-## ARCHITECTURE.md
+## `ARCHITECTURE.md`
 
 **Purpose**: Provide system overview and component relationships.
 
@@ -376,7 +376,7 @@ What's in scope vs out of scope for this codebase.
 
 ---
 
-## GLOSSARY.md
+## `GLOSSARY.md`
 
 **Purpose**: Define domain terms, abbreviations, and project vocabulary.
 
@@ -411,7 +411,7 @@ What's in scope vs out of scope for this codebase.
 
 ---
 
-## DRIFT.md
+## `DRIFT.md`
 
 **Purpose**: Define signals that the context is stale and needs updating.
 
@@ -460,7 +460,7 @@ Update context when:
 
 ---
 
-## AGENT_PLAYBOOK.md
+## `AGENT_PLAYBOOK.md`
 
 **Purpose**: Explicit instructions for how AI tools should read, apply, 
 and update context.

docs/index.md

@@ -27,9 +27,15 @@ conventions, and learnings:
 **Open source is better together**.
 
 <!-- the long line is required for zensical to render block quote -->
-> ⭐️ **If the idea behind `ctx` resonates, a star helps it reach engineers who run into context drift every day.**
-> 
-> → https://github.com/ActiveMemory/ctx
+
+!!! tip "Help `ctx` Change How AI Remembers"
+    **If the idea behind `ctx` resonates, a star helps it reach engineers 
+    who run into context drift every day.**
+
+    → https://github.com/ActiveMemory/ctx
+
+    `ctx` is free and open source software, and **contributions are always
+    welcome** and appreciated.
 
 Join the community to ask questions, share feedback, and connect with
 other users: