fapony 0.7.0 → 0.7.1

package/README.md

@@ -4,12 +4,85 @@
 
 # fapony
 
-[![npm](https://img.shields.io/npm/v/fapony.svg)](https://www.npmjs.com/package/fapony) [![GitHub](https://img.shields.io/github/stars/kire21b/fapony.svg)](https://github.com/kire21b/fapony)
+[![npm](https://img.shields.io/npm/v/fapony.svg)](https://www.npmjs.com/package/fapony) [![GitHub](https://img.shields.io/github/stars/inonix-dev/fapony.svg)](https://github.com/inonix-dev/fapony)
 
-**See what your coding agents actually cost.** fapony reads the session logs Claude Code, Codex,
-OpenCode and ZCode already write, and puts them all on one yardstick — tokens, cost and time per
-model, per client, per workflow. Nothing to instrument, no per-project setup: it runs on the
-history already sitting on your disk.
+**The dev workflow for writing code with agents** — plans cut into one-session chunks, lookups
+that cost a fraction of reading the files, convention debt you can count, and what it all cost in
+tokens. It is one developer's daily flow made into commands; adopting fapony means adopting that
+flow. Memory — decisions, bugs, notes — is [fael](https://github.com/inonix-dev/fael)'s, never
+fapony's.
+
+Why chunks: a long plan run in one unbroken session only accumulates context. Every chunk here is
+its own session that opens with just the facts it needs and stops when the chunk lands.
+
+## The workflow — fapony + fael
+
+Two tools, one loop, no overlap. **fapony is the workflow** — plans cut into chunks, convention
+debt, cheap lookups, what it all cost. **[fael](https://github.com/inonix-dev/fael) is the memory** — the
+decisions, bugs and notes the next session must see. Each is useful alone; together they close
+the loop: fapony says *what's next*, fael says *what the last session learned*.
+
+| | fapony — workflow | fael — memory |
+|---|---|---|
+| Owns | plans + chunk loop, `debt`, `lint-baseline`, `review-seed` / `analyze`, usage | decisions, issues, notes (`add` / `find` / `close`) |
+| Agent surface | plan-mv guard hook, skills — **no MCP server** | MCP tools + SessionStart / read / Stop hooks |
+| Writes | plan files, only when told (`plan sweep --apply`) | its log under `.fael/` in your repo |
+| Install | `npm i -g fapony && fapony install` | `npm i -g @inonix/fael && fael install` |
+
+One chunk, one session:
+
+```mermaid
+flowchart TD
+    S([new session]) --> K["fael kickoff — SessionStart hook<br/>open decisions + issues"]
+    K --> P["fapony plan PLAN-x.md<br/>unchecked chunks + handoff notes from fael"]
+    P --> L["fapony review-seed --files …<br/>exports + importers instead of whole-file reads"]
+    L --> E["edit<br/>fael read hook: rows about that file"]
+    E --> C["tick the chunk with its sha → commit"]
+    C --> N["fael add note 'what chunk N+1 must know'<br/>--files f1,f2,PLAN-x.md"]
+    N --> X([stop — don't drag the transcript along])
+    X -->|next chunk| S
+    C -->|last chunk| W["fapony plan sweep PLAN-x.md --apply<br/>git mv into .fapony/done/"]
+```
+
+Who reads what:
+
+```mermaid
+flowchart LR
+    CC[Claude Code] --> F[fapony]
+    OC[OpenCode] --> F
+    ZC[ZCode] --> F
+    CX[Codex] --> F
+    AG[Antigravity] --> F
+    F --> U[usage — tokens & cost]
+    F --> P[plans — next chunk, sweep, check]
+    F --> D[debt — how far the move has gone]
+    M[(fael — memory)] -. read-only .-> F
+    CC & OC & CX --> M
+```
+
+fapony is opinionated: the loop above is the product, and the commands exist to make each step
+cheap. Plans and debt are per-project (`fapony init`); usage needs no setup at all.
+
+## The pieces
+
+**Plans, one chunk at a time.** `fapony plan` shows every active plan, its progress and next
+unchecked chunk; `fapony plan PLAN-x.md` opens one chunk with just the facts it needs — the
+unchecked boxes, whether the last ticked chunk's commit really exists, and the notes the previous
+session left in fael — instead of dragging the old transcript along.
+
+**Lookups instead of whole-file reads.** `fapony review-seed --files <f>` gives exports with line
+numbers and every importer for roughly a thirtieth of the tokens reading those files costs.
+
+**Convention debt.** `fapony debt` answers the question nothing else does: *we decided this six
+months ago — how far along is the move?* ESLint says this line is wrong; nothing says 11 of 47
+files have migrated. Dead code and duplication it deliberately leaves to knip and friends —
+they already do that better.
+
+## What it cost — usage
+
+fapony reads the session logs Claude Code, Codex, OpenCode and ZCode already write, and puts them
+all on one yardstick — tokens, cost and time per model, per client, per workflow. Nothing to
+instrument: it runs on the history already sitting on your disk.
 
 <p align="center">
   <img src="images/summary.webp" width="800" alt="fapony usage-web summary cards">
@@ -40,47 +113,13 @@ Raw facts from logs are hard to argue with — a vendor can dispute a verdict as
 dispute their own token count. That is the whole measurement layer: tokens and cost, nothing
 self-graded.
 
-## Past day one
-
-Two more layers, both optional, both compounding:
-
-**Memory — the mem log.** An agent has no memory of pain across sessions: it writes the 37th
-hand-rolled `try/catch` as cheerfully as the first, because every session starts new. Wrappers
-and shared libraries get built by *people* who were hurt often enough to remember. fapony
-remembers instead: one MCP call per unit of work (`mem_add`) records the decision, bug or note
-with the files it touched, and `mem_find` answers *"what was ever decided about this file?"*
-before the next agent touches it. The log lives in your repo (`.fapony/.memory/`), so it crosses
-machines over git for free.
-
-**Convention debt.** `fapony debt` answers the question nothing else does: *we decided this six
-months ago — how far along is the move?* ESLint says this line is wrong; nothing says 11 of 47
-files have migrated. Dead code and duplication it deliberately leaves to knip and friends —
-they already do that better.
-
-```mermaid
-flowchart LR
-    A[Claude Code] --> F[fapony]
-    B[OpenCode] --> F
-    C[ZCode] --> F
-    D[Codex] --> F
-    E[Cursor] --> F
-    G[Antigravity] --> F
-    F --> U[usage — tokens & cost]
-    F --> M[mem log — what was decided here]
-    F --> D[debt — how far the move has gone]
-```
-
-Adopting it doesn't change your workflow: install it, point your agent at it, read the reports.
-Both layers above are per-project (`fapony init`) and worthless on run 1 — they get more useful
-every run after, which is exactly why they're retention, not the reason to install.
-
 ## Quick start
 
 ```bash
 # 1. Install (needs Bun — https://bun.sh)
 npm install -g fapony
 #    from source instead:
-#    git clone https://github.com/kire21b/fapony.git && cd fapony && bun install && bun link
+#    git clone https://github.com/inonix-dev/fapony.git && cd fapony && bun install && bun link
 #    (`bun link` claims the global `fapony` bin by package name, not path — re-run it in the
 #    checkout you want to be the one)
 
@@ -96,17 +135,16 @@ fapony install --all        # skip the prompt, wire everything detected
 #    claude/opencode also symlink skill/<name>/ into ~/.claude/skills — an existing
 #    skill of the same name is reported, never overwritten
 
-# 4. Turn on the memory layer (per project you want it in)
+# 4. Turn on plans + debt (per project you want them in)
 fapony init /path/to/your-worktree
-#    creates .fapony/ — .memory/ (the mem log the 3 MCP tools read and write)
+#    creates .fapony/ — plan/ done/ spec/, evidence.json for `fapony report`,
 #    and conventions.json for `fapony debt` (shared rules: commit them),
-#    then offers to write the memory rules into CLAUDE.md / AGENTS.md
-#    (none yet = AGENTS.md + a CLAUDE.md that imports it) — agents only log
-#    what the rules they already read tell them to
+#    then offers to write the plan-loop rules into CLAUDE.md / AGENTS.md
+#    (none yet = AGENTS.md + a CLAUDE.md that imports it)
 fapony init /path/to/your-worktree --rules --yes   # repo already set up: rules only, no prompt
-```
 
-…or add it manually to any MCP client: `{ "mcpServers": { "fapony": { "command": "fapony", "args": ["mcp"] } } }`. Full protocol and adapter examples: [docs/mcp-handcheck.md](https://github.com/kire21b/fapony/blob/main/docs/mcp-handcheck.md).
+# 5. Memory: install fael (npm i -g @inonix/fael && fael install)
+```
 
 ## What fapony is not
 
@@ -114,69 +152,36 @@ Stated up front, because the gap between these two things is where most tooling
 
 - **It does not run your test suite.** The evidence collector runs an allowlist *you* write in
   `.fapony/evidence.json`, never a command an agent proposes. No allowlist, no evidence.
-- **It does not judge your code.** Mem rows *record* what a human or a working agent supplies.
-  fapony is the memory, not the judge.
+- **It does not judge your code** — and it holds no memory of its own; that is fael's.
 - **It checks conformance, not correctness** — that a claim lines up with git facts and that
   uncertainty was declared, not that the code works.
-- **Almost nothing blocks.** The one exception is the Stop hook, once per turn when a commit
-  lands with no new mem row; everything else only annotates.
+- **Almost nothing blocks.** The one exception is the plan-mv guard on Claude Code, which denies a
+  raw `git mv` of a plan into done/ and points at `fapony plan sweep --apply`; nothing else touches a
+  tool call.
 - **Model attribution is inferred, not declared** — reports label it `inferred`; read it as such.
-- **The knowledge layer is empty on run 1** — worth something around run 5, more every run after.
 
 ## What runs where
 
-`fapony install` wires six clients (Claude Code, OpenCode, Cursor, ZCode, Codex, Antigravity). MCP is
-the only piece all of them get — the hooks and in-process hints are per-client, and the read/edit
-hints arrive **before** the call on Claude Code but **after** it on OpenCode, whose only annotate
-channel is `tool.execute.after`. Nothing here is required: skip the hooks and every MCP tool still
-answers.
-
-| | Claude Code | OpenCode | Cursor | ZCode | Codex | Antigravity |
-|---|---|---|---|---|---|---|
-| MCP tools — `mem_find` `mem_add` `mem_close` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Stop hook — refuse to end a turn with commits but no new mem row | ✅ | — | ✅ | — | ✅ after trust | — |
-| Read hint — big-file pointer + debt/mem lines | ✅ before | ✅ after | — | — | — | — |
-| Re-read hint — unchanged repeat read | ✅ before | ✅ after | — | — | — | — |
-| Edit hint — importer count before a shape change | ✅ before | ✅ after | — | — | — | — |
-| Commit hint — `git commit` → record-a-mem-row nudge | — | ✅ after | — | — | — | — |
-| Skills symlinked into `~/.claude/skills` | ✅ | ✅ | — | — | — | — |
-| Skills symlinked into `~/.agents/skills` | — | — | — | ✅ | ✅ | ✅ |
-| `usage-scan` reads this client's session log | ✅ | ✅ | — | ✅ | ✅ | — |
-
-`—` means not wired, not impossible. Codex hooks require trust via `/hooks` before they run —
-`fapony install` tells you when. Antigravity gets MCP + skills now; its hook surface is still
-evolving, and `usage-scan` can't read its session log yet. The hints live on hooks rather than MCP
-on purpose — they must fire mid-turn without the agent deciding to call anything.
-
-## The ledger — one habit, 3 tools
-
-One habit feeds it: record a mem row when a unit of work ends. Everything else on this page is
-optional around that. The **Stop hook** is the only thing fapony *blocks* — once per turn, when a
-commit lands with no new mem row. It never judges what deserves recording. The hints only
-annotate: a big-file read points at `review-seed`, a repeat read of an unchanged file points at
-grep, an edit names the file's importer count before you change its shape.
-
-| Tool | Purpose |
-|------|---------|
-| `mem_find` | Search the project's mem log read-only — matched on the row's `files[]` (text substring for older rows), `text`, `kind` (no default filter), `since` |
-| `mem_add` | Append a mem row (decision/bug/note/next/hold) with `files[]` required and rejected when empty — the write half of `mem_find` |
-| `mem_close` | Close a mem row by id with a tombstone message — a separate tool because a close row carries no `files[]` |
-
-**A tool earns its schema by being called mid-task without being asked.** Everything you invoke
-deliberately is a CLI command instead: a tool schema is paid as input tokens in every session of
-every client whether or not it is used, while a CLI command costs nothing until it runs. That is
-why `stats`, `report`, `usage-web` and friends are CLI-only, and why four tools left the MCP
-surface in 2026-09 — the 3 mem tools keep their schemas because nobody is going to type them at
-the right moment.
-
-## The work side — conveniences, not the contract
-
-Read-only, deterministic, none of it writes anything. Skip this side entirely and fapony still
-works. **Nothing here is a precondition for anything above.**
-
-- `fapony review-seed --files src/thing/` — exports, importers, untested, for roughly a thirtieth
-  of the tokens reading those files costs. Before touching an unfamiliar file, fire this and Read
-  only the line ranges it points at. Directories work too.
+`fapony install` wires five clients (Claude Code, OpenCode, ZCode, Codex, Antigravity) — skills
+everywhere, plus the plan-mv guard on Claude Code. It also removes hooks fapony no longer ships (the
+edit hint, cut 2026-09-26: measured over two windows, it never moved an agent to migrate a file).
+Memory hooks and MCP tools are fael's (`fael install`); fapony has no MCP server.
+
+| | Claude Code | OpenCode | ZCode | Codex | Antigravity |
+|---|---|---|---|---|---|
+| Plan-mv guard — deny raw `git mv` of a plan into done/ | ✅ | — | — | — | — |
+| Skills symlinked into `~/.claude/skills` | ✅ | ✅ | — | — | — |
+| Skills symlinked into `~/.agents/skills` | — | — | ✅ | ✅ | ✅ |
+| `usage-scan` reads this client's session log | ✅ | ✅ | ✅ | ✅ | — |
+
+`—` means not wired, not impossible.
+
+## Lookups, digest and skills
+
+Read-only and deterministic — none of it writes anything.
+
+- `fapony review-seed --files src/thing/` — exports, importers, untested. Before touching an
+  unfamiliar file, fire this and Read only the line ranges it points at. Directories work too.
 - `fapony digest` — decisions, open bugs, in-flight plans, cost, on one page, from what's already
   on disk.
 
@@ -188,8 +193,8 @@ expects, so a client can symlink the directory rather than copy the file:
 | Skill | Purpose | Trigger |
 |-------|---------|---------|
 | `skill/plan-with-pony/` | Draft plan + spec from "what's in your head" via conversation | `/plan-with-pony` |
-| `skill/review-pony/` | Review as verification, wired to fapony: scope facts before (`review-seed`), a mem row after when findings survive | `/review-pony` |
-| `skill/lookup-before-edit/` | Look up unfamiliar files (`review-seed --files` + mem + debt) before reading/editing them | `/lookup-before-edit` |
+| `skill/review-pony/` | Review as verification: scope facts before (`review-seed`), a fael row after when findings survive | `/review-pony` |
+| `skill/lookup-before-edit/` | Look up unfamiliar files (`review-seed --files` + fael + debt) before reading/editing them | `/lookup-before-edit` |
 | `skill/define-convention/` | Turn a not-yet-migrated pattern into a tracked convention (interview + dry-run `debt`) | `/define-convention` |
 | `skill/move-to-done/` | Archive a shipped PLAN into .fapony/done/ | `/move-to-done` |
 | `skill/git-commit-conventional/` | Commit split by concern + conventional message | `/git-commit` |
@@ -197,63 +202,59 @@ expects, so a client can symlink the directory rather than copy the file:
 
 `plan-with-pony` is vendor-neutral — the SKILL.md *is* the prompt, so pipe it to any agent:
 `cat skill/plan-with-pony/SKILL.md | claude -p` (or `opencode run`, or anything that reads stdin).
-Example plans it produced: [examples/](https://github.com/kire21b/fapony/tree/main/examples).
+Example plans it produced: [examples/](https://github.com/inonix-dev/fapony/tree/main/examples).
 
 ### Plans your agent can answer questions about
 
 Plans stay markdown files in your repo — nothing moves into a database. Four optional frontmatter
 keys (`kind` / `status` / `blocked_by` / `blocks`) make a folder of them queryable; plans with no
 frontmatter still work, because the unchecked checkboxes are enough. Open the next session with
-`fapony mem kickoff` — it prints what is next (priority plans, the first unchecked chunk of each,
-open bugs) without reading a single 100KB plan body into context:
+`fapony plan` — it prints every active plan with its progress and first unchecked chunk without
+reading a single 100KB plan body into context:
 
 ```
-## next up
-  [1] chunk 2 — move overdue out (PLAN-calendar.md)
-  [2] bug #mu8t5qve — money drifts in the month grid…
-      → fapony mem close mu8t5qve "<msg>"
-  [3] last touched: src/quick/month.tsx, src/lib/money.ts
+# .fapony/plan/ — 3 active plan(s)
+
+- PLAN-calendar.md — 1/4 chunks · priority:high
+  next: chunk 2 — move overdue out
+- PLAN-billing.md — 0/3 chunks · blocked_by: PLAN-calendar.md
+  next: chunk 1 — money type
 ```
 
+`fapony plan PLAN-calendar.md` then shows that plan's unchecked chunks, whether the last ticked
+chunk's sha is really in git, and the open fael notes about it — close a chunk with
+`fael add note "<what chunk N+1 must know>" --files <f>,<PLAN path>` and the next session finds it.
+
 **There is no `MASTER.md`** — every line above is derived from the plan files themselves, so it
-cannot drift; a hand-kept master file always does. `fapony mem plan-check` verifies ticked chunk
+cannot drift; a hand-kept master file always does. `fapony plan check` verifies ticked chunk
 shas against git history (a ticked box with no sha to check is a claim, not a close) and flags
-dangling `blocked_by` refs; `fapony mem plan-sweep --apply` archives a shipped plan with `git mv`
+dangling `blocked_by` refs; `fapony plan sweep PLAN-x.md --apply` archives a shipped plan with `git mv`
 into `.fapony/done/` — same name, same depth, so every relative link inside the file survives the
 move. Specs live in `.fapony/spec/` and are never archived.
 
 ## CLI
 
 ```bash
-# core: memory + debt
-fapony mem add <kind> "<text>" --files f1,f2 [--key k] [spec.md]   # append a mem row (decision/bug/note/next/hold)
-fapony mem close <id> "<msg>"              # close a row (a bug stays open without this)
-fapony mem find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--open]  # search mem log
-fapony mem kickoff [<plan.md>] [--pick <n>]  # open a session + a next-up list
-fapony mem where                           # show the resolved mem dir and which step won
-fapony mem done | stale | claim | release | synced | plan-sweep | plan-check | rotate
+# core: plans + debt (memory — decisions, bugs, notes — lives in fael)
+fapony plan [<PLAN.md>]                    # active plans + next chunk; one plan: unchecked chunks + open fael rows
+fapony plan sweep [<PLAN.md>] [--apply]    # archive shipped plans into done/ + rewrite links
+fapony plan check [--quiet]                # deps, broken links, ticked-chunk shas (exit 1 on issues)
 fapony debt [--id a,b] [--where <path>]    # which files haven't migrated to a declared convention (live, read-only)
 fapony lint-baseline [--cmd ...] [--diff]  # separate "already red" from "I made it red"
-fapony init-mem                            # delete legacy .memory/ dirs + warn call sites still referencing them
 fapony digest [--since 7d|YYYY-MM-DD] [--format text|html] [--json] [--out FILE]  # single-page summary from what's on disk
 
-# usage (day one)
+# usage — what it cost
 fapony usage-scan                          # scan session logs → cache (incremental, progress bar)
 fapony price-scan                          # fetch model price table → prices.json (cache; query never fetches)
 fapony usage-web [port]                    # usage comparison dashboard from cache
 
 # lookup (read-only, never touches state)
 fapony analyze [path]                      # live repo graph: hubs, orphans, cycles, changed-untested (TS/JS + Python .py/.pyi; stdlib→external, no sys.path)
-fapony review-seed [--staged|--commit <sha>|--range <a...b>|--files f1,f2,dir|--plan <PLAN.md>]  # scope facts for a review
+fapony review-seed [--staged|--commit <sha>|--range <a...b>|--files f1,f2,dir|--plan <PLAN.md>] [--body sym[,sym]] [--callers sym[,sym]]  # scope facts for a review
 fapony plan-seed <name> [--spec] [--scope <path>[,<path>]]...  # write PLAN (+SPEC): frontmatter, capped sections, prior-art list
 
-# hooks & MCP (wired by `fapony install`, not run by hand)
-fapony mcp                                 # MCP server (stdio JSON-RPC — 3 tools)
-fapony hook-stop                           # Stop hook: block turns with commits but no mem row
-fapony hook-read-hint                      # read/re-read annotations
-fapony hook-edit-hint                      # importer count before editing shape
+# hooks (wired by `fapony install`, not run by hand)
 fapony hook-mv-guard                       # deny raw git mv of plan files into done/
-fapony hook-session-start                  # SessionStart: kickoff into context
 
 # frozen ledger (reads history only — the grading tool left the MCP surface in 2026-09)
 fapony stats [--mode verdict [--regime code|fix|review|plan|inquiry|test]]  # KPIs from old graded runs
@@ -261,8 +262,8 @@ fapony report <run-id>                     # verification report for a run
 fapony report-web [file]                   # static HTML report page
 
 # setup & maintenance
-fapony init <path>                         # scaffold .fapony/ (plan/spec/memory/evidence)
-fapony install [--all|--platform <name>|--dry-run]  # wire MCP + skills into clients
+fapony init <path>                         # scaffold .fapony/ (plan/done/spec/evidence)
+fapony install [--all|--platform <name>|--dry-run]  # wire skills + plan-mv guard into clients
 fapony setup                               # interactive wizard: config + scaffold in one step
 fapony update                              # self-update via git pull
 fapony telemetry show|send                 # opt-in only, default off — see TELEMETRY.md
@@ -271,43 +272,30 @@ fapony telemetry show|send                 # opt-in only, default off — see TE
 `fapony report <run-id>` prints the full report for a frozen-ledger run — git facts, handoff
 conformance, allowlisted evidence, the stored verdict, cost — with anything the agent claimed but
 couldn't prove marked as such. Reports are stamped with the producing build's `server_sha`; after
-editing fapony, compare the stamp against `git log -1` before trusting a report from a
-long-lived MCP server. Each allowlisted command gets `timeout_ms` (default 30s), the whole report
+editing fapony, compare the stamp against `git log -1` before trusting a report. Each allowlisted command gets `timeout_ms` (default 30s), the whole report
 capped at 180s — a command that doesn't fit reports as `timeout`, never as a pass. If your
 `.gitignore` ignores `.fapony/` wholesale, re-include the file: `**/.fapony/*`, then
 `!**/.fapony/evidence.json`.
 
-*When* to call `mem add` is your project's call, not fapony's — write it in your own
-`AGENTS.md`/`CLAUDE.md`. A starting point:
-
-```markdown
-## Memory
-- Found a bug while working (not just user-reported)? Log it before fixing:
-  mem_add { kind: "bug", worktree: "<absolute app dir>", files: [...], text: "..." }
-- `text` must stand alone — read months later with no chat context: what/where/repro/status.
-- Don't fold the fix into the same chunk — log first, fix as its own next/chunk if you do.
-```
-
 ## Config
 
 `fapony.config.json` lives in the fapony checkout and is gitignored (it's per-machine). Copy
-[fapony.config.example.json](https://github.com/kire21b/fapony/blob/main/fapony.config.example.json)
+[fapony.config.example.json](https://github.com/inonix-dev/fapony/blob/main/fapony.config.example.json)
 for a complete working reference; every section is optional. Key fields: `worktrees`
-(name → path), `memory` (shell commands, or `null` to disable), `paths` / `safety`,
+(name → path), `memory` (shell commands the frozen ledger runs; off unless set), `paths` / `safety`,
 `usageWeb { port, hostname }`. Env overrides: `FAPONY_CONFIG`, `FAPONY_STATE_DIR` (state DB;
-default `~/.config/fapony/`), `FAPONY_NO_REREAD_HINT=1`.
+default `~/.config/fapony/`).
 
 ## Scope
 
-**Supported:** MCP server (3 mem tools, any MCP client) · cross-client usage on one yardstick ·
-per-project mem log + convention debt · per-client hooks ([matrix above](#what-runs-where)) ·
+**Supported:** cross-client usage on one yardstick · per-project plans + convention debt ·
+per-client hooks ([matrix above](#what-runs-where)) ·
 vendor-neutral skills (anything that reads stdin) · opt-in telemetry, off by default
-([TELEMETRY.md](https://github.com/kire21b/fapony/blob/main/TELEMETRY.md) lists exactly what
+([TELEMETRY.md](https://github.com/inonix-dev/fapony/blob/main/TELEMETRY.md) lists exactly what
 leaves the machine) · Bun-only; run state in SQLite via `bun:sqlite` (WAL mode).
 
-**Not supported (yet):** PreToolUse hints on Cursor, ZCode, Codex or Antigravity — Cursor has no
-such hook, the other two expose no in-process hook surface for read/edit hints, and Antigravity's
-hook surface is still evolving. A hosted or shared ledger —
+**Not supported (yet):** the plan-mv guard outside Claude Code. Memory of any
+kind — that is [fael](https://github.com/inonix-dev/fael). A hosted or shared ledger —
 `FAPONY_STATE_DIR` on a synced folder works as an experiment only; SQLite's WAL mode does not
 tolerate concurrent writers over NFS/Dropbox/iCloud Drive and can corrupt the db under real
 contention.

package/package.json

@@ -1,18 +1,17 @@
 {
   "name": "fapony",
-  "version": "0.7.0",
-  "description": "Token usage across Claude Code, OpenCode, Codex & ZCode on one yardstick — plus a project mem log and convention-debt tracker agents query via 3 MCP tools. No server, your data stays local",
+  "version": "0.7.1",
+  "description": "Token usage across Claude Code, OpenCode, Codex & ZCode on one yardstick — plus plans run chunk by chunk and a convention-debt tracker. No server, your data stays local",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",
-  "homepage": "https://github.com/kire21b/fapony#readme",
+  "homepage": "https://github.com/inonix-dev/fapony#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kire21b/fapony.git"
+    "url": "git+https://github.com/inonix-dev/fapony.git"
   },
   "keywords": [
-    "mcp",
-    "mcp-server",
     "agent",
+    "token-usage",
     "claude-code",
     "opencode",
     "coding-agent"

package/skill/define-convention/SKILL.md

@@ -8,8 +8,8 @@ description: Turn "files that haven't migrated yet" into a tracked convention
 One convention = the pattern to use (`ok`) + the pattern meaning not-yet-migrated
 (`stale`) + scope (`where`) + an optional file condition (`guard`). The output is
 one row in `<worktree>/.fapony/conventions.json` (`{"conventions": [...]}`), in the
-same `.fapony/` dir as the mem log — run `fapony mem where`, go up one level, that
-is where the file lives (app-scoped in a monorepo). No file there yet = create it;
+nearest `.fapony/` at or above the code — the same dir `fapony plan` lists plans
+from (app-scoped in a monorepo). No file there yet = create it;
 a file with rows = append only, never rewrite other rows.
 
 ## Phase 1 — One question, then the checker question
@@ -68,7 +68,7 @@ Read it literally — every outcome names its fix:
   Phase 3.
 - `0 convention(s)` after `--id` → that id does not exist (misspelling — a dropped
   row still prints its `⚠`). Only `no conventions.json in <dir>` means you wrote
-  to the wrong `.fapony/` (re-check `mem where`).
+  to the wrong `.fapony/` (the nearest one above the code — `fapony plan` names it).
 
 ## Later
 

package/skill/lookup-before-edit/SKILL.md

@@ -38,7 +38,8 @@ per file, the rest as `(+N)`, so the total is still readable. That is your entry
 
 ## History + debt (same paths, two calls)
 
-- `mem_find` with `files: [<same paths>]` — "what was ever decided about this file" (MCP, no CLI spawn).
+- fael `find` with `files: [<same paths>]` (or `fael find --files <paths>`) — "what was ever decided about
+  this file". fael already attaches these rows when you Read a file, so call it only for paths you skip reading.
 - `fapony debt --where <dir|file>` — conventions this path still violates; empty until `conventions.json` exists.
 
 ## After the lookup

package/skill/move-to-done/SKILL.md

@@ -37,26 +37,26 @@ You are about to move a PLAN that has been shipped to the archive.
    A plan that is merely *waiting* (on a person, a customer, a decision) is **not** dead and does
    not move — mark it `status: blocked` + `blocked_by: <what you are waiting for>` and leave it in
    `plan/` — the frontmatter is for the next person reading the folder, and the plan stays out
-   of `done/`, which is what `plan-sweep` and `kickoff` go by. Never `--apply` a blocked file;
+   of `done/`, which is what `fapony plan` and `plan sweep` go by. Never `--apply` a blocked file;
    a blocked file with all chunks ticked is deferred doc debt — ask the user: ship it or keep
    waiting.
 
- 1c. **Check the dep graph before moving** — `fapony mem plan-check` reads `blocked_by`/`blocks`
+ 1c. **Check the dep graph before moving** — `fapony plan check` reads `blocked_by`/`blocks`
     and says what a human would miss: a `blocked_by` pointing at a file that is not in `plan/`
     or `done/`, a blocker already in `done/` while the dependent is still `status: blocked`,
     a waiter cycle, and a blocked plan with all chunks ticked. Fix its issues first — a move
     on top of a broken graph just relocates the confusion.
 
-2. **Run `plan-sweep --apply`** — this does the `git mv`, rewrites markdown links inside the
+2. **Run `fapony plan sweep --apply`** — this does the `git mv`, rewrites markdown links inside the
    file and inbound links from every `.md` under `.fapony/` (`plan/`, `done/`, `spec/`),
    warns about plain-text mentions and about tracked files outside `.fapony/` that still
    name the file, prints a `🔓 <shipped> — <waiter> lists it as blocker` line when the ship
    unblocks a waiting plan (copy that line into your summary — the waiter keeps
-   `status: blocked` until its owner clears it), and logs a decision row — all in one call:
+   `status: blocked` until its owner clears it) — all in one call:
    ```bash
-   fapony mem plan-sweep <PLAN-foo.md> --apply
+   fapony plan sweep <PLAN-foo.md> --apply
    ```
-   It refuses if the file lacks a shipped header or has open mem rows (next/bug/hold/decision/note).
+   It refuses if the file lacks a shipped header or fael still has an open issue about it (notes and decisions travel with the plan).
    If git refuses ("not under version control" — `.fapony/` is gitignored in this repo), plain
    `mv` instead; there's nothing to commit for an untracked path, so skip step 4 in that case.
    The filename gets no date prefix — the ship date is already in the header (step 1).
@@ -71,20 +71,17 @@ You are about to move a PLAN that has been shipped to the archive.
    chore(plan): archive PLAN-foo.md (shipped <hash>)
    ```
 
-5. **Leave a note when the ship taught something** — `plan-sweep --apply` (step 2)
-   already logged the ship itself as a decision row, so a clean ship needs nothing
-   more. When the plan hit something a reader could not get from the diff, call the
-   `mem_add` MCP tool (fapony) once:
+5. **Leave a note when the ship taught something** — the move itself is in git, so a
+   clean ship needs nothing more. When the plan hit something a reader could not get
+   from the diff, call fael's `add` tool (or `fael add`) once:
    - `kind`: `note`
    - `text`: what the symptom looked like, where the cause actually was, and the
      rule that follows. Standalone prose — it is read months later with no access
      to this conversation. Write one only then — "clean ship" files nothing, and a
      note that repeats the diff teaches the next session nothing
    - `files`: repo-relative paths this plan touched (`git diff --name-only <base>..HEAD`)
-   - `spec`: the archived plan's path (post-move, e.g. `.fapony/done/PLAN-foo.md`)
-   - `worktree`: **absolute path** (`git rev-parse --show-toplevel`) — every other
-     fapony tool scopes by absolute path too; a bare repo name won't match them
-   Skip only if fapony's MCP tools aren't available in this session — don't block the archive on it.
+     plus the archived plan's path (post-move, e.g. `.fapony/done/PLAN-foo.md`)
+   Skip only if fael isn't available in this session — don't block the archive on it.
 
 ## Example
 
@@ -92,25 +89,24 @@ You are about to move a PLAN that has been shipped to the archive.
 Input: .fapony/plan/PLAN-kickoff.md, no shipped header yet
 Steps:
 1. stamp header: > ✅ **shipped 2026-09-13** (a1b2c3)
-2. fapony mem plan-sweep .fapony/plan/PLAN-kickoff.md --apply
-   → moved, links rewritten, decision logged
+2. fapony plan sweep .fapony/plan/PLAN-kickoff.md --apply
+   → moved, links rewritten
 3. spec: untouched, stays in .fapony/spec/
 4. commit
-5. (clean ship — plan-sweep's decision row already recorded it, nothing more to file)
+5. (clean ship — the move is in git, nothing more to file)
 ```
 
 A ship worth a note looks like this instead:
 
 ```
-5. mem_add(kind="note",
+5. add(kind="note",
      text="sheet scroll reset on open, not close — the restore hook was on the wrong side; the router's own scrollRestoration resets on every navigate(). Check the router option before writing a restore hook.",
-     files=["src/routes/expenses/index.tsx"], spec=".fapony/done/PLAN-quick-nav.md",
-     worktree="/Users/you/Project/vela")
+     files=["src/routes/expenses/index.tsx", ".fapony/done/PLAN-quick-nav.md"])
 ```
 
 ## If fail
 
 - No git repo / no commits (can't derive a shipped hash) → tell user: "Add header > ✅ **shipped** (<hash>) first"
 - Stamped the header yourself → always say which hash you used
-- plan-sweep refuses (open mem rows) → close them or use `MEM_FORCE=1`
-- Too many inbound links → plan-sweep reports them; too many to fix → report the list
+- plan sweep refuses (open fael issue) → fix and `fael close` it, or `MEM_FORCE=1`
+- Too many inbound links → plan sweep reports them; too many to fix → report the list

package/skill/plan-with-pony/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-with-pony
-description: Draft a plan + spec from "what's in your head" — one question, then a draft you correct. Vendor-neutral — works with Claude Code, OpenCode, Codex, ZCode. Seeds the factual sections from the code and the fapony ledger when the CLI is wired up. Trigger on /plan-with-pony and when the user asks to plan or brainstorm a feature.
+description: Draft a plan + spec from "what's in your head" — one question, then a draft you correct. Vendor-neutral — works with Claude Code, OpenCode, Codex, ZCode. Seeds the factual sections from the code and fael memory when the CLI is wired up. Trigger on /plan-with-pony and when the user asks to plan or brainstorm a feature.
 ---
 
 # plan-with-pony — start from what's in your head
@@ -88,7 +88,7 @@ fapony plan-seed <feature> --spec --scope <path>
 One command, no MCP round trip. It writes `<planDir>/PLAN-<feature>.md` +
 `<specDir>/SPEC-<feature>.md` — the frontmatter, the 8 empty sections, a `## 8. References` list
 of shipped plans that already touched this scope, and a `## Context (fapony)` block under the
-TL;DR (recent mem decisions plus what is already in scope — one line per scope file with its
+TL;DR (recent fael decisions plus what is already in scope — one line per scope file with its
 exports; needs `--scope` to list anything). No ledger-ranking line: the ledger is frozen and
 cross-model ranking claims are off the table, so the seed does not point at them. SPEC chunks carry
 verbatim signatures, hard-capped (PLAN ≤ ~60 / SPEC ≤ 200 lines), and capped lines say what was
@@ -149,7 +149,7 @@ normal — writing to the default there scatters plans into a directory nobody r
 by hand, this check is yours.)
 
 **Editing a plan someone is executing right now is a different job from drafting one.** Ask the
-dev, or run `fapony mem kickoff` — it reads the same plan files and names the first unchecked
+dev, or run `fapony plan` — it reads the same plan files and names each plan's first unchecked
 chunk, so a plan already in flight is the one you are about to edit under someone. When that is the case:
 
 - **Anything you add is an instruction, not a note.** A measured fact parked under "don't do"
@@ -189,7 +189,7 @@ only place that ordering stays true.
 
 **The TL;DR is 15 lines, hard cap, and is the only part that changes while the work is in flight**
 (tick a box, stamp a short sha). Everything below it is the agreement. A TL;DR allowed to grow
-becomes a second copy of the plan, and then neither copy can be trusted. `fapony mem kickoff` reads the
+becomes a second copy of the plan, and then neither copy can be trusted. `fapony plan` reads the
 checkboxes in the **first `##` section only**, so section 6 stays detail rather than status.
 
 Section 6 — every step must be verifiable. Section 8 — must link back to anything it came from. **A step that needs something the system does not store yet** ("the month the accountant has seen",