chore: clean up project root (#45)

* chore: migrate pre-commit config to non-deprecated stage names

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: overhaul documentation structure and tone

- Rewrite README with vision-first framing — leads with the agentic
  memory problem, origin story, and Ingest→Categorize→Recall→Search
  as the central concept
- Add docs/cli.md as the complete command reference (moved out of README)
- Add docs/search.md as a user-facing guide to search vs recall
- Rewrite all user-facing docs (getting-started, team-sharing,
  configuration, architecture) to match README tone — direct, honest,
  opens with context before diving into mechanics
- Reorganize docs structure: kebab-case throughout, internal planning
  docs move to docs/internal/, personal writing gitignored via
  docs/writing/
- Rename: CI_HARDENING_EXECUTION_PLAN → internal/ci-hardening,
  DESIGN → internal/design, WORKFLOW_AUTOMATION → internal/workflow-automation,
  e2e-dev-release-flow-test → internal/e2e-release-flow,
  search-recall-architecture → internal/search-analysis
- Update .gitignore: add docs/writing/, .letta/, zsh plugins

👾 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta <noreply@letta.com>

* chore: clean up project root — move docs to docs/internal/, remove clutter

Move 9 root-level docs to docs/internal/ with kebab-case rename:
  IMPLEMENTATION.md             → docs/internal/implementation.md
  IMPLEMENTATION_CHECKLIST.md   → docs/internal/implementation-checklist.md
  PHASE1_IMPLEMENTATION.md      → docs/internal/phase1-implementation.md
  INGEST_ARCHITECTURE.md        → docs/internal/ingest-architecture.md
  DEMO_RESULTS.md               → docs/internal/demo-results.md
  RULES_QUICK_REFERENCE.md      → docs/internal/rules-quick-reference.md
  QUICKSTART.md                 → docs/internal/segmentation-quickstart.md
  majestic-sauteeing-papert.md  → docs/internal/qmd-deep-dive.md
  streamed-humming-curry.md     → docs/internal/ingest-refactoring.md

Remove:
  issues.json — GitHub issues export, not source or documentation
  zsh-autosuggestions/, zsh-syntax-highlighting/ — personal zsh plugins,
    unrelated to the project (already gitignored)

Update references to INGEST_ARCHITECTURE.md in README.md and CLAUDE.md.

Project root now contains only what belongs there: README, LICENSE,
CHANGELOG, CLAUDE.md, package.json, install/uninstall scripts, and
source directories.

* feat(claude): add proactive memory behavior directives to CLAUDE.md

Adds a Memory section at the top of CLAUDE.md that instructs Claude Code
to use Smriti actively — not passively. Modeled on the Loop pattern:
action-first, not acknowledgment-first.

- Recall at session start before writing code
- Recognize decision/finalization moments and act immediately
- Concrete wrong/right example with actual bash commands
- Category guide for correct tagging
- No asking permission — just save it

---------

Co-authored-by: Baseline User <baseline@example.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Letta <noreply@letta.com>

Author: 4 people

CLAUDE.md

@@ -3,6 +3,118 @@
 Shared memory layer for AI-powered engineering teams. Built on
 [QMD](https://github.com/tobi/qmd).
 
+## Memory
+
+You have Smriti. USE IT.
+
+### Start of Every Session
+
+Before writing a single line of code, run:
+
+```bash
+smriti recall "[what we're about to work on]"
+```
+
+Use what comes back. If there's prior context on this topic, it changes how
+you approach the work. Don't ignore it.
+
+### Recognize These Moments — Then Act Immediately
+
+No permission needed. No asking "should I save this?" Just do it.
+
+- Someone says "this works" or "let's go with this"
+- An approach is chosen after comparing options
+- A bug is fixed and the root cause is understood
+- A constraint is discovered that will affect future work
+- An architectural decision is made
+
+**WRONG**: Continue the conversation without saving.
+**RIGHT**: Write the decision record, ingest it, tag it — then respond.
+
+### How to Save a Decision
+
+**Step 1 — Write the record:**
+
+```bash
+cat > /tmp/smriti-note.md << 'EOF'
+# [Title]
+
+## Decision
+[One sentence — the actual choice made.]
+
+## Why
+[The reasoning. What was considered. What was ruled out and why.]
+
+## Context
+[What problem this solves. What breaks if someone reverses this later.]
+EOF
+```
+
+**Step 2 — Ingest:**
+
+```bash
+smriti ingest file /tmp/smriti-note.md \
+  --title "[Title]" \
+  --project smriti
+```
+
+**Step 3 — Tag:**
+
+```bash
+smriti tag [session-id] [category]
+```
+
+### Categories
+
+| What happened | Tag |
+|---------------|-----|
+| Architecture choice, approach finalized | `decision/technical` |
+| Library or tool selected | `decision/tooling` |
+| Bug fixed, root cause identified | `bug/fix` |
+| Structural design settled | `architecture/design` |
+| Feature approach finalized | `feature/implementation` |
+| Config or setup figured out | `project/config` |
+
+### Concrete Example
+
+User says: *"Okay let's use post-filtering for vector search with filters"*
+
+**WRONG**:
+> "Got it, I'll use post-filtering."
+
+**RIGHT**:
+
+```bash
+cat > /tmp/smriti-note.md << 'EOF'
+# Vector search with filters: post-filter approach
+
+## Decision
+Use post-filter strategy for applying metadata filters to vector search
+results, rather than combining sqlite-vec queries with EXISTS subqueries.
+
+## Why
+sqlite-vec's two-step query pattern hangs when combined with Smriti's
+EXISTS subqueries on metadata tables. Post-filtering runs vector search
+unfiltered (3x overfetch), then filters results against session metadata
+in a separate batch lookup — no sqlite-vec changes needed.
+
+## Context
+Affects smriti recall when --project, --category, or --agent flags are
+used. Without this, filtered recall loses semantic search entirely and
+falls back to BM25 only.
+EOF
+
+smriti ingest file /tmp/smriti-note.md \
+  --title "Vector search with filters: post-filter approach" \
+  --project smriti
+
+smriti tag [session-id] decision/technical
+```
+
+Then respond to the user.
+
+---
+
 ## Quick Reference
 
 ```bash
@@ -104,7 +216,7 @@ get a clean name like `openfga`.
 4. Store message/meta/sidecars/costs (store gateway)
 5. Aggregate results and continue on per-session errors (orchestrator)
 
-See `INGEST_ARCHITECTURE.md` for details.
+See `docs/internal/ingest-architecture.md` for details.
 
 ### Search
 

README.md

@@ -299,7 +299,7 @@ works cross-project by default, scoped with `--project <id>`.
 git-native today. Issue tracker integrations are on the roadmap.
 
 **Further reading:** See [docs/cli.md](./docs/cli.md) for the full command
-reference, [INGEST_ARCHITECTURE.md](./INGEST_ARCHITECTURE.md) for the ingestion
+reference, [docs/internal/ingest-architecture.md](./docs/internal/ingest-architecture.md) for the ingestion
 pipeline, and [CLAUDE.md](./CLAUDE.md) for the database schema and
 architecture.