echo/MAINTENANCE.md

# echo-memory — Maintenance & repo hygiene (M5)

Low-lift cleanups that remove "which copy is canonical?" traps before tagging 1.0.
None of these change runtime behavior; they reduce drift and confusion.

## Canonical source tree

- **`echo-memory.plugin.src/`** is the single canonical source tree. ✅
- **`codex plugin/`** has already drifted — it lacks the 0.9 modules
  (`echo_index.py`, `echo_links.py`, `echo_ops.py`, `sweep.py`, `check_routing.py`).
  - [ ] Decide: regenerate it from the canonical tree as a build target, **or** delete it
        and document the codex/CoWork packaging step instead.
  - [ ] Until resolved, add a `codex plugin/README.md` note: "derived — do not edit by hand."

## Build artifacts

The repo root carries every historical build (`echo-memory-0.6.0.plugin` …
`echo-memory-0.9.0.plugin`) plus `echo-memory.plugin`.
- [ ] Keep only the latest `echo-memory.plugin` (the installable) tracked; move versioned
      zips to GitHub Releases (or a `dist/` that is git-ignored).
- [ ] Add `*.plugin` build outputs to `.gitignore` except the current pointer, if desired.
- [x] `.gitignore` added (`.DS_Store`, `__pycache__`, local `.echo-memory/`, eval output).

## `plugin.json` completeness

- [x] Add `license` (UNLICENSED — personal, not for distribution).
- [x] Version bumped to **1.0.0**.
- [ ] Add `homepage` / repository URL (optional — repo URL not yet decided).
- [ ] (Optional) register slash commands in the manifest; they're auto-discovered from
      `commands/` today (`echo-load|save|recall|triage|health|sweep|reflect|doctor`).

## Docs freshness

- [ ] `eval/run_eval.py` still benchmarks **0.6 vs 0.7** — refresh to current (open H4 follow-up).
- [x] README version-history has a **1.0.0** entry; title bumped to v1.0.0.
- [x] Scrub the literal bearer token from docs → `$ECHO_KEY` placeholder (M1, done:
      `api-reference.md` ×11, `SKILL.md`, `bootstrap.md`, eval harness).
      **Superseded in 1.3/1.4:** key resolution now lives in `echo_config.py`
      (machine-local `~/.claude/echo-memory/config.json`, `ECHO_*` env overrides, and
      empty-in-source `DEFAULT_*` constants filled only by `build.py --bake-key` for
      per-user artifacts in gitignored `dist/`). `API-KEY-SETUP.md` and the old
      `~/.echo-memory/credentials` fallback are gone; the committed tree ships zero
      credentials.

## Building the `.plugin` artifact

`python build.py` zips `echo-memory.plugin.src/` into `echo-memory-<version>.plugin` (version
read from the manifest) and refreshes the `echo-memory.plugin` pointer. Deterministic
(sorted entries + fixed timestamp → byte-identical rebuilds). Flags:

- `--strip-key` — force-blank the `echo_config.py` `DEFAULT_*` constants for a guaranteed
  token-free artifact (a clean source build is already token-free; this is the belt-and-braces flag).
- `--bake-key --from <config.json> [--label <name>]` — per-user secret-bearing artifact in
  gitignored `dist/`; deliver directly to that one user, never commit (see README).
- `--no-pointer` — skip refreshing `echo-memory.plugin`.
- `--outdir DIR` — write artifacts elsewhere.

Without `--strip-key` the build warns that the baked-in token is present.

## Pre-1.0 release checklist

- [x] All 10 roadmap items wired; scaffold TODOs cleared (see `ROADMAP-1.0.md` status table).
- [x] `schema_version` bumped to 4 (sweep/migrate); `migrate.py` `[3→4]` step added.
      *Verify on a copy of the live vault before migrating it (it currently reports schema 3).*
- [x] Offline suites green in CI on Win/macOS/Linux × Py 3.10/3.12 (check_routing,
      test_echo_client, test_v1_scaffold, test_features, test_patch_semantics,
      test_offline_queue, test_reflect).
- [ ] No live secret in the tracked tree or the built `.plugin` — **one line left**: delete
      `echo.py` `DEFAULT_KEY` after `ECHO_KEY`/credentials are set everywhere (per `API-KEY-SETUP.md`).
- [ ] `eval/run_eval.py` reports current-version retrieval/durability metrics (open follow-up).