@zecalis/fael 0.12.0 → 0.14.0

package/README.md

@@ -5,14 +5,15 @@
 [![CI](https://github.com/zecalis/fael/actions/workflows/ci.yml/badge.svg)](https://github.com/zecalis/fael/actions/workflows/ci.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**The secretary for every agent on your team.** Every agent on your repo knows what was decided and
-what's still open — without re-asking, and without a context dump.
+**The secretary for every agent on your team.** Every agent on your repo gets what git can't tell
+it — why a call was made, what was rejected, what's still open — next to the file it opens.
 
 One person runs five agents; a team runs fifty — and each of those hands work to sub-agents. Every
 one of them starts from zero: it finds the same flaky test, re-asks why that function looks weird,
 and repeats the mistake the last agent already fixed.
 Memory tools that try to help stuff a summary of everything into context before the agent has said
-what it's about to do — you pay tokens for noise, and the one row that mattered gets averaged away.
+what it's about to do — the one row that mattered gets averaged away, and a summary of stale notes
+is still stale.
 
 fael works the other way round: like a good secretary, it takes the notes nobody else will and hands
 each agent **only what matters for the file in front of it**. The agent writes down what it decided
@@ -35,10 +36,15 @@ fael gives the repo a memory that agents can't skip:
   session after compaction, is told again — it no longer has them), and cut to a token budget
   (800 by default) — not a notes dump. Anything else the agent asks for itself, through MCP.
   `fael stats` shows exactly what fael has put into context.
+- **It retires what the code outgrew.** Git owns what changed; fael keeps only what git can't say.
+  When an agent edits a file, it is asked to close a row the code now says, or re-file one the
+  code contradicts — in the same message. `fael doctor` lists the rest: open rows whose files took
+  10+ commits since they were written, to check against the code.
 - **It follows the code.** Rename a file and its rows follow it (`git log -M`). Split one into
   several and `fael mv old new` points the rows at the new files.
-- **It lives in git.** Rows are plain JSONL in `.fael/`. Clone the repo and you get every decision,
-  bug and note with it — for every agent and every person on the team. No server, no account.
+- **It lives in your git, out of your branches.** Rows are plain JSONL in the clone's `.git/fael/`,
+  shared at once by every worktree, so PRs never carry log lines to conflict on. `fael sync` carries
+  them to teammates through your own remote (`refs/fael/*`). No server, no account.
 
 Works with **Claude Code, Codex and OpenCode**, and any MCP host. One small binary; hooks run in 2–3 ms.
 
@@ -51,7 +57,7 @@ Works with **Claude Code, Codex and OpenCode**, and any MCP host. One small bina
 | Agent notices a bug mid-task, then forgets it | It's filed on the spot, and shown to whoever touches that file next |
 | Two agents in parallel worktrees hit the same problem | The first files it; the second gets it when it opens the file — the same hour, before any commit |
 | A sub-agent finds something and its summary drops it | Its `fael issue: …` line is filed when it stops (Claude Code), and the parent gets it on that file |
-| Knowledge stays in one person's chat history | It's in the repo — teammates and their agents get it on `git pull` |
+| Knowledge stays in one person's chat history | It's in the clone — teammates and their agents get it on `fael sync` |
 | A PM's requirement lives in a ticket the agent never opens | `fael add decision … --files src/pay.rs` — it's in front of the agent the moment it opens the file |
 
 ## Install
@@ -59,7 +65,6 @@ Works with **Claude Code, Codex and OpenCode**, and any MCP host. One small bina
 **1. Get the binary** — prebuilt for macOS, Linux and Windows. No Rust needed.
 
 ```bash
-npm i -g @zecalis/fael               # Node
 brew install zecalis/tap/fael    # Homebrew (macOS / Linux)
 curl -LsSf https://github.com/zecalis/fael/releases/latest/download/fael-installer.sh | sh
 ```
@@ -70,6 +75,9 @@ Windows (PowerShell):
 irm https://github.com/zecalis/fael/releases/latest/download/fael-installer.ps1 | iex
 ```
 
+Or through npm: `npm i -g @zecalis/fael`. It works, but every `fael` call — including each hook —
+starts Node first, so the options above are faster.
+
 **2. Connect your agents** — once per machine.
 
 ```bash
@@ -82,7 +90,16 @@ fael install --dry-run    # show what would change, write nothing
 an old path. That's also why `npx @zecalis/fael install` is refused: npx keeps the binary in a
 throwaway cache. Install it globally first.
 
-**3. Work as usual.** The first row an agent writes creates `.fael/log/` in the repo — commit it like code.
+**3. Work as usual.** Rows land in `.git/fael/` — nothing to commit. To share them or back them up:
+
+```bash
+git config fael.remote <url>   # any git remote you can push to — origin works, a private one if the repo is public
+fael sync                      # push your rows, pull everyone else's (the Stop hook also runs it once per session)
+```
+
+Rather review memory in PRs? `store = "tracked"` in `.fael/config.toml` also writes the rows to
+`.fael/log/` in the tree, to commit like code. Repos that already have a `.fael/log/` keep that mode;
+`fael migrate local` moves one over ([docs/integrate.md](docs/integrate.md#moving-a-tracked-repo-to-local)).
 
 ## How it works
 
@@ -90,7 +107,7 @@ throwaway cache. Install it globally first.
 agent reads src/pay.rs   →  fael attaches: "[bug] refund rounds down on JPY → src/pay.rs"
 agent fixes it, replies  →  "…done. fael decision: refunds round half-up, per finance [files: src/pay.rs]"
 fael                     →  files that line as a row — no extra turn, nothing blocked
-git push                 →  the next agent, on any machine, sees it when it opens src/pay.rs
+fael sync                →  the next agent, on any machine, sees it when it opens src/pay.rs
 ```
 
 Agents use the `fael` MCP server (`find`, `add`, `close`). You can use the same log from the shell:
@@ -102,7 +119,7 @@ fael add bug "refund rounds down on JPY" --files src/pay.rs
 fael add issue "count from order date or ship date?" --to finance --files src/pay.rs
 fael close <id> "fixed in 4f2a91c"
 fael mv src/pay.rs src/pay/refund.rs                     # a split git can't see — rows follow
-fael doctor                                              # check the setup (e.g. a gitignored .fael/log)
+fael doctor                                              # check the setup (e.g. no fael.remote to back rows up)
 ```
 
 `fael` with no arguments lists every command.
@@ -112,8 +129,8 @@ fael doctor                                              # check the setup (e.g.
 
 ## Links
 
-- **npm:** [@zecalis/fael](https://www.npmjs.com/package/@zecalis/fael)
 - **Homebrew tap:** [zecalis/homebrew-tap](https://github.com/zecalis/homebrew-tap)
+- **npm:** [@zecalis/fael](https://www.npmjs.com/package/@zecalis/fael)
 - **Releases & changelog:** [GitHub Releases](https://github.com/zecalis/fael/releases)
 - **Bugs & ideas:** [Issues](https://github.com/zecalis/fael/issues)
 - **Docs:** [architecture](docs/architecture.md) · [log format](docs/format.md) (read/write it without fael) · [integrate another agent](docs/integrate.md)

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@zecalis/fael",
-      "version": "0.12.0"
+      "version": "0.14.0"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.12.0"
+  "version": "0.14.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/zecalis/fael/releases/download/v0.12.0"
+    "https://github.com/zecalis/fael/releases/download/v0.14.0"
   ],
   "bin": {
     "fael": "run-fael.js"
@@ -81,7 +81,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.12.0",
+  "version": "0.14.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"