quicksilver/docs/quicksilver-plan.md

# Quicksilver — user-agnostic rewrite + rename plan

## Objective

Turn the plugin (formerly `echo-memory` / "ECHO") into one a coworker can install
cold. On first run it detects it's freshly installed, prompts for the **API endpoint
FQDN**, **API key**, and **operator name/role**, verifies them, persists them to a
**local bootstrap indicator file**, then bootstraps the vault and personalizes memory
to that operator. The system is renamed to **Quicksilver** throughout. Jason stays
credited only as the architect.

## Locked decisions

1. **Credentials** → a dedicated **local bootstrap indicator file** (client-side) holds
   FQDN + API key. The in-vault marker stays a pure schema/version flag (no secret).
2. **Operator identity** → prompt for name/role at first run; personalize memory
   ("Alex prefers X"); seed `operator-preferences.md` + the marker with it.
3. **Attribution** → Jason kept in `plugin.json` `author` + a one-line
   "Architecture by Jason Stedwell" credit in the README. Every other operational
   mention removed.
4. **Name** → full rename `echo-memory` / `ECHO` → `quicksilver` / `Quicksilver`
   (0 "echo" hits after the pass).

## Core design: two-layer "is this set up?" detection

| Layer | File | Question | Holds |
|---|---|---|---|
| 1. Local indicator (new) | `~/.quicksilver/quicksilver-config.json` (client-side) | "Is *this install* configured?" | FQDN + **API key** + operator name/role |
| 2. Vault marker (existing) | `_agent/quicksilver-vault.md` (in vault) | "Is the *vault* scaffolded?" | schema_version, bootstrap date, operator name — **never the key** |

