wayform 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,166 +1,217 @@
1
1
  # Wayform
2
2
 
3
- **Shared planning memory for teams that build with AI.** A decision made in one
4
- person's Claude session is already loaded in their teammate's Cursor session —
5
- automatically, at session start, with nobody pasting anything.
3
+ **A plan layer for teams that build with agents.** One prompt becomes a full
4
+ engineering plan — built from the repo in front of the agent plus the team's
5
+ settled decisions — that stays a living, versioned document as the team
6
+ revises it, ships it, and moves on to the next one. Every teammate's agent
7
+ reads the same plans and the same decision history, in whatever client they
8
+ use: Claude Code, Cursor, Codex, or any MCP client.
9
+
10
+ Works from day one for a single developer; a team simply adds more writers to
11
+ the same space.
6
12
 
7
13
  ```
8
- you (Claude Code) teammate (Cursor)
9
- │ │
10
- │ "we decided X because Y" │ new session opens
11
- ▼ ▼
12
- write_context ──► shared git repo ──► session-start hook
13
- (your repo, injects every decision
14
- your history) as already-known context
14
+ you teammate
15
+ │ plan_brief → write the plan │
16
+ │ create_plan → transition to active │ new session opens
17
+ ▼ ▼
18
+ gateway (shared space) ───────► session-start briefing
19
+ │ transition to building → shipped injects settled decisions
20
+ ▼ and in-flight plans
21
+ decisions join the team's memory
15
22
  ```
16
23
 
17
24
  ## Why this exists
18
25
 
