docs: standardize terminology and fix CLI reference accuracy

Documentation audit fixes:
- Standardize on ".context/" notation (not "./context" or ".context")
- Update global flags section: remove "planned" markers (flags are implemented)
- Add missing docs for ctx decisions reindex and ctx learnings reindex
- Standardize terminology: "AI tools" (not "AI agents")
- Standardize terminology: "manual session files" (not "curated sessions")
- Standardize terminology: "session dumps" (not "full conversation dumps")
- Define ADR (Architectural Decision Record) on first use
- Fix tone consistency: use "AI tool" throughout docs

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

Author: josealekhine

.claude/hooks/block-git-push.sh

@@ -1,4 +1,11 @@
 #!/bin/bash
+
+#   /    Context:                     https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2026-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
 #
 # Block git push - requires explicit user approval
 #

.context/AGENT_PLAYBOOK.md

@@ -64,15 +64,15 @@ implementation detail. Load it and use it — don't lead with caveats.
 
 ## Session History
 
-**IMPORTANT**: Check `.context/sessions/` for full conversation dumps from 
+**IMPORTANT**: Check `.context/sessions/` for session 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`
+**Manual 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.
 

.context/DECISIONS.md

@@ -383,19 +383,19 @@ Also, multiple compacts in the same minute could collide.
 
 **Decision**: Use `YYYY-MM-DD-HHMMSS-<topic>.md` format for session files.
 Two file types:
-- **Curated sessions**: `HHMMSS-<topic>.md` - updated throughout session
+- **Manual session files**: `HHMMSS-<topic>.md` - updated throughout session
 - **Auto-snapshots**: `HHMMSS-<event>.jsonl` - immutable once created
 
 **Rationale**:
 - Human-readable (unlike unix timestamps)
 - Naturally sorts chronologically
 - Seconds precision prevents collision even with rapid compacts
-- Clear distinction between curated notes and raw snapshots
+- Clear distinction between manual notes and raw snapshots
 
 **Consequences**:
 - Slightly longer filenames
 - Must ensure consistent format in all session-saving code
-- Curated files keep getting updated; snapshots are write-once
+- Manual files keep getting updated; snapshots are write-once
 
 ---
 

.context/LEARNINGS.md

@@ -41,7 +41,7 @@
 
 ## [2026-01-28-191951] Required flags now enforced for learnings
 
-**Context**: Implemented ctx add learning flags to match decision's ADR pattern
+**Context**: Implemented ctx add learning flags to match decision's ADR (Architectural Decision Record) pattern
 
 **Lesson**: Structured entries with Context/Lesson/Application are more useful 
 than one-liners

CLAUDE.md

@@ -8,7 +8,7 @@ This project uses Context (ctx) for context persistence across sessions.
 ## On Session Start
 
 1. **Read `.context/AGENT_PLAYBOOK.md`** first - it explains how to use this system
-2. **Check `.context/sessions/`** for full conversation dumps from previous sessions
+2. **Check `.context/sessions/`** for session dumps from previous sessions
 3. **Run `ctx status`** to see current context summary
 
 ## Quick Context Load
@@ -30,7 +30,7 @@ ctx status
 | `.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 |
+| `.context/sessions/`       | **Session dumps** - check here for deep context |
 
 ## Before Session Ends
 

cmd/ctx/main.go

@@ -13,6 +13,7 @@ import (
 	"github.com/ActiveMemory/ctx/internal/bootstrap"
 )
 