The secret lives client-side (you need it *before* you can reach the vault, and the
plugin's own safety rule forbids keys in vault notes). The vault marker stays a pure
schema flag. The local indicator file *is* the "freshly installed?" signal — its
absence triggers first-run.

### Local indicator file spec

Path: `~/.quicksilver/quicksilver-config.json` (Windows:
`%USERPROFILE%\.quicksilver\quicksilver-config.json`). Lives in the user home, **not**
the plugin dir, so it survives plugin reinstalls/updates.

```json
{
  "schema": 1,
  "endpoint": "https://<operator-fqdn>",
  "api_key": "<bearer-token>",
  "operator": { "name": "Alex Rivera", "role": "Network Engineer" },
  "configured_at": "2026-06-07",
  "verified_at": "2026-06-07"
}
```

The skill reads this with the Read tool at session start and substitutes
`endpoint`→`$BASE` and `api_key`→bearer into all curl calls. **No `jq` dependency** —
the agent parses the JSON itself, portable across Windows/Mac/Linux shells.

## First-run / session-start algorithm (new Step 0)

1. **Check local indicator** (`~/.quicksilver/quicksilver-config.json`).
   - **Absent → FRESH INSTALL.** Tell the operator this looks like a first run and
     prompt for: (a) endpoint FQDN, (b) API key, (c) name + role. Verify by probing
     `GET $BASE/vault/_agent/quicksilver-vault.md` (200/404 = reachable+authorized;
     connection error/401 = re-prompt). Write the indicator file (`chmod 600`).
   - **Present →** load `endpoint`, `api_key`, `operator`; continue.
2. **Probe vault marker** `_agent/quicksilver-vault.md` with the known creds.
   - **404 →** fresh bootstrap (scaffold), seeding `operator-preferences.md`
     `## Operator` with the provided name/role, and writing the marker with
     `operator:` set (no key).
   - **200 →** check `schema_version`, migrate if stale, proceed to normal loading.

## File-by-file changes (genericize + rename in one pass)

- **`.claude-plugin/plugin.json`** — `name`/`description`/`keywords` → quicksilver;
  drop "Jason's personal memory vault"; **keep** `author: Jason Stedwell`; bump
  `0.5.0` → `0.6.0`.
- **`README.md`** — title `# quicksilver`; operator-agnostic intro + one line
  "Architecture by Jason Stedwell."; rewrite **Configuration** (no hardcoded
  server/key; document first-run flow + indicator file); remove "not for
  distribution"; ECHO → Quicksilver.
- **`skills/quicksilver/SKILL.md`** — frontmatter `name: quicksilver`, genericize
  `description` (strip Jason / Bryan's goldbrain / MPM / wISP; ECHO → Quicksilver);
  replace hardcoded `OBSIDIAN_BASE`/`OBSIDIAN_KEY` block with "load from indicator
  file"; delete the `echoapi.alwisp.com`-only / retired-`obsidian-memory` paragraph;
  rewrite operator-identity paragraph to read identity dynamically; every curl
  `Bearer 2412…`→`$AUTH`, `https://echoapi.alwisp.com`→`$BASE`; remove goldbrain/Bryan
  cross-write rule; "Jason" → "the operator"; add Step 0 to loading; marker path →
  `quicksilver-vault.md`.
- **`references/api-reference.md`** — server/key header lines and every curl →
  `$BASE`/`$AUTH`; example prose genericized; marker path.
- **`references/bootstrap.md`** — replace hardcoded `AUTH`/`BASE` with load-from-
  indicator preamble; add **Step 0: Client configuration (first run)**; seed
  `## Operator` from provided name; marker stores operator + schema only; add the
  `echo-vault.md` → `quicksilver-vault.md` rename migration.
- **`references/vault-layout.md`** — genericize operator-preferences + people example
  (`<operator-name>.md`); marker path; ECHO → Quicksilver.
- **`references/operating-contract.md`** — confirm operator-agnostic; ECHO →
  Quicksilver.
- **`references/session-log-template.md`** — update illustrative key/decision lines;
  example slugs `echo-*` → `quicksilver-*`.
- **`scaffold/quicksilver-vault.md`** (was `echo-vault.md`) — "Quicksilver Vault
  Marker"; add `operator:` frontmatter; `managed_by: quicksilver-plugin`; explicit
  "no key here".
- **`scaffold/README.vault.md`** — "Quicksilver Memory Vault"; ECHO → Quicksilver.
- **`scaffold/anchors/operator-preferences.seed.md`** — add `{{OPERATOR}}`/`{{ROLE}}`
  substitution tokens for `## Operator`.
- **`scaffold/anchors/inbox.seed.md`** — "quicksilver skill".

## Path / file renames (git mv)

- `echo-memory.plugin.src/` → `quicksilver.plugin.src/`
- `…/skills/echo-memory/` → `…/skills/quicksilver/`
- `…/scaffold/echo-vault.md` → `…/scaffold/quicksilver-vault.md`
- `echo-memory.plugin` (packaged artifact) → rebuilt/renamed `quicksilver.plugin`

## Migration impact (Jason's existing vault)

The marker rename means Jason's current vault has the marker at the old path. Fold into
the schema migration: on probe, if `quicksilver-vault.md` is 404 **but**
`echo-vault.md` is 200, treat as a rename migration — PUT the new marker, DELETE the
old, scrub stale `[[echo-vault]]` links. New coworker vaults are fresh and hit the
clean path.

## Security / hygiene

- **Rotate the live key.** `241265fbe…` is committed in plaintext and in git history.
  Even after genericizing, history retains it — rotate it on the backend.
- Indicator file holds a secret → write `0600`; it lives in `$HOME`, outside the repo.

## Validation

- **Grep gate:** `grep -ri "echo"` → 0 hits; `grep -ri "jason\|alwisp\|241265\|goldbrain\|bryan"` → only README architect credit + plugin.json author.
- **Fresh install:** no indicator + empty vault → prompts for FQDN/key/name, file
  written, vault scaffolded, `## Operator` seeded.
- **Returning user:** indicator + marker present → loads silently, no prompts.
- **Reinstall:** plugin reinstalled, indicator persists in `$HOME` → no re-prompt.
- **Bad endpoint at first run:** unreachable/401 → graceful re-prompt, nothing written.

## Out of scope (v1)

Multiple operators / multiple vaults per machine (single indicator file assumed).