MemoryVault — Dev Onboarding

# MemoryVault — Reader Contract

You have access to a persistent, interlinked LLM Wiki at `$HOME/MemoryVault`.
It is the source of truth for tradeit.gg organizational knowledge — repo
synthesis, infra patterns, MySQL/Redis hard rules, business domain vocabulary.

The SessionStart hook auto-injects `MEMORY.md` (entrypoint) into your context
every new session. Follow these rules whenever you operate.

## Read order

1. `MEMORY.md` — already in context; orientation + high-signal entry pages.
2. `index.md` — full catalog by category. Load when answering navigational
   questions or when MEMORY.md's entry list doesn't cover the topic.
3. `CLAUDE.md` (the schema) — read on demand when ingesting, querying, or
   maintaining wiki pages. Authoritative on frontmatter, scope, supersession.
4. Specific `wiki/**/*.md` pages — drilled into via wikilinks `[[slug]]`.

## Frontmatter is authoritative

Every wiki page has `confidence` (0.0–1.0), `scope` (org | both — personal is
stripped from your export), `last_verified` (YYYY-MM-DD), `supersedes`,
`superseded_by`. Treat these as load-bearing:

- `confidence < 0.6` — speculative, verify before relying on
- `last_verified` > 90 days old — stale, mention staleness in your answer
- `superseded_by: <slug>` — read the successor page, not this one

## Repo-fact routing (LOAD-BEARING)

The vault contains `wiki/entities/repo-*.md` pages AND each repo has its own
team-owned `~/Projects/<repo>/CLAUDE.md`. They are complementary, not
competing:

- **How to work IN repo X** (build, test, in-repo conventions, debug recipes)
  → `~/Projects/X/CLAUDE.md` ONLY. Never the vault.
- **What X IS / how it fits the system / cross-repo synthesis**
  → `wiki/entities/repo-X.md` ONLY. Never the per-repo CLAUDE.md.
- **Cross-repo conventions** (MySQL, git, infra) → `wiki/concepts/*.md`.

**On conflict between vault and per-repo CLAUDE.md, per-repo wins.** Update
the vault page to match, bump `last_verified`, and never the reverse.

## What to write to the vault

When you learn a new durable fact about tradeit.gg in any session (regardless
of cwd):

- DO write a new/updated page under `$HOME/MemoryVault/wiki/{entities,
  concepts,sources,topics}/` with proper frontmatter.
- DO update `$HOME/MemoryVault/index.md` and append to `log.md`.
- DO NOT write to `~/.claude/projects/<project>/memory/` for durable facts
  about tradeit.gg — that's project-scoped, won't be loaded in other sessions.
- DO use project-scoped memory for ephemeral in-progress work that won't
  outlive the current task.

## What to NEVER ingest

- `~/.local/secrets/` — live secrets, never read or grep
- `.env*` files (any variant) — live credentials
- Files containing API keys, JWT secrets, OAuth tokens

If a candidate source contains any of these inline, refuse the ingest and
surface to the user.

## Inbox-surfacing protocol (LOAD-BEARING)

When the SessionStart hook output contains a `=== Pending session-end notes
===` block, your VERY FIRST response in the session MUST surface those items
before addressing the user's actual request. Use this format:

> Pending inbox from previous session: <filename>
> Summary: <one-line synopsis>
> Process now, defer, or discard?

This OVERRIDES the no-filler / no-preamble preference — inbox surfacing is a
protocol step, not chatter. After the user decides, continue normally.

When processing: translate each suggestion into wiki pages per `CLAUDE.md`
§16, then `mv` the inbox file to `archive/inbox/`.

## Maintenance protocol

- Don't create a page for something mentioned once in passing. Wait for the
  second mention. A wiki page needs at least 2 sentences of substance.
- Prefer updating in place over creating new pages with `supersedes`.
  Reserve supersession for genuine reversals.
- When a session has produced durable learnings, proactively suggest running
  `/revise-claude-md` near session end. Save its output to
  `$HOME/MemoryVault/.inbox/session-end-YYYY-MM-DD-HHMM.md` so the next
  session's hook surfaces it.

## Scope guardrail

All pages in your vault are `scope: org` or `scope: both`. Anything you write
back to the vault must respect that — no personal opinions, no unconfirmed
claims about teammates, nothing that wouldn't be safe to publish to the team.