ActiveMemory · josealekhine · Apr 14, 2026 · Apr 9, 2026 · Apr 14, 2026
@@ -1,7 +1,7 @@
 ---
 name: _ctx-backup
 description: "Backup project context and global Claude data to SMB share. Use before risky operations, at end of session, or on request."
-allowed-tools: Bash(ctx system backup*), Bash(ls /tmp/ctx-backup*)
+allowed-tools: Bash(ctx backup*), Bash(ls /tmp/ctx-backup*)
 ---
 
 Backup `.context/`, `.claude/`, `ideas/`, and `~/.claude/` to
@@ -44,19 +44,19 @@ Based on the argument, run the appropriate command:
 
 ```bash
 # For "project"
-ctx system backup --scope project
+ctx backup --scope project
 
 # For "global"
-ctx system backup --scope global
+ctx backup --scope global
 
 # For "all" or no argument
-ctx system backup --scope all
+ctx backup --scope all
 ```
 
 ## Process
 
 1. Parse the argument (default to `all` if none provided)
-2. Run the appropriate `ctx system backup` command
+2. Run the appropriate `ctx backup` command
 3. Report the archive path and size from the output
 4. Confirm success to the user
 

@@ -256,3 +256,9 @@ DO NOT UPDATE FOR:
 - Warn format strings centralized in config/warn/ — use warn.Close,
   warn.Write, warn.Remove, warn.Mkdir, warn.Rename, warn.Walk, warn.Getwd,
   warn.Readdir, warn.Marshal instead of inline format strings in log.Warn calls
+
+- Nav frontmatter title: fields must not contain ctx — frontmatter does not support backticks, so the brand stays out of nav titles entirely (Hub, not The ctx Hub). Body headings can use `ctx` since markdown supports backticks.
+
+- CLI flags and slash-commands inside headings or admonition titles must be backticked: `--keep-frontmatter=false`, `/ctx-reflect`. The title-case engine in hack/title-case-headings.py protects these patterns automatically, but authors should still backtick at write time for clarity.
+
+- File extensions inside headings must be backticked when title-case capitalization would otherwise apply: write `CONSTITUTION.md`, not CONSTITUTION.Md. The title-case engine refuses to capitalize lowercase tokens following a literal . dot, but explicit backticks remain the clearest signal.
@@ -3,6 +3,9 @@
 <!-- INDEX:START -->
 | Date | Decision |
 |----|--------|
+| 2026-04-14 | doc.go quality floor: behavior-grounded, ~25-100 body lines, related-packages section required |
+| 2026-04-14 | Bootstrap stays under ctx system bootstrap (reverted experimental top-level promotion) |
+| 2026-04-14 | Title Case style for docs is AP-leaning with explicit ambiguity carve-outs |
 | 2026-04-13 | Walk boundary uses git as a hint, not a requirement |
 | 2026-04-11 | Journal stays local; LEARNINGS.md is the shareable layer |
 | 2026-04-11 | `Entry.Author` is server-authoritative, not client-authoritative |
@@ -122,6 +125,48 @@ For significant decisions:
 
 -->
 