19
- AI pair-programming has a memory problem, and it's worse in teams. Every session
20
- starts cold. Every collaborator re-explains the same settled decisions to their
21
- own agent, every day. The context that matters — *what we decided and why* —
22
- lives in Slack scrollback and people's heads.
23
-
24
- Wayform fixes the loop with three properties nothing else combines:
25
-
26
- - **Multiplayer.** One shared store per team. Your agent reads what your
27
- teammate's agent wrote. Attribution is git commit authorship — you always know
28
- who decided what, when.
29
- - **Vendor-neutral.** Works identically across **Claude Code, Cursor, and
30
- Codex** (plus any MCP client). The store, the tool contract, and the injected
31
- context are byte-identical across tools — a decision written from Cursor lands
32
- in a Claude session and vice versa. Switching AI tools never loses your
33
- team's memory.
34
- - **You own the data.** The store is a **private git repo in your account** —
35
- append-only log, immutable commits, full history, `git log` as the audit
36
- trail. We rent git's consistency model; we don't rebuild it. No vendor
37
- database holds your team's decisions.
38
-
39
- **The write model is deliberately curated:** a write is *"we decided X because
40
- Y"* — settled decisions and durable context, not a firehose of reasoning
41
- tokens. That's what keeps the store worth injecting into every session instead
42
- of degrading into a junk drawer.
26
+ AI pair-programming has a memory problem, and it compounds in teams. Every
27
+ session starts cold. Plan mode in a coding agent throws away everything the
28
+ team already decided, so a plan can silently contradict a settled call — or a
29
+ collaborator re-explains the same context to their own agent, every day. The
30
+ context that matters — *what we decided, why, and what's already in flight* —
31
+ lives in Slack scrollback, `docs/plans/*.md` nobody re-reads, and people's
32
+ heads.
33
+
34
+ Wayform makes the **plan** the shared object instead of a local markdown file
35
+ or a throwaway plan-mode transcript:
36
+
37
+ - **Plans are briefed, not blind.** Before an agent writes a plan, `plan_brief`
38
+ hands it the team's relevant decisions, constraints, and any related
39
+ in-flight plans — so the plan starts from what's already settled instead of
40
+ contradicting it.
41
+ - **Plans are living documents.** A plan is created, revised, and moved through
42
+ a lifecycle (draft → active → building → shipped) as a versioned record any
43
+ teammate's agent can read or edit — never a local file only one person has
44
+ open.
45
+ - **Shipping a plan writes memory.** When a plan ships, the decisions it
46
+ produced join the team's shared memory, so the next plan (or the next
47
+ session, for anyone) starts from them.
48
+ - **Vendor-neutral.** One remote MCP server, the same tool contract, works
49
+ identically in Claude Code, Cursor, Codex, or any MCP client that speaks
50
+ Streamable HTTP + OAuth.
51
+ - **You own the data.** The store backing every plan and decision is a
52
+ **private git repo in your own GitHub account** — append-only, full history,
53
+ `git log` as the audit trail. No vendor database holds your team's plans.
54
+
55
+ **The product plane is remote MCP only.** A local git/stdio mode exists in
56
+ `src/` for legacy installs; it is not the path this project ships or
57
+ maintains going forward — see [Legacy: local mode](#legacy-local-mode).
43
58
 
44
59
  ---
45
60
 
46
- ## Quickstart (local mode)
61
+ ## How it works
62
+
63
+ 1. **Brief.** Before writing a plan (including in plan mode), the agent calls
64
+ `plan_brief(project, prompt)` with the task in the user's own words. It
65
+ returns the decisions and constraints that bind the work, related in-flight
66
+ plans, and fact ids to inherit — it does not write the plan for you.
67
+ 2. **Write and record.** The agent writes the plan from that brief plus the
68
+ repo, then calls `create_plan(project, title, body, inherits: [...])`. The
69
+ plan comes back numbered (`#N`) and starts as `draft`.
70
+ 3. **Move it forward.** `transition_plan` advances the plan: `active` once the
71
+ team agrees, `building` once an agent starts implementing, `shipped` once
72
+ it merges. `edit_plan` revises the body at any point before it ships; every
73
+ edit keeps the prior version readable.
74
+ 4. **Decisions join memory.** Shipping a plan passes `decisions` — the atomic,
75
+ self-contained calls the plan settled, each with its "because" — into the
76
+ team's shared memory (`write_context`'s ledger), where `search_memory` and
77
+ `plan_brief` will find them for the next plan.
78
+ 5. **Every session starts briefed.** The session-start hook injects the
79
+ project's canon decisions, recent activity, and a topic manifest before the
80
+ agent does anything — reads are guaranteed, not hoped for.
81
+ 6. **The guard catches contradictions in flight.** Before a mutating tool call
82
+ (an edit or a shell command), the proposed action is checked against the
83
+ team's live decisions; a contradiction needs the user's confirmation
84
+ before it runs. See [The guard](#the-guard).
85
+ 7. **The plan mirror keeps plans visible in-repo.** An admin can turn on
86
+ writing every in-flight plan as read-only markdown into
87
+ `.wayform/plans/<N>-<title>.md` in each teammate's checkout — gitignored,
88
+ never part of the repo's history. See [Plan mirror](#plan-mirror).
47
89
 
48
- Three steps: install the CLI, create the shared repo, wire your project.
90
+ ---
49
91
 
50
- ### 1. Install the CLI (once per machine)
92
+ ## Hosted quickstart
51
93
 
52
- ```bash
53
- git clone https://github.com/skandaramanan/Wayform /tmp/wayform \
54
- && npm install -g /tmp/wayform
55
- ```
94
+ There are three roles: the **gateway operator** deploys the Worker once (see
95
+ [gateway/README.md](gateway/README.md)); a **team leader** creates the space;
96
+ each **member** connects their client. As a team leader or solo user:
56
97
 
57
- Requires Node ≥ 18. `dist/` is pre-built and committed, so no build step runs
58
- on install.
98
+ ### 1. Get allowlisted
59
99
 
60
- > **Why not `npm install -g github:...`?** npm 10 has a git-global-install bug
61
- > (the package is symlinked to an ephemeral cache dir that never gets checked
62
- > out) that makes the one-liner fail with `command not found` or `ENOTDIR`.
63
- > The clone-then-install path above uses npm's copy path and works everywhere.
64
- > See [Troubleshooting](#troubleshooting).
100
+ Ask the gateway operator to add your GitHub login or org to the allowlist and
101
+ send you the MCP URL (default production URL:
102
+ `https://memorylayer-gateway.memory-layer.workers.dev`). No token, ever.
65
103
 
66
- ### 2. Create the shared context repo (once per team)
104
+ ### 2. Create the space repo
67
105
 
68
- One person creates a **private** git repo (e.g. `yourteam-memory`) and grants
69
- each collaborator push access. This is the team's memory; it starts empty. The
70
- v1 "shared key" is simply git access to this repo — an HTTPS URL with a token,
71
- or SSH. No accounts, no separate auth.
106
+ Create a **private** GitHub repo (e.g. `yourteam-memory`) and give it a
107
+ first commit. This repo *is* your team's memory — every decision and plan edit lands
108
+ here as a commit, in your account, under your history.
72
109
 
73
- ### 3. Wire it into your project
110
+ ### 3. Initialize this product repo
74
111
 
75
- From your project repo:
112
+ In the product repo (the codebase you work in — not the memory repo):
76
113
 
77
114
  ```bash
78
- wayform init
115
+ npm i -g wayform
116
+ wayform init --remote --clients cursor,claude
79
117
  ```
80
118
 
81
- `init` writes, idempotently and without clobbering existing config:
119
+ Pick only the clients this project actually uses. This writes
120
+ project-scoped, URL-only configuration (`.mcp.json`, `.cursor/mcp.json`,
121
+ `.codex/config.toml`, …, plus `.wayform-hook.env`) — no credential in any of
122
+ it. Never add Wayform to a user-global MCP file, or it follows you into
123
+ unrelated folders.
82
124
 
83
- - **Session-start read hooks + MCP registration** for Claude Code
84
- (`.claude/settings.json`, `.mcp.json`), Cursor (`.cursor/hooks.json`,
85
- `.cursor/mcp.json`), and Codex (`.codex/hooks.json` and project
86
- `.codex/config.toml`)
87
- - **End-of-turn write-review hooks** (the Stop hook — see
88
- [The loop](#the-loop-how-reads-and-writes-actually-happen))
89
- - Your per-user, **gitignored** `.memorylayer-hook.env` (identity + repo URL —
90
- secrets never enter git)
125
+ ### 4. Connect and pick the memory repo
91
126
 
92
- One person commits the project configs; each teammate runs `wayform init`
93
- once to set their own identity. Done — the next coding session in that project
94
- starts with the team's context already loaded.
127
+ Connect the `wayform` MCP server and sign in with GitHub. Follow the guided
128
+ App installation and select **only** the private memory repo from step 2.
129
+ Public or branchless repos are rejected. The App gets Contents read/write on
130
+ exactly that repo — nothing else in your account.
95
131
 
96
- **Verify the round-trip:** from a session, say *"record this decision: testing
97
- Wayform, because we just set it up."* Then have a teammate (or a second
98
- machine) open a fresh session — the decision should be in their context without
99
- anyone pasting it. That round-trip is the product.
132
+ ### 5. Hook login (once per machine)
100
133
 
101
- ---
134
+ ```bash
135
+ wayform login
136
+ ```
102
137
 
103
- ## Hosted gateway
104
-
105
- The local mode above needs each member to hold a git token. The **hosted
106
- gateway** removes even that: a stateless Cloudflare Worker exposes the same
107
- tools over **MCP Streamable HTTP**. Identity is **GitHub OAuth** (the same App
108
- that writes the memory repo). Members never copy, paste, or store a Wayform
109
- credential.
110
-
111
- Wayform is **vendor-neutral**. The same URL works in Cursor, Claude Code,
112
- Codex, Devin, Antigravity, or any MCP client that speaks Streamable HTTP +
113
- OAuth. Configure it in **this product repo** (the codebase you work in) — never
114
- as a user-global MCP, or it will follow you into unrelated folders.
115
-
116
- Every customer is a new team. The operator allowlists their GitHub user or org;
117
- they create their own private memory repo, initialize project-scoped config,
118
- and select that memory repo in the guided App installation. Teammates are
119
- invited in-agent by GitHub username.
120
-
121
- **Operator (once per client):** add their GitHub login or org to the allowlist,
122
- then send the MCP URL. Never send a token.
123
-
124
- **They do:**
125
-
126
- 1. On GitHub, create a **private** team-memory repo and give it a first commit
127
- (for example, initialize it with a README).
128
- 2. In the product repo, run
129
- `wayform init --remote --clients cursor,claude` with the clients the team
130
- actually uses. This writes URL-only, project-scoped configuration.
131
- 3. Connect the `wayform` MCP server. Sign in with GitHub, follow the guided App
132
- installation, and select only the private memory repo from step 1.
133
- 4. Run `wayform login` once on the machine so session hooks can authenticate.
134
- 5. Run `wayform doctor`; resolve every failed hosted check before continuing.
135
- 6. Ask the agent to record a test decision, then open a new session and confirm
136
- that decision is already present.
137
- 7. Commit the URL-only project configuration. Teammates run remote init and
138
- authenticate; nobody copies a credential.
138
+ Session-start and guard hooks authenticate via the OS credential store after
139
+ this — no pasted secret.
139
140
 
140
- ### Client setup (project-scoped, OAuth)
141
+ ### 6. Run diagnostics
141
142
 
142
- Same URL everywhere. OAuth credentials are managed internally by each MCP
143
- client or the native OS credential store; users never copy or configure them.
143
+ ```bash
144
+ wayform doctor
145
+ ```
146
+
147
+ Resolve every failed hosted check before relying on the loop.
148
+
149
+ ### 7. Verify the round-trip
150
+
151
+ Ask the agent to record a test decision (or draft a small plan), open a new
152
+ session, and confirm the context is already there. Check the memory repo on
153
+ GitHub for a new commit, authored as you. Then commit the generated,
154
+ credential-free project config so teammates only need to authenticate.
155
+
156
+ ### Client setup (project-scoped, OAuth)
144
157
 
145
158
  | Client | Project file (commit this) | Do **not** use (global) | Authenticate |
146
159
  |---|---|---|---|
147
- | **Cursor** | `.cursor/mcp.json` → `{ "mcpServers": { "wayform": { "url": "…" } } }` | `~/.cursor/mcp.json` | Connect |
148
- | **Claude Code** | `.mcp.json` (same JSON), or `claude mcp add --transport http --scope project wayform <url>` | `--scope user` | `claude mcp login wayform` |
149
- | **Codex** | `.codex/config.toml` → `url` + `auth = "oauth"` | `~/.codex/config.toml` | `codex mcp login wayform` |
150
- | **Devin CLI** | `.devin/mcp_config.json` → `{ "url": "…", "transport": "http" }` | `--scope user` / `~/.config/devin/mcp_config.json` | `devin mcp login wayform` |
151
- | **Antigravity** | `.agents/mcp_config.json` → `{ "serverUrl": "…" }` | `~/.gemini/config/mcp_config.json` | Authenticate in MCP settings (DCR) |
160
+ | **Cursor** | `.cursor/mcp.json` → `{ "mcpServers": { "wayform": { "type": "http", "url": "…/mcp" } } }` | `~/.cursor/mcp.json` | Connect |
161
+ | **Claude Code** | `.mcp.json` (same JSON), or `claude mcp add --transport http --scope project wayform <url>/mcp` | `--scope user` | `claude mcp login wayform` |
162
+ | **Codex** | `.codex/config.toml` → `[mcp_servers.wayform]` with `url` + `auth = "oauth"` | `~/.codex/config.toml` | `codex mcp login wayform` |
163
+ | **Devin CLI** | `.devin/mcp_config.json` → `{ "url": "…/mcp", "transport": "http" }` | `--scope user` / `~/.config/devin/mcp_config.json` | `devin mcp login wayform` |
164
+ | **Antigravity** | `.agents/mcp_config.json` → `{ "mcpServers": { "wayform": { "serverUrl": "…/mcp" } } }` | `~/.gemini/config/mcp_config.json` | Authenticate in MCP settings (DCR) |
152
165
 
153
- `wayform init --remote --clients cursor,claude` writes **only** those
154
- clients' files. With `--yes` and no `--clients`, it updates folders
155
- already in the repo and does not create the rest. `wayform doctor` says
156
- "run wayform login" when the hook session is missing — never "paste a token".
166
+ `wayform init --remote --clients cursor,claude` writes only those clients'
167
+ files. With `--yes` and no `--clients`, it updates folders already present in
168
+ the repo rather than creating the rest. `wayform doctor` says "run wayform
169
+ login" when the hook session is missing — never "paste a token".
157
170
 
158
171
  Do **not** add Wayform as a Devin Cloud **organization-wide** MCP if you only
159
- want it in this repo — that surface is shared across the org, not one folder.
172
+ want it in this one repo — that surface is shared across the org.
160
173
 
161
- Endpoints, allowlist, and the deploy runbook live in
174
+ Endpoints, the operator deploy runbook, and space administration
175
+ (`invite_member`, `revoke_member`) live in
162
176
  [gateway/README.md](gateway/README.md).
163
177
 
178
+ ### Build a plan
179
+
180
+ ```bash
181
+ wayform build 17 # or: wayform build 17 --client codex --project acme
182
+ ```
183
+
184
+ Run from your repo after `wayform init --remote`. It launches your own coding agent
185
+ (Claude Code, Cursor or Codex) interactively in your terminal with the
186
+ installed `wayform-build` skill; the agent builds plan #17 with one subagent
187
+ per checklist item, each briefed with the team's decisions, and ticks the plan
188
+ as it goes. No headless runs, no hosted execution.
189
+
190
+ ---
191
+
192
+ ## MCP tools
193
+
194
+ All 16 tools the gateway exposes over MCP (`gateway/src/mcp-tools.ts`):
195
+
196
+ | Tool | What it does |
197
+ |---|---|
198
+ | `plan_brief` | Brief a new plan: the settled decisions, constraints, and related in-flight plans that bind it, before you write anything. Read-only. |
199
+ | `task_brief` | Brief one task of a plan for a subagent: the decisions that bind that task, as text to paste at the top of its prompt. Read-only. |
200
+ | `create_plan` | Record a new engineering plan (markdown) as a living, versioned document the team and every agent can read. Starts as `draft`. |
201
+ | `read_plan` | Read one plan's state, decisions, and body — or list a project's plans. Read-only. |
202
+ | `edit_plan` | Revise a draft/active/building plan's body or title; every edit is a new version, old ones stay readable. Pass `base_rev` (shown by `read_plan`) to reject the edit if the plan changed since. |
203
+ | `transition_plan` | Move a plan through draft → active → building → shipped (or mark it superseded); shipping turns its decisions into memory. |
204
+ | `set_plan_mirror` | Turn on/off mirroring a project's in-flight plans as read-only markdown into every teammate's repo. Admin only. |
205
+ | `read_context` | Pull shared planning context: a recency snapshot, or (with `query`) relevance-ranked results across the whole indexed history. Read-only. |
206
+ | `write_context` | Append one settled decision or durable context; each write is its own commit, attributed to the writer. |
207
+ | `search_memory` | Search all recorded decisions/context before contradicting, re-deciding, or re-asking something that may already be settled. Read-only. |
208
+ | `memory_feedback` | Mark a retrieved fact `useful`, `wrong`, or `stale`. |
209
+ | `supersede_facts` | Confirm which existing facts a new entry actually replaces or corrects. |
210
+ | `invite_member` | Grant a GitHub user access to this space by username — no token ever changes hands. Admin only. |
211
+ | `revoke_member` | Remove a GitHub user (pending invite or live member) from this space. Admin only. |
212
+ | `list_sessions` | List every client currently connected to your own Wayform account. Read-only. |
213
+ | `revoke_session` | Disconnect one client from your own account (e.g. after losing a laptop). |
214
+
164
215
  ---
165
216
 
166
217
  ## The guard
@@ -168,19 +219,36 @@ Endpoints, allowlist, and the deploy runbook live in
168
219
  Reading decisions back is half the loop. The other half is catching an agent
169
220
  about to contradict one.
170
221
 
171
- With the hosted gateway configured, `wayform init` wires a `PreToolUse` hook in
172
- Claude Code. Before any `Edit`, `Write`, or `Bash`, the proposed action is
173
- checked against the team's live decisions. If it contradicts one, you get a
174
- confirmation prompt naming the decision, who made it, and when:
222
+ With the hosted gateway configured, `wayform init` wires a pre-tool hook in
223
+ Claude Code, Cursor and Codex. Before any edit or shell command, the proposed
224
+ action is checked against the team's live decisions. If it contradicts one, you
225
+ get a confirmation prompt naming the decision, who made it, and when:
175
226
 
176
227
  > **Wayform — this contradicts a recorded team decision:**
177
228
  > We ruled out a second datastore; Postgres is not being added.
178
229
  > — Skanda, 2026-07-12
179
230
 
180
- It **asks**; it never blocks. Reads are never guarded, so only mutating tools
181
- pay any latency, capped at 1.5s before the check gives up and allows.
231
+ How you confirm depends on the client, because only Claude Code's hook can ask:
232
+
233
+ | Client | Tools guarded | On a contradiction |
234
+ | --- | --- | --- |
235
+ | Claude Code | `Edit`, `Write`, `Bash` | Native permission prompt (verified live). |
236
+ | Cursor | `Shell`, `Write`, `StrReplace`, `Edit`, `Delete` | Blocked; the agent asks you, and only if you confirm calls `guard_allow` with the block's ticket and retries (verified live). |
237
+ | Codex | `Bash`, `apply_patch` | Same as Cursor. Codex runs project hooks only once trusted; `init` writes that trust to `~/.codex/config.toml`. Verified live. |
182
238
 
183
- Turn it off per machine with `WAYFORM_GUARD=off` in `.memorylayer-hook.env`.
239
+ Onboarding notes:
240
+
241
+ - **Codex:** run `codex mcp login wayform` in a terminal in the repo (the in-session reconnect can't start the browser flow), then start a **new** Codex session; a session started before login skips the wayform server.
242
+ - **Codex:** if a "Wayform" app is connected to your ChatGPT account, disconnect it (or run Codex with `-c features.apps=false`); it shadows the project's wayform server with stale tools and a sign-in loop.
243
+ - **Cursor:** `agent mcp login wayform` (or approve in the IDE). Cursor's guard blocks with a ticket, and `guard_allow` lifts it after you confirm.
244
+
245
+ A `guard_allow` ticket lets actions that contradict that one decision proceed,
246
+ for you only, for 10 minutes; a different conflict asks again. Reads are never
247
+ guarded, so only mutating tools pay any latency, capped at 6 seconds before the
248
+ check gives up and allows; any failure allows.
249
+
250
+ Turn it off per machine by setting `WAYFORM_GUARD=off` in the shell
251
+ environment the agent runs in.
184
252
 
185
253
  How often it fires:
186
254
 
@@ -192,19 +260,19 @@ curl -H "$WAYFORM_AUTH" \
192
260
 
193
261
  ---
194
262
 
195
- ## The two tools
263
+ ## Plan mirror
196
264
 
197
- Everything reads and writes through one MCP contract (identical in local stdio
198
- and hosted HTTP modes):
265
+ A space admin can mirror a project's in-flight plans (draft, active, building)
266
+ into every teammate's code repo as readable markdown:
199
267
 
200
- | Tool | What it does |
201
- |---|---|
202
- | `read_context(project, budget_tokens?)` | Pull latest and return the projected context — every recorded decision, in write order, packed to a token budget (default 4000) so reads never flood a session as the store grows. |
203
- | `write_context(project, type, payload)` | Append one decision (`type: "decision"`) or durable background (`type: "context"`) as its own file, commit, push. The commit is the event; the author is the attribution. |
268
+ > "turn on the plan mirror for project MemoryLayer" → `set_plan_mirror(project, enabled: true)`
204
269
 
205
- Each write is its own file under `context/<project>/<author>/`, so concurrent
206
- writers never touch the same file and never merge-conflict. Many working repos
207
- may share one memory repo (kept separate inside it by `context/<project>/`).
270
+ At each session start the hook writes `.wayform/plans/<N>-<title>.md` and
271
+ removes plans that shipped or were superseded. The folder git-ignores itself
272
+ (`.wayform/.gitignore` is `*`), so it never shows up in commits, diffs, or
273
+ `git status`. Plans only, never memories. The files are a read-only view: change
274
+ a plan with `edit_plan`. Turning the mirror off removes the folder at the next
275
+ session start.
208
276
 
209
277
  ## The loop — how reads and writes actually happen
210
278
 
@@ -217,7 +285,8 @@ sessions, never in unrelated chats.
217
285
  **Writes have three paths, softest first:**
218
286
 
219
287
  1. **Say it** (any client, incl. Claude Desktop): *"record this decision: X
220
- because Y."* A direct command the model complies with near-reliably.
288
+ because Y"* or *"plan out X"*. A direct command the model complies with
289
+ near-reliably.
221
290
  2. **`/remember`** (Claude Code / Cursor): one-word gesture; ships in
222
291
  `.claude/commands/remember.md`. `/remember we decided X because Y`, or bare
223
292
  `/remember` to record the last settled decision.
@@ -233,29 +302,25 @@ coding session. (The flip side: failures are quiet — that's what `doctor` is
233
302
  for.)
234
303
 
235
304
  **Claude Desktop** has no hook system, so it's MCP-pull-only: register
236
- `wayform` as a stdio server (or point Desktop at the hosted gateway URL and
237
- Connect) and it reads when the model chooses to — path 1 is your write path
238
- there.
239
-
240
- ## Configuration (`.memorylayer-hook.env`)
241
-
242
- Written by `init`, per-user, gitignored, self-loaded from the project root at
243
- runtime. Keys are an **allowlist** — a crafted file cannot inject other env
244
- into hook subprocesses:
245
-
246
- | Var | Required | Meaning |
247
- |-----|----------|---------|
248
- | `CONTEXT_REPO_URL` | local mode | Shared context repo URL (may embed a git token). |
249
- | `MEMORYLAYER_GATEWAY_URL` | hosted mode | Gateway base URL. Presence selects hosted (no clone). |
250
- | `MEMORYLAYER_AUTHOR` | local mode | Your name — local commit author / attribution. Hosted attribution comes from GitHub OAuth. |
251
- | `MEMORYLAYER_AUTHOR_EMAIL` | no | Local commit email. Defaults from author name. |
252
- | `MEMORYLAYER_PROJECT` | no | Project/space name. Default: repo directory name. |
253
- | `CONTEXT_REPO_PATH` | no | Local clone path. Default: keyed per repo URL under `$XDG_DATA_HOME/memorylayer/clones/<repo-slug>-<hash>` (falls back to `~/.local/share/...`), so two spaces can never share a clone. |
254
- | `MEMORYLAYER_READ_BUDGET_TOKENS` | no | Read token budget. Default 4000; `<=0` = unlimited. |
255
- | `MEMORYLAYER_AUTO_PUSH` | no | `false` to skip pushing (local smoke tests). |
256
-
257
- Hosted hook env contains only project settings and the gateway URL. The OAuth
258
- session is held by the native OS credential store after `wayform login`.
305
+ `wayform` as a remote MCP server and it reads when the model chooses to — path
306
+ 1 is your write path there.
307
+
308
+ ## Configuration (`.wayform-hook.env`)
309
+
310
+ Written by `wayform init --remote`, project-scoped, **credential-free** (URL +
311
+ project name only — safe to commit; `wayform init` removes it from
312
+ `.gitignore` for this reason). The legacy filename `.memorylayer-hook.env` and
313
+ the `MEMORYLAYER_` variable prefix are still read indefinitely, so old configs
314
+ keep working.
315
+
316
+ | Var | Meaning |
317
+ |-----|---------|
318
+ | `WAYFORM_GATEWAY_URL` | Gateway base URL. Presence selects hosted mode. |
319
+ | `WAYFORM_PROJECT` | Project/space name. Default: repo directory name. |
320
+ | `WAYFORM_READ_BUDGET_TOKENS` | Read token budget. Default 4000; `<=0` = unlimited. |
321
+
322
+ `WAYFORM_GUARD=off` (in the shell environment, not this file) disables the
323
+ guard hook per machine.
259
324
 
260
325
  ## Diagnostics
261
326
 
@@ -263,27 +328,23 @@ session is held by the native OS credential store after `wayform login`.
263
328
  wayform doctor
264
329
  ```
265
330
 
266
- Read-only. Checks the env file, resolved config, clone health and origin,
267
- remote connectivity/auth, unpushed commits, and the default project name.
268
- Tokens embedded in URLs are redacted before printing. Run it whenever a read or
269
- write "silently" does nothing — fail-open means problems hide here first.
331
+ Read-only. Checks the resolved config, hosted login/session state, gateway
332
+ reachability, and the default project name. Run it whenever a read, write, or
333
+ plan call "silently" does nothing — fail-open means problems hide here first.
270
334
 
271
335
  ## Security & data ownership
272
336
 
273
- - **Local mode:** your data never transits anything but git between your
274
- machine and your own private repo. The env allowlist blocks env injection;
275
- project/author names are slugged so a hostile name can't path-traverse out of
276
- `context/`; error output redacts embedded tokens.
277
- - **Hosted mode:** the gateway is a stateless proxy — the source of truth stays
278
- a private GitHub repo in *your* account. The App holds Contents-only
279
- permission on exactly one repo per space; members are keyed by GitHub user
280
- id after OAuth. The Worker holds operator secrets in Cloudflare's secret
281
- store, never in code or git. Members never see a Wayform API key. For now,
282
- one GitHub user can belong to one Wayform space; multi-space membership is a
283
- deferred product decision.
284
- - **Trust boundary to know about:** everything a space member writes is
285
- injected into every member's sessions. You trust the people in your space —
286
- that's the model, stated plainly.
337
+ - **The gateway is a stateless proxy.** The source of truth is a private
338
+ GitHub repo in *your* account — plans and decisions alike are commits there.
339
+ The App holds Contents-only permission on exactly one repo per space;
340
+ members are keyed by GitHub user id after OAuth. The Worker holds operator
341
+ secrets in Cloudflare's secret store, never in code or git. Members never
342
+ see a Wayform API key.
343
+ - **One GitHub user belongs to one Wayform space** for now; multi-space
344
+ membership is a deferred product decision.
345
+ - **Trust boundary to know about:** everything a space member writes — plans
346
+ included — is injected into every member's sessions. You trust the people in
347
+ your space; that's the model, stated plainly.
287
348
  - **Rate limits — wired but NOT currently enforcing.** Verified live
288
349
  2026-08-30: the binding is bound and called on every request, but returned
289
350
  success for 100+ requests in seconds against a limit of 20/60s. Treat these
@@ -299,8 +360,8 @@ write "silently" does nothing — fail-open means problems hide here first.
299
360
 
300
361
  ### Managing your own sessions
301
362
 
302
- Every editor you connect is a separate OAuth grant. You can review and
303
- disconnect them yourself, from any agent — no operator involved:
363
+ Every editor you connect is a separate OAuth grant. Review and disconnect them
364
+ yourself, from any agent — no operator involved:
304
365
 
305
366
  > "list my wayform sessions"
306
367
  > "revoke wayform session <id>"
@@ -308,39 +369,50 @@ disconnect them yourself, from any agent — no operator involved:
308
369
  `list_sessions` shows each connected client, when it was connected, and marks
309
370
  the one you are currently using. `revoke_session` disconnects one and takes
310
371
  effect immediately; that client must sign in again. Both act only on **your**
311
- account — removing a *teammate* from the space is `revoke_member`, and is
312
- admin-only. A revoke that cannot be confirmed reports an error rather than
313
- claiming success, so "revoked" always means revoked.
372
+ account — removing a *teammate* from the space is `revoke_member`, admin-only.
373
+ A revoke that cannot be confirmed reports an error rather than claiming
374
+ success, so "revoked" always means revoked.
314
375
 
315
376
  ## Troubleshooting
316
377
 
317
378
  | Symptom | Cause & fix |
318
379
  |---|---|
319
- | `wayform: command not found` right after `npm install -g github:...` | npm 10 git-global-install bug: the global bin points at an ephemeral cache clone with no files. Fix: the clone-then-install path from the Quickstart, or `npm pack` + `npm install -g ./wayform-*.tgz`. |
320
- | `ENOTDIR` reinstalling over a previous failed install | Same bug, stale symlink. Remove the target dir shown in the error, then clone-then-install. |
321
- | Reads/writes silently do nothing | `wayform doctor`. Hosted: usually `wayform login`. Local: missing `.memorylayer-hook.env`, no repo access, or unpushed local commits (self-heals on next read). |
322
- | Teammates still see old behavior after an upgrade | The fix lives in the **global binary** — each teammate must reinstall it (committed project configs aren't enough), and a running MCP server needs a restart to pick it up. |
380
+ | Reads/writes/plan calls silently do nothing | `wayform doctor`. Usually `wayform login`, or the space isn't allowlisted yet. |
381
+ | Teammates still see old behavior after an upgrade | The fix lives in the **global binary** — each teammate must reinstall it (`npm i -g wayform`) and restart any running MCP server to pick it up. |
323
382
  | macOS `curl` fails TLS against the hosted gateway (`workers.dev`) | LibreSSL negotiation quirk — add `--tlsv1.2`. Client-side only; SDK-based MCP clients are unaffected. |
383
+ | `.memorylayer-hook.env` from an old install | Still read automatically; `wayform init --remote` migrates it to `.wayform-hook.env` (and rewrites it credential-free) the next time it runs. |
324
384
 
325
385
  ## Project status
326
386
 
327
- Working and in daily two-person dogfood on GitHub OAuth (no member API keys).
328
- Hosted onboarding is Connect + GitHub App install on your private memory repo.
387
+ Plans #1–#16 have shipped the plan object, plan generation, and the pre-UI
388
+ hardening pass (guard, recall, HTTP API, multi-team, this doc) on the hosted
389
+ gateway — GitHub OAuth, no member API keys. The desktop app (Phase 3, plan #5)
390
+ has not been built yet; today the plan is authored and read through whatever
391
+ MCP client the agent runs in.
329
392
 
330
- **Deliberately not built yet:** Stripe/paid plans, per-space extract caps,
331
- dashboard UI, custom merge engine (git *is* the merge engine).
393
+ **Deliberately not built yet** (see plan #2's cut lines): an orchestrator, a
394
+ repo-map product, hosted execution of dispatched agents, a live session
395
+ viewer, an accounts system beyond OAuth + the GitHub App, and a CRDT sync
396
+ engine — optimistic writes plus last-write-wins on a versioned plan body is
397
+ enough until two people demonstrably edit one plan at once.
332
398
 
333
399
  ## Repo layout
334
400
 
335
401
  ```
336
- src/ local CLI + stdio MCP server (init, hooks, store, doctor)
337
- gateway/ hosted gateway — Cloudflare Worker (own README + runbook)
402
+ src/ local CLI + legacy stdio MCP server (init, hooks, store, doctor)
403
+ gateway/ hosted gateway — Cloudflare Worker, the product plane (own README + runbook)
338
404
  dist/ pre-built JS, committed (installs need no toolchain)
339
- docs/plans/ implementation plans docs/specs/ design specs
340
- docs/roadmap/ production + graph-store roadmaps
341
405
  test/ node:test suites (gateway has its own under gateway/test/)
342
406
  ```
343
407
 
408
+ Plans and specs are no longer kept as local `docs/` files — they live in the
409
+ Wayform space itself (`create_plan`, `read_plan`) and are visible in-repo,
410
+ read-only, via the plan mirror.
411
+
412
+ ## Desktop app
413
+
414
+ A macOS app for reading and editing plans lives in [`app/`](app/README.md).
415
+
344
416
  ## Development
345
417
 
346
418
  ```bash
@@ -352,3 +424,50 @@ wayform --help # subcommands: init, login, hook, doctor, space
352
424
  Both planes share the entry format modules (`src/frontmatter.ts`,
353
425
  `src/slug.ts`, `src/token-budget.ts`) — change the format in one place or not
354
426
  at all.
427
+
428
+ ---
429
+
430
+ ## Legacy: local mode
431
+
432
+ Before the hosted gateway, each member cloned a shared git repo directly and
433
+ ran a local CLI + stdio MCP server. That code still lives in `src/` and still
434
+ works, but it is **not the product plane** — no plan tools, no guard, no plan
435
+ mirror, no session-start briefing beyond a raw recency dump. New setups should
436
+ use the [hosted quickstart](#hosted-quickstart) above.
437
+
438
+ ```bash
439
+ git clone https://github.com/skandaramanan/Wayform /tmp/wayform \
440
+ && npm install -g /tmp/wayform
441
+ ```
442
+
443
+ > **Why not `npm install -g github:...`?** npm 10 has a git-global-install bug
444
+ > (the package is symlinked to an ephemeral cache dir that never gets checked
445
+ > out) that makes the one-liner fail with `command not found` or `ENOTDIR`.
446
+ > The clone-then-install path above uses npm's copy path and works everywhere.
447
+
448
+ One person creates a **private** git repo (e.g. `yourteam-memory`) and grants
449
+ each collaborator push access — this is the shared "key," just git access to
450
+ that repo. From your project repo:
451
+
452
+ ```bash
453
+ wayform init
454
+ ```
455
+
456
+ This writes session-start read hooks + local MCP registration for Claude
457
+ Code, Cursor, and Codex, an end-of-turn write-review Stop hook, and a
458
+ per-user, gitignored `.wayform-hook.env` (identity + repo URL — secrets never
459
+ enter git). One person commits the project configs; each teammate runs
460
+ `wayform init` once to set their own identity.
461
+
462
+ Local mode speaks only `read_context` / `write_context` / `search_memory` —
463
+ no plans. Configuration keys (local mode only):
464
+
465
+ | Var | Meaning |
466
+ |-----|---------|
467
+ | `CONTEXT_REPO_URL` | Shared context repo URL (may embed a git token). |
468
+ | `WAYFORM_AUTHOR` / `WAYFORM_AUTHOR_EMAIL` | Local commit author / attribution. |
469
+ | `CONTEXT_REPO_PATH` | Local clone path. Default: keyed per repo URL under `$XDG_DATA_HOME/memorylayer/clones/<repo-slug>-<hash>`. |
470
+ | `WAYFORM_AUTO_PUSH` | `false` to skip pushing (local smoke tests). |
471
+
472
+ `wayform doctor` also diagnoses local mode: env file, clone health and origin,
473
+ remote connectivity/auth, and unpushed commits.