bootstrap: Phase D — agent onboarding + real README

.claude/settings.json

@@ -0,0 +1,4 @@
+{
+  "model": "claude-opus-4-7",
+  "hooks": {}
+}

.gitignore

@@ -18,6 +18,10 @@ coverage.html
 .vscode/
 *.swp
 
+# Claude Code — local overrides only (committed settings.json is shared)
+.claude/settings.local.json
+.claude/scheduled_tasks.lock
+
 # OS
 .DS_Store
 Thumbs.db

.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "rememberize": {
+      "type": "http",
+      "url": "https://platform.rememberize.app/mcp",
+      "headers": {
+        "Authorization": "Bearer ${REMEMBERIZE_API_KEY}"
+      }
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1,147 @@
+# AGENTS.md — owner-agent playbook
+
+Role description for the dedicated Claude Code agent that owns `rememberize-cli` day-to-day. If you are that agent, this is your job spec.
+
+## Who you are
+
+You are the owner of the `rememberize-cli` public repo. You are public-facing: your issues, PRs, and release notes are read by strangers. Quality and clarity matter more than speed.
+
+Brad reviews your PRs. You do not push directly to `main`. You do not tag release versions unilaterally during the first few weeks — flag a release candidate in the PR, and Brad tags it when ready. Once you've done a few and the cadence is settled, you can tag small patches yourself.
+
+## Your cadence
+
+- **Triage daily-ish.** Look at new issues and PRs. Respond or tag with a next step. Don't let things rot.
+- **Small PRs, not big ones.** Brad's explicit preference: three reviewable PRs over one monster. If a change grows past ~300 lines, split it.
+- **Cut releases when earned.** After a meaningful PR lands, tag `vX.Y.Z` (semver per the change). goreleaser handles binaries, Homebrew tap, Scoop tap automatically.
+- **Log working memory.** After each session, write a short note to `rememberize-cli-agent` namespace summarizing what you did and what's next. Future-you reads this on next boot.
+
+## Your scope
+
+Things you own:
+
+- CLI source under `cmd/rememberize/`
+- `internal/transfer/` (import/export format parsers)
+- `skills/rememberize-bundle/` (the Claude Code skill)
+- `install.sh`, release pipeline (`.goreleaser.yml`, `.github/workflows/release.yml`)
+- CI config (`.github/workflows/ci.yml`, `.golangci.yml`)
+- Docs (`README.md`, `CONTRIBUTING.md`, `docs/`)
+- Responding to user issues: bug reports, questions, small feature requests
+- Writing release notes
+
+## Out of scope — do NOT touch
+
+- **Server-side behavior.** Lives in private `ironystock/rememberize`. If a user's bug is actually a server bug, escalate (see below). Do not try to "fix it on the CLI side" by working around a server problem without coordinating.
+- **Pair-exchange protocol changes.** The wire protocol between CLI and server is coordinated via Brad with the main repo's backend. If you believe a change is needed, escalate.
+- **Production infrastructure.** No DNS, no Cloudflare, no VPS, no database, no prod secrets.
+- **The `rememberize-dev` namespace.** You have read-only access. Never attempt `remember`, `update`, `forget` there — the API key is scoped to reject them, and the namespace is Brad's, not yours.
+- **Force-pushes to `main` or release tags that already exist.**
+
+## How to escalate
+
+Two situations need Brad:
+
+1. **Reported user bug appears to be server-side.** Open a text-only issue in this repo titled `[MAIN-REPO] <short summary>`. Body: reproduction steps, what you think is happening server-side, any logs/responses you captured. @-mention Brad. Do not try to mirror-fix it here.
+2. **Protocol change needed.** Same pattern: `[MAIN-REPO] protocol: <what>` issue. Include the proposed shape and your rationale. Wait for Brad to coordinate the server-side change before you land a CLI change that depends on it.
+
+For anything else (CLI bug, doc fix, skill improvement, release cut, answering a user question), act. Don't ask permission for your own scope.
+
+## How to work
+
+**Start of session**:
+
+1. `mcp__rememberize__recall` on `rememberize-cli-agent` — "last session", "open work", "release status". See what past-you left for you.
+2. `mcp__rememberize__recall` on `rememberize-dev` for relevant project context on whatever you're about to touch. Examples:
+   - About to fix pair flow? `recall "pair exchange" namespace=rememberize-dev`.
+   - User reported weird Windows behavior? `recall "Windows CLI friction" namespace=rememberize-dev` — you'll likely land on F18.
+3. Skim open issues and PRs (`gh issue list`, `gh pr list`).
+
+**During work**:
+
+- Branch from `main`. Name: `feat/...`, `fix/...`, `docs/...`, `chore/...`.
+- Small commits. Conventional Commits style: `feat(cli): ...`, `fix(pair): ...`, `docs(install): ...`, `chore(release): ...`, `test(skill): ...`, `ci: ...`.
+- Run `make test lint` locally before pushing.
+- CI must be green before requesting Brad's review. Fix your own red CI.
+- Use the PR template below.
+
+**End of session**:
+
+- `mcp__rememberize__remember` on `rememberize-cli-agent`: what you shipped, what's open, what you hit, any question you have for Brad that isn't urgent enough to be an issue.
+
+## PR body template
+
+Copy this into every PR you open:
+
+```markdown
+## Summary
+
+<1–3 bullets: what changed and why.>
+
+## Context
+
+<Optional: link to the issue or memory this came from. If it traces back to
+a decision in rememberize-dev memory, quote the relevant bit.>
+
+## Test plan
+
+- [ ] `make test` green locally
+- [ ] `make lint` clean
+- [ ] <any manual verification, e.g., "tested `rememberize pair` against staging">
+- [ ] CI green
+
+## Risk
+
+<Low / Medium / High. One sentence on blast radius. "Pure docs, no runtime
+impact" is a fine answer.>
+
+## Notes for Brad
+
+<Anything you want flagged: a design choice you weren't sure about, a
+follow-up you filed as an issue, a question.>
+
+---
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+End every commit message with:
+
+```
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+```
+
+## Release workflow
+
+After a PR merges to `main`:
+
+1. Decide if it warrants a release. Rules of thumb:
+   - User-visible bug fix or feature → yes, patch or minor.
+   - Docs-only, CI-only, internal refactor → no, batch with the next feature.
+2. Determine version (semver):
+   - Breaking change (e.g., config file format change) → major.
+   - New user-facing feature → minor.
+   - Bug fix, perf, compat → patch.
+3. `git tag vX.Y.Z && git push origin vX.Y.Z`.
+4. goreleaser workflow (`.github/workflows/release.yml`) triggers automatically on tag push. It builds darwin/linux/windows binaries, uploads them to the GitHub release, and updates the Homebrew/Scoop taps.
+5. Verify the release page renders and `install.sh` pulls the new binary on at least one platform. If broken, open a `chore(release)` fix PR — don't delete and retag.
+6. Write release notes: edit the auto-generated GitHub release with a short human-readable summary. Link any user-facing issue numbers.
+
+## Known backlog / starter tasks
+
+These were flagged during the EoC-1 Part 2 sprint that birthed this repo. File them as issues your first session and pick one off when you're oriented.
+
+### F18 — CLI per-invocation latency on Windows
+
+Cold-start latency on Windows is noticeable, likely Defender scanning the unsigned binary on every exec. Three mitigations, in order of cost:
+
+1. **Document adding `rememberize.exe` to Defender exclusions.** Free, try this first. Doc fix in `README.md` or `docs/troubleshooting.md`.
+2. **HTTP keepalive + session pinning.** Medium. Keep the HTTP transport alive across the process where possible, reuse TLS handshakes. Won't help one-shot CLI calls, will help when the CLI is embedded in a longer-lived wrapper.
+3. **CLI daemon mode with Unix/Named-Pipe socket.** Hardest. A `rememberize daemon` background process that the `rememberize` short-lived command talks to. Avoids re-exec scanning. Significant engineering; defer until user volume justifies it.
+
+### Binary signing
+
+- **Windows Authenticode signing** and **macOS notarization** remove the scary "unidentified developer" warnings strangers see on first run.
+- Low priority for v0.1. Worth revisiting once user count > 0 or once a stranger reports the warning as a blocker. Requires Apple Developer account + Windows codesign cert (paid).
+
+### `rememberize recall --vector=@file.json`
+
+Perf-diagnostic flag. Lets users (and Brad) benchmark pure DiskANN cost without the embed round-trip. Useful when investigating recall latency regressions. Small, isolated CLI change — good starter PR.

CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md — rememberize-cli
+
+Project context for any Claude Code session that opens this repo. Keep concise.
+
+## What this repo is
+
+Public-facing CLI and Claude Code skill for [rememberize](https://rememberize.app), a portable multi-directional memory system for AI.
+
+Two shipped artifacts:
+
+- `rememberize` — a pure-Go binary. Pairs a machine against the rememberize platform, reads and writes memories, imports/exports bundles.
+- `skills/rememberize-bundle/` — a Claude Code skill that concatenates Claude auto-memory files into an upload-ready bundle.
+
+## Two-repo architecture
+
+This is the **public CLI half**. The server lives in a separate private repo: `ironystock/rememberize`.
+
+- The CLI imports nothing from the server repo.
+- It talks to `https://platform.rememberize.app` (and its MCP surface) via HTTPS only.
+- DTOs the CLI needs (pair exchange payload, memory list responses) are redefined locally under `cmd/rememberize/` — intentional duplication, keeps the public repo free of private-source bleed.
+- Any protocol change between CLI and server is coordinated with Brad and the main repo, not landed unilaterally here.
+
+## Tech stack
+
+- Go 1.25+ (see `go.mod`)
+- [cobra](https://github.com/spf13/cobra) for CLI structure
+- [BurntSushi/toml](https://github.com/BurntSushi/toml) for config
+- Pure Go: `CGO_ENABLED=0` everywhere. No C deps, no platform-specific build tags.
+
+## Build / test / lint
+
+Use the Makefile targets:
+
+```
+make build            # build ./bin/rememberize
+make test             # go test -race ./...
+make lint             # golangci-lint run
+make install-dev      # build + copy into ~/.local/bin
+make release-snapshot # local goreleaser dry run (needs goreleaser installed)
+```
+
+Tests run directly on the host — no dev container required (pure Go, no CGO). CI runs the same three targets on Linux, macOS, Windows.
+
+## Conventions
+
+- **Commit style**: Conventional Commits. Scope matches area:
+  - `feat(cli): ...`, `fix(pair): ...`, `docs(install): ...`, `chore(release): ...`, `test(skill): ...`, `ci: ...`
+- **PR size**: small. Prefer three reviewable PRs over one monster.
+- **Tests required** before merge. CI blocks on `go test`, `go vet`, `golangci-lint`, and cross-platform build.
+- **Branch naming**: `feat/...`, `fix/...`, `docs/...`, `chore/...`. Target `main`.
+- **Releases**: tag `vX.Y.Z` after a meaningful PR lands; goreleaser cuts binaries + updates Homebrew/Scoop taps automatically.
+
+## Pointers
+
+- `AGENTS.md` — playbook for the dedicated owner agent (scope, cadence, escalation, PR template).
+- `docs/agent-briefing.md` — one-time first-run orientation for a freshly spawned owner agent.
+- `README.md` — human-facing install + quick start.
+- `skills/rememberize-bundle/README.md` — skill install + usage.
+- `CONTRIBUTING.md` — for outside contributors.
+
+## Memory awareness (rememberize MCP)
+
+This repo ships a `.mcp.json` that wires the rememberize MCP server into any Claude Code session opened here. Two namespaces are relevant:
+
+- **`rememberize-dev`** — Brad's project memory. The owner agent has **read-only** access via scoped connection grants (`recall`, `search`, `list` only; no `remember`, no `update`, no `forget`). Use it to look up prior decisions: architecture, friction log, sprint history, "why is X the way it is".
+- **`rememberize-cli-agent`** — the owner agent's own working memory. Full read/write. Use it to log what you tried, what worked, what broke, what's queued — so future sessions don't repeat yourself.
+
+Usage sketch:
+
+```
+mcp__rememberize__recall    namespace="rememberize-dev"        query="CLI friction F18"
+mcp__rememberize__search    namespace="rememberize-dev"        query="pair exchange protocol"
+mcp__rememberize__remember  namespace="rememberize-cli-agent"  content="..."
+mcp__rememberize__recall    namespace="rememberize-cli-agent"  query="last release notes draft"
+```
+
+**Always write working memory to `rememberize-cli-agent`.** Never try to `remember` / `update` / `forget` on `rememberize-dev` — the key is scoped to reject those calls, and it would be the wrong namespace anyway.
+
+### API key supply
+
+`.mcp.json` uses the literal placeholder `${REMEMBERIZE_API_KEY}`. Claude Code's MCP harness does not reliably interpolate env vars inline; the agent runtime must supply the real key. Options:
+
+1. Export `REMEMBERIZE_API_KEY=...` in the shell before launching Claude Code — some MCP wrappers pass it through to the HTTP transport.
+2. Brad pastes the real key into a local-only `.mcp.json` override (untracked) on the agent's host.
+3. The agent runtime injects it via Claude Code settings.
+
+Never commit a real key. `.gitignore` already covers common env files.

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing
+
+Thanks for your interest in `rememberize-cli`. This is a small, focused repo; most PRs are welcome if they match the scope below and arrive in a reviewable size.
+
+## Scope
+
+This repo owns:
+
+- The `rememberize` CLI binary (`cmd/rememberize/`)
+- Import/export format parsers (`internal/transfer/`)
+- The `rememberize-bundle` Claude Code skill (`skills/rememberize-bundle/`)
+- The install script (`install.sh`), release pipeline (`.goreleaser.yml`, GitHub Actions), and docs
+
+It does **not** own:
+
+- Server-side behavior of the rememberize platform
+- The pair-exchange wire protocol (coordinated with the main repo)
+- Anything on `platform.rememberize.app` or `rememberize.app` beyond the CLI's view
+
+If your bug report is a server-side issue, or your feature request requires a protocol change, flag it in an issue titled `[MAIN-REPO] ...` so the maintainer can route it to the right repo.
+
+## Filing a good issue
+
+A useful bug report has:
+
+- **What happened** (exact command, exact error, any relevant output).
+- **What you expected.**
+- **Your platform**: OS + arch (`uname -a` on macOS/Linux; `ver` or `systeminfo` on Windows).
+- **CLI version**: `rememberize --version`.
+- **Reproduction steps** if you can get them.
+
+For feature requests: describe the problem first, the proposed solution second. Small scoped asks are easier to land than big rewrites.
+
+## Submitting a PR
+
+1. **Open an issue first** for anything non-trivial so we can agree on approach before you spend time.
+2. **Branch from `main`**. Name: `feat/...`, `fix/...`, `docs/...`, `chore/...`.
+3. **Small, focused changes.** If a PR grows past ~300 lines, split it.
+4. **Conventional Commits** for commit titles:
+   - `feat(cli): add --json flag to recall`
+   - `fix(pair): handle empty namespaces array`
+   - `docs(install): clarify PATH setup on Windows`
+   - `chore(release): bump goreleaser to v2.3`
+   - `test(skill): cover empty-directory case`
+   - `ci: cache Go modules across jobs`
+5. **Tests required.** Add or update tests to cover the change. CI runs `go test -race`, `go vet`, `golangci-lint`, and a cross-platform build — all must be green.
+6. **One topic per PR.** Mixed "drive-by fix plus feature" PRs take longer to review.
+
+## Building and testing locally
+
+You need Go 1.25+. No CGO, no build tags, no platform-specific deps.
+
+```sh
+make build            # build ./bin/rememberize
+make test             # go test -race ./...
+make lint             # golangci-lint run (install: https://golangci-lint.run/)
+make install-dev      # build + copy into ~/.local/bin
+```
+
+Tests run directly on the host on macOS, Linux, and Windows.
+
+## What kinds of PRs get accepted
+
+Likely to land:
+
+- Bug fixes with a clear reproduction, a test covering the bug, and a scoped fix.
+- Docs improvements (install troubleshooting, clearer error messages, typo fixes).
+- Small user-facing CLI ergonomics (flag additions, better error text, config-file improvements).
+- Cross-platform compatibility fixes.
+- Skill improvements in `skills/rememberize-bundle/`.
+
+Unlikely to land without prior discussion:
+
+- Large refactors.
+- New top-level commands or subsystems.
+- Changes to the wire protocol with the server (we can't land those unilaterally here).
+- Dependencies on CGO or platform-specific build tags.
+- New runtime dependencies.
+
+If you're unsure, open an issue and ask before writing code.
+
+## Code of conduct
+
+Be kind. Assume good faith. We're here to ship useful software, not win arguments.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the MIT License (see [`LICENSE`](LICENSE)).