+## [2026-04-14-010205] doc.go quality floor: behavior-grounded, ~25-100 body lines, related-packages section required
+
+**Status**: Accepted
+
+**Context**: About 140 doc.go files were rewritten this session. User flagged the original 5-line Key exports + See source files + Part of subsystem pattern as lazy minimum effort.
+
+**Decision**: doc.go quality floor: behavior-grounded, ~25-100 body lines, related-packages section required
+
+**Rationale**: Behavior-grounded rewrites (read source first, then write) are the only acceptable form for any non-trivial package. The lazy template communicates nothing a future reader cannot grep for; it satisfies tooling without adding signal.
+
+**Consequence**: Every non-trivial package's doc.go now leads with the package's actual purpose, names key behaviors, calls out non-obvious design choices (Raft-lite, two-step indirection, idempotency contracts), and lists related packages with paths. New packages should follow the same shape.
+
+---
+
+## [2026-04-14-010205] Bootstrap stays under ctx system bootstrap (reverted experimental top-level promotion)
+
+**Status**: Accepted
+
+**Context**: Mid-session promoted ctx bootstrap to top-level to make a stale CLAUDE.md instruction work. User reverted it and reaffirmed the original design.
+
+**Decision**: Bootstrap stays under ctx system bootstrap (reverted experimental top-level promotion)
+
+**Rationale**: The ctx system namespace is for agent and hook plumbing the user does not type by hand. Bootstrap is invoked by AI agents at session start; surfacing it at top-level pollutes ctx --help for humans without benefit.
+
+**Consequence**: internal/bootstrap/group.go reverted; internal/config/embed/cmd/system.go header now correctly states bootstrap is intentionally not promoted. The CLAUDE.md template across the repo (and the workspace copy) updated to reference ctx system bootstrap as canonical.
+
+---
+
+## [2026-04-14-010205] Title Case style for docs is AP-leaning with explicit ambiguity carve-outs
+
+**Status**: Accepted
+
+**Context**: Needed a deterministic Title Case engine for headings and admonition titles across docs/. User precedent (Working with AI lowercase with) ruled out strict Chicago.
+
+**Decision**: Title Case style for docs is AP-leaning with explicit ambiguity carve-outs
+
+**Rationale**: AP lowercase prepositions regardless of length matches user-approved titles. But strict AP would lowercase ambiguous prep/conj/adv words like before, after, since, until, past, near, down, up, off, hurting common cases. Carve-outs leave them at default-cap and let the engine reach a sensible result for ~95 percent of headings without manual review.
+
+**Consequence**: hack/title-case-headings.py ships an AP-leaning with ambiguity carve-outs PREPOSITIONS set. Future style changes must touch that set explicitly with reasoning. New brand or acronym additions go through the same audited pattern.
+
+---
+
 ## [2026-04-13-153617] Walk boundary uses git as a hint, not a requirement
 
 **Status**: Accepted

@@ -17,6 +17,11 @@ DO NOT UPDATE FOR:
 <!-- INDEX:START -->
 | Date | Learning |
 |----|--------|
+| 2026-04-14 | Constitution forbids context window as a deferral excuse |
+| 2026-04-14 | docs/cli/system.md and embed/cmd/system.go diverged on bootstrap promotion intent |
+| 2026-04-14 | Raft-lite trade-off is the load-bearing choice in internal/hub |
+| 2026-04-14 | AST stutter test only checks FuncDecl, not GenDecl |
+| 2026-04-14 | Brand-name handling in title-case engines must cover possessives |
 | 2026-04-13 | GPG signing from non-TTY contexts requires pinentry-mac (or equivalent) |
 | 2026-04-13 | Load average measures a queue, not CPU utilization |
 | 2026-04-13 | rc.ContextDir() is the single source of truth — fix the resolver, not callers |
@@ -115,6 +120,56 @@ DO NOT UPDATE FOR:
 
 ---
 