+// main is the entry point of the application.
 func main() {
 	cmd := bootstrap.Initialize(bootstrap.RootCmd())
 

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

@@ -490,10 +490,10 @@ If you're a mere mortal tired of reset amnesia, give `ctx` a try.
 
 And when you do, check `.context/sessions/` sometime. 
 
-The archaeological record might surprise you.
+The **archaeological record** might surprise you.
 
 ---
 
 *This blog post was written with the help of `ctx` with full access to the 
 `ctx` session files, decision log, learning log, task archives, and 
-git history of `ctx—The meta continues.*
+git history of `ctx`—The meta continues.*

docs/cli-reference.md

@@ -19,20 +19,15 @@ This is a complete reference for all `ctx` commands.
 
 All commands support these flags:
 
-| Flag        | Description       |
-|-------------|-------------------|
-| `--help`    | Show command help |
-| `--version` | Show version      |
+| Flag                   | Description                                       |
+|------------------------|---------------------------------------------------|
+| `--help`               | Show command help                                 |
+| `--version`            | Show version                                      |
+| `--context-dir <path>` | Override context directory (default: `.context/`) |
+| `--quiet`              | Suppress non-essential output                     |
+| `--no-color`           | Disable colored output                            |
 
-**Planned flags** (not yet implemented):
-
-| Flag                   | Description                                      |
-|------------------------|--------------------------------------------------|
-| `--context-dir <path>` | Override context directory (default: `.context`) |
-| `--quiet`              | Suppress non-essential output                    |
-| `--no-color`           | Disable colored output                           |
-
-> Use `NO_COLOR=1` environment variable to disable colored output today.
+> The `NO_COLOR=1` environment variable also disables colored output.
 
 ## Commands
 
@@ -411,6 +406,68 @@ ctx tasks snapshot "before-refactor"
 
 ---
 
+### `ctx decisions`
+
+Manage the DECISIONS.md file.
+
+```bash
+ctx decisions <subcommand>
+```
+
+#### `ctx decisions reindex`
+
+Regenerate the quick-reference index at the top of DECISIONS.md.
+
+```bash
+ctx decisions reindex
+```
+
+The index is a compact table showing date and title for each decision,
+allowing AI tools to quickly scan entries without reading the full file.
+
+Use this after manual edits to DECISIONS.md or when migrating existing
+files to use the index format.
+
+**Example**:
+
+```bash
+ctx decisions reindex
+# ✓ Index regenerated with 12 entries
+```
+
+---
+
+### `ctx learnings`
+
+Manage the LEARNINGS.md file.
+
+```bash
+ctx learnings <subcommand>
+```
+
+#### `ctx learnings reindex`
+
+Regenerate the quick-reference index at the top of LEARNINGS.md.
+
+```bash
+ctx learnings reindex
+```
+
+The index is a compact table showing date and title for each learning,
+allowing AI tools to quickly scan entries without reading the full file.
+
+Use this after manual edits to LEARNINGS.md or when migrating existing
+files to use the index format.
+
+**Example**:
+
+```bash
+ctx learnings reindex
+# ✓ Index regenerated with 8 entries
+```
+
+---
+
 ### `ctx recall`
 
 Browse and search AI session history from Claude Code and other tools.

docs/comparison.md

@@ -165,7 +165,7 @@ Together, loops become cumulative instead of forgetful.
 
 ## SDK-Level Context Objects
 
-Some SDKs expose "context" objects that exist:
+Some SDKs expose "*context*" objects that exist:
 
 * inside a process
 * during a request

docs/context-files.md

@@ -11,7 +11,7 @@ icon: lucide/files
 
 ![ctx](images/ctx-banner.png)
 
-## `./context`
+## `.context/`
 
 Each context file in `.context/` serves a specific purpose. 
 
@@ -29,16 +29,16 @@ Files are designed to be human-readable, AI-parseable, and token-efficient.
 | LEARNINGS.md      | Lessons learned, gotchas, tips         | 6           |
 | GLOSSARY.md       | Domain terms and abbreviations         | 7           |
 | DRIFT.md          | Staleness signals and update triggers  | 8           |
-| AGENT_PLAYBOOK.md | Instructions for AI agents             | 9 (lowest)  |
+| AGENT_PLAYBOOK.md | Instructions for AI tools              | 9 (lowest)  |
 
 ## Read Order Rationale
 
-The priority order follows a logical progression for AI agents:
+The priority order follows a logical progression for AI tools:
 
-1. **CONSTITUTION** — Inviolable rules first. The agent must know what it
+1. **CONSTITUTION** — Inviolable rules first. The AI tool must know what it
    *cannot* do before attempting anything.
 
-2. **TASKS** — Current work items. What the agent should focus on.
+2. **TASKS** — Current work items. What the AI tool should focus on.
 
 3. **CONVENTIONS** — How to write code. Patterns and standards to follow
    when implementing tasks.
@@ -69,7 +69,7 @@ The priority order follows a logical progression for AI agents:
 **Purpose:** Define hard invariants—rules that must **NEVER** be violated, 
 regardless of the task.
 
-AI agents read this first and should refuse tasks that violate these rules.
+AI tools read this first and should refuse tasks that violate these rules.
 
 ### Structure
 
@@ -462,7 +462,7 @@ Update context when:
 
 ## AGENT_PLAYBOOK.md
 
-**Purpose**: Explicit instructions for how AI agents should read, apply, 
+**Purpose**: Explicit instructions for how AI tools should read, apply, 
 and update context.
 
 ### Key Sections