+## [2026-04-14-010134] Constitution forbids context window as a deferral excuse
+
+**Context**: Mid-session, agent proposed pacing through doc.go rewrites with the reasoning that context budget was tight.
+
+**Lesson**: The CONSTITUTION explicitly lists 'We are running out of context window' as a forbidden deferral phrase under No Excuse Generation. The rule is real and applies to agent self-pacing, not just user-facing answers.
+
+**Application**: When tempted to scope down because context is tight, re-read the constitution. The right move is to do the work end-to-end, not to ask the user which slice to skip.
+
+---
+
+## [2026-04-14-010134] docs/cli/system.md and embed/cmd/system.go diverged on bootstrap promotion intent
+
+**Context**: Header comment in internal/config/embed/cmd/system.go claimed bootstrap was promoted to top-level; the bootstrap.go registration never actually promoted it. Two contradictory sources of truth coexisted silently.
+
+**Lesson**: Header-comment claims about command-tree structure are unaudited; they can drift from registrations without any test failing. Trust the code, not the comment.
+
+**Application**: When evaluating any package_name namespace cleanup type claim about command structure, verify against the actual cobra registration in internal/bootstrap/group.go before acting.
+
+---
+
+## [2026-04-14-010134] Raft-lite trade-off is the load-bearing choice in internal/hub
+
+**Context**: Discovered while writing thorough doc.go for internal/hub. The package embeds HashiCorp Raft for leader election only; data replication is sequence-based gRPC sync over the append-only JSONL store.
+
+**Lesson**: A leader crash window between accept and replicate can lose the most recent write. Append-only storage plus idempotent clients make this acceptable; full Raft log replication would not be needed and would not be simpler.
+
+**Application**: Any future make hub stronger proposal must engage with this trade-off explicitly. Do not abandon Raft-lite accidentally by introducing log-replicated state; that would invalidate the simplicity argument.
+
+---
+
+## [2026-04-14-010134] AST stutter test only checks FuncDecl, not GenDecl
+
+**Context**: tpl.TplEntryMarkdown stuttered for a long time because TestNoStutteryFunctions in internal/audit walks *ast.FuncDecl only; the constant slipped through.
+
+**Lesson**: The audit suite has a real coverage gap for *ast.GenDecl (consts, vars, types). Stuttery type/const names will not be caught until the audit is extended to walk those node kinds.
+
+**Application**: When a stuttery identifier is reported by a human, check both the offending file and whether the audit can catch it; if not, file an audit-extension task.
+
+---
+
+## [2026-04-14-010105] Brand-name handling in title-case engines must cover possessives
+
+**Context**: First pass of hack/title-case-headings.py produced 'Ctx's' from 'ctx's' because the brand check matched the bare token only.
+
+**Lesson**: A brand allowlist needs to recognize <brand>, <brand>'s, <brand>s, and short apostrophe-suffixed variants. Single-word matching misses contractions and possessives.
+
+**Application**: When adding a new always-lowercase brand to hack/title-case-headings.py, extend the suffix-aware loop in title_case_word, not just the BRAND_LOWER set.
+
+---
+
 ## [2026-04-13-153618] GPG signing from non-TTY contexts requires pinentry-mac (or equivalent)
 
 **Context**: git commit failed from Claude Code's shell with 'gpg: signing

@@ -2076,3 +2076,13 @@ disambiguates.
   `make test` (0 failures including the audit exempt-list
   update and the `gofmt` round-trip on `serve/cmd/root/cmd.go`).
   #added:2026-04-11 #pr:60 #done:2026-04-11
+
+### Later
+
+- [ ] Optional follow-up doc.go pass: a handful of tiny per-subcommand wrappers under internal/cli/*/cmd/* still have ~5-line bodies. Most are accurate-but-brief; expand only if the brief form proves insufficient in review. #session:4b37e2f6 #branch:feat/copilot-cli-skill-parity-rebased #commit:edaac81786c9379333b352dae0d55df0ae0f72bb #added:2026-04-14-010311
+
+- [ ] Extend internal/audit/stuttery_functions_test.go to cover *ast.GenDecl (consts, vars, types). Current implementation walks *ast.FuncDecl only and missed tpl.TplEntryMarkdown (since renamed to HubEntryMarkdown). #session:4b37e2f6 #branch:feat/copilot-cli-skill-parity-rebased #commit:edaac81786c9379333b352dae0d55df0ae0f72bb #added:2026-04-14-010311
+
+- [ ] Decide whether to delete docs/cli/connect.md — verified dead duplicate of docs/cli/connection.md (uses old ctx connect command name; zero inbound references; not in zensical.toml). Awaiting explicit user OK before git rm. #session:4b37e2f6 #branch:feat/copilot-cli-skill-parity-rebased #commit:edaac81786c9379333b352dae0d55df0ae0f72bb #added:2026-04-14-010311
+
+- [-] PROMPT.md design — belongs in another project; skipped here. #session:4b37e2f6 #added:2026-04-14-010311 #skipped:2026-04-14
@@ -53,7 +53,7 @@ key_rotation_days: 90  # Days before encryption key rotation nudge
 
 # --- Webhook notifications ---
 # Notifications are opt-in: nothing fires unless events are listed.
-# Run `ctx notify setup` to configure the encrypted webhook URL first.
+# Run `ctx hook notify setup` to configure the encrypted webhook URL first.
 #
 notify:
   events:
@@ -73,5 +73,5 @@ notify:
     #   qa-reminder         — QA gate reminder emitted
     #   block-non-path-ctx  — blocked non-PATH ctx invocation
 #
-# Note: `ctx notify test` always bypasses the event filter — no need to
+# Note: `ctx hook notify test` always bypasses the event filter — no need to
 # list "test" here. It warns if filtered but sends anyway.
@@ -100,7 +100,7 @@ If `ctx` is installed, use these commands:
 ctx status        # Context summary and health check
 ctx agent         # AI-ready context packet
 ctx drift         # Check for stale context
-ctx recall list   # Recent session history
+ctx journal source --limit 5   # Recent session history
 ```
 
 <!-- ctx:copilot:end -->
@@ -306,6 +306,14 @@ check-why:
 	@diff -q docs/reference/design-invariants.md internal/assets/why/design-invariants.md || (echo "FAIL: design-invariants.md is stale — run 'make sync-why'" && exit 1)
 	@echo "Why docs are in sync."
 
+## title-case-check: Dry-run title-case checker on docs (or TARGET=path)
+title-case-check:
+	@python3 hack/title-case-headings.py $${TARGET:-docs}
+
+## title-case-fix: Apply title-case fixes to headings + admonition titles (TARGET=path defaults to docs)
+title-case-fix:
+	@python3 hack/title-case-headings.py --apply $${TARGET:-docs}
+
 ## help: Show this help
 help:
 	@echo "Context CLI - Available targets:"

@@ -33,7 +33,7 @@ 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 
 learned along the way.
 
-!!! info "Context is a Record"
+!!! info "Context Is a Record"
     **Context** *is a* **persistent record**.
 
     By "*context*", I **don't** mean model memory or stored thoughts: 
@@ -165,7 +165,7 @@ The `git` history tells the story:
 4f0e195 feat: separate orchestrator directive from agent tasks
 ```
 
-## YOLO Mode: Fast, But Dangerous
+## YOLO Mode: Fast, but Dangerous
 
 The *Ralph Loop* made feature development *incredibly fast*.
 
@@ -277,12 +277,12 @@ conventions...*) should go in to `CONVENTIONS.md`.
 
 Here's how `ctx` explained why the distinction was important: 
 
-!!! tip "Decision record, 2026-01-25"
+!!! tip "Decision Record, 2026-01-25"
     Overly strict constitution creates friction and gets ignored.
 
     Conventions can be bent; constitution **cannot**.
 
-## Hooks: Harder Than They Look
+## Hooks: Harder than They Look
 
 Claude Code hooks seemed simple: Run a script before/after certain events. 
 
@@ -339,7 +339,7 @@ By the time of this writing this project's `ctx` sessions
 
 They are not part of the source code due to security, privacy, and size concerns.
 
-!!! tip "Middle Ground: the Scratchpad"
+!!! tip "Middle Ground: The Scratchpad"
     For sensitive notes that *do* need to travel with the project,
     `ctx pad` stores encrypted one-liners in git, and
     `ctx pad add "label" --file PATH` can ingest small files.
@@ -470,7 +470,7 @@ The archive from January 23rd shows 13 phases of work:
 
 That's an impressive ^^173 commits** across **8 days** of development.
 
-## What I Learned About AI-Assisted Development
+## What I Learned about AI-Assisted Development
 
 **1. Memory changes everything**
 
@@ -551,7 +551,7 @@ 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).
 
-!!! note "Session Records are a Gold Mine"
+!!! 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.

@@ -22,11 +22,11 @@ topics:
 
 ![ctx](../images/ctx-banner.png)
 
-## Digging Through the Past to Build the Future
+## Digging through the Past to Build the Future
 
 *Jose Alekhinne / 2026-02-01*
 
-!!! question "What if Your AI Could Remember Everything?"
+!!! question "What If Your AI Could Remember Everything?"
     Not just the current session, but **every** session:
 
     * **Every** decision made,
@@ -74,7 +74,7 @@ I found myself grepping through files to answer questions like:
 * "*What was the session where we fixed the hook regex?*"
 * "*How did the `embed.go` split actually happen?*"
 
-!!! note "Fate is Whimsical"
+!!! note "Fate Is Whimsical"
     The irony was **painful**:
 
     I built a tool to prevent AI amnesia, but I was suffering from 
@@ -114,7 +114,7 @@ them in a human-readable format:
 Slugs are auto-generated from session IDs (*memorable names instead of
 UUIDs*). The goal (*as the name implies*) is **recall**, not archival accuracy.
 
-!!! note "2,121 lines of new code"
+!!! note "2,121 Lines of New Code"
     The `ctx recall` feature was the largest single addition:
 
     parser library, CLI commands, test suite, and slash command.
@@ -214,7 +214,7 @@ ctx add learning "CGO breaks ARM64 builds" \
   --application "Added to Makefile and CI config"
 ```
 
-!!! quote "Structured entries are prompts to the AI"
+!!! quote "Structured Entries Are Prompts to the AI"
     When the AI reads a decision with full context, rationale, and
     consequences, it understands the **why**, *not* just the **what**.
 
@@ -250,7 +250,7 @@ always loaded first.
 
 The same structure serves two very different readers.
 
-!!! tip "Reindex after manual edits"
+!!! tip "Reindex After Manual Edits"
     If you edit entries by hand, rebuild the index with:
 
     ```bash
@@ -301,7 +301,7 @@ a human can **reason** about.
 
 ### 2. Enforcement > Documentation
 
-!!! quote "The Prompt is a Guideline"
+!!! quote "The Prompt Is a Guideline"
     The code is more what you'd call '*guidelines*' than actual rules.
 
     -**Hector Barbossa**
@@ -324,7 +324,7 @@ The journal system started as a way to understand `ctx` itself.
 
 It immediately became useful for everything else.
 
-## v0.2.0 in The Numbers
+## v0.2.0 in the Numbers
 
 This was a heavy release. The numbers reflect that:
 

@@ -196,7 +196,7 @@ This is where **v0.2.0** becomes more than a refactor.
 The biggest feature of this change window wasn't a refactor; it was
 the **journal system**.
 
-!!! note "45 files changed, 1680 insertions"
+!!! note "45 Files Changed, 1680 Insertions"
     This commit added the infrastructure for synthesizing AI session
     history into human-readable content.
 
@@ -245,7 +245,7 @@ The work also introduced **thread safety** in the **recall parser** and
 centralized shared validation logic; removing duplication that had
 quietly spread during YOLO mode.
 
-## I (Re)learned My Lessons
+## I (Re)Learned My Lessons
 
 Similar to what I've learned in 
 [the former human-assisted refactoring post][first-post], this

@@ -166,7 +166,7 @@ Also noted: ~100 tokens (title-only summaries for overflow)
 
 The constraint is the feature: It enforces ruthless prioritization.
 
-### Primitive 3: Indexes Over Full Content
+### Primitive 3: Indexes over Full Content
 
 `DECISIONS.md` and `LEARNINGS.md` both include index sections:
 
@@ -243,7 +243,7 @@ cat .context/sessions/...       # Deep dive when needed
 
 Summaries **first**. Details: **on demand**.
 
-## Quality Over Quantity
+## Quality over Quantity
 
 Here is the counterintuitive part: **more context can make AI worse**.