@lawaty/lacode 0.5.0 → 0.7.0

package/docs/CONTEXT.md

@@ -45,9 +45,9 @@ independently measured.** A number derived from somebody else's repository and
 token mix is not a claim about yours; see [BENCHMARKS.md](BENCHMARKS.md) for the
 harness that produces a number for your own workload.
 
-## The five files
+## The files in the map
 
-`.opencode/context/` holds exactly these, and nothing else:
+`.opencode/context/` holds the five generated files below:
 
 | File | What belongs in it |
 | --- | --- |
@@ -57,6 +57,12 @@ harness that produces a number for your own workload.
 | `workflows.md` | The few runtime flows worth tracing end to end — how a request becomes a mutation, how a plugin hook reaches the thing it hooks. Read this when you need to know what actually happens at runtime. |
 | `decisions.md` | Architectural decisions that the repository's own decision log does not already record. Concise, variable length. |
 
+The project's root `AGENTS.md` is the standing-instructions home: the client's
+own statement of intent, what they want worked on and how they want it
+approached. It sits outside the map, is per-clone and not committed, and has
+no prescribed structure. It has exactly one writer — the hidden `instructions`
+agent, reachable only from the `/agent-instructions` command.
+
 Files the user or the plan explicitly names always win over the map. The map is
 a shortcut to the right starting point, not an authority: when it disagrees with
 the source, the source is right and the map is wrong.
@@ -98,12 +104,20 @@ formatting, local renames, added tests and dependency bumps rarely alter what
 the map should say. The cartographer is told to edit only when the work
 introduced or revealed something that will help a future agent — a new boundary,
 a new or moved entry point, a changed workflow, a new convention, an
-architectural decision, a previously undocumented invariant — and to report
+architectural decision, an undocumented invariant — and to report
 "no update needed" otherwise.
 
-If the map is missing entirely, nothing breaks: agents check, find nothing, and
-explore as they always did. The standing rule that tells them to check is
-injected into your config only when you have no `instructions` array of your own.
+If the map is missing entirely, nothing breaks: agents run the check, find no
+`.opencode/context/`, and explore from scratch. What tells them to run the check
+is an entry appended to your config's `instructions` array: your own entries are
+kept as they are, and a marked entry goes after them unless one of your entries
+already carries its marker or its opt-out. LaCode appends two such entries, each
+governed by its own pair — the context-map rule
+(`<!-- lacode:context-map-instruction:v1 -->`, opt out with
+`<!-- lacode:context-map-instruction:off -->`) and the rule that documentation
+states the current state (`<!-- lacode:current-state-rule:v1 -->`, opt out with
+`<!-- lacode:current-state-rule:off -->`). One opt-out suppresses only the rule
+it names.
 
 ### On demand
 
@@ -132,10 +146,10 @@ outside the map — not by convention, but by an `edit` rule that allows
 The rule runs in both directions. The agents that *could* write anywhere else in
 the repository — the root `build` agent and both implement tiers — carry the
 mirror image of the cartographer's grant: `"*": "allow"` followed by a `deny` on
-`.opencode/context/**`, so they edit everything except the map. The instruction
-telling them not to touch it is still there, and still matters — a permission
-denial tells an agent nothing about what it should have done instead — but it is
-no longer the only thing standing between them and the map.
+`.opencode/context/**`, so they edit everything except the map. Enforcement is
+two mechanisms at once, and both are load-bearing: the injected instruction
+naming the one writer, and the permission rule — a permission denial tells an
+agent nothing about what it should have done instead.
 
 This exists because two writers produce a map that is neither current nor
 trustworthy. Concurrent sessions rewriting the same five files produce
@@ -150,14 +164,14 @@ writes every narrow rule last, in both files (`src/agents.ts` and your own
 grepping for the word `allow` — which is what stops a correctly-placed deny from
 being reported as a hole.
 
-The rule has a sharp edge worth knowing about, because it has already bitten
-this project: **opencode evaluates a file permission against the path relative
-to the project root, not the absolute path the tool was given.** A rule written
-as `*/.opencode/context/**` matches an absolute path and therefore matches
-nothing at all. Both spellings are therefore required — `.opencode/context/**`
-for a normally-rooted project and `*/.opencode/context/**` for one rooted at
-`/` — and LaCode ships both. At startup the plugin checks your config for that,
-and logs an error naming the rules it saw if neither form would ever fire.
+The rule has a sharp edge worth knowing about: **opencode evaluates a file
+permission against the path relative to the project root, not the absolute path
+the tool was given.** A rule written as `*/.opencode/context/**` matches an
+absolute path and therefore matches nothing at all. Both spellings are therefore
+required — `.opencode/context/**` for a normally-rooted project and
+`*/.opencode/context/**` for one rooted at `/` — and LaCode ships both. At
+startup the plugin checks your config for that, and logs an error naming the
+rules it saw if neither form would ever fire.
 
 ### The residual risk: a subdirectory worktree
 
@@ -181,14 +195,13 @@ How to detect it: open opencode from the repository root, not from a
 subdirectory of it. If `ls .opencode/context` from your shell's current
 directory does not list the five files, your shell is not at the root and
 neither is opencode's worktree. The cost of getting it wrong is not a crash —
-it is a silent return to a map maintained only by prompt, which is the exact
-state US-21 exists to eliminate.
-
-The symptom of getting this wrong is not a crash. The cartographer's writes are
-simply denied, its run still "succeeds", and the map quietly stops changing. So
-a run that changed nothing on disk is reported as a warning, not as a success:
-if you see `auto update finished without changing the map` repeatedly, the first
-thing to check is that permission rule, not the map's content.
+it is a map maintained only by prompt, with no mechanism enforcing who writes it.
+
+The symptom is silence: the cartographer's writes are denied without an error,
+its run reports success, and the map quietly stops changing. So a run that
+changed nothing on disk is reported as a warning, not as a success: if you see
+`auto update finished without changing the map` repeatedly, the first thing
+to check is that permission rule, not the map's content.
 
 ## What you will see in the log
 

package/docs/INSTALL.md

@@ -118,26 +118,25 @@ This package also publishes `main` and an `exports["./server"]` entry pointing a
 the same built file, because those are two of the shapes a plugin loader
 resolving an entry point consults. They are forward-compatibility metadata and
 they cost nothing — but they do **not** fix this on 1.18.35: adding either one to
-the *installed* cache copy was tested there and the bare specifier still loaded
-nothing. No other version has been observed where they help either. Use the
-`file://` entry.
+the *installed* cache copy leaves the bare specifier loading nothing. Whether
+they help on any other version is unknown. Use the `file://` entry.
 
 
 ## Which opencode versions this is known on
 
-Exactly one version has been measured, and the procedure above is deliberately
+Exactly one version is measured, and the procedure above is deliberately
 not built around that fact. Treat this table as the evidence it is, which is one
 row wide.
 
 | opencode version | bare spec loads? | `file://` needed? | evidence |
 | --- | --- | --- | --- |
-| 1.18.35 | No — installs the package, then silently drops it | Yes | **Verified** on 1.18.35: a populated cache directory, zero agents injected, no error and no log line; the `file://` entry loads the full agent set. |
-| Any other version | **Unknown** | **Unknown** | **Untested.** No other opencode version has been run against this package in either direction. |
+| 1.18.35 | No — installs the package, then silently drops it | Yes | Measured on 1.18.35: a populated cache directory, zero agents injected, no error and no log line; the `file://` entry loads the full agent set. |
+| Any other version | **Unknown** | **Unknown** | No other opencode version is covered by this table, in either direction. |
 
-Every command quoted on this page was run against 1.18.35. **If your version is
-not the one measured here, follow the procedure above rather than reading this
-table as coverage of your build**: each step stands on its own, and step 2 tells
-you which situation you are in before any version-specific advice is relevant.
+**If your version is not the one measured here, follow the procedure above
+rather than reading this table as coverage of your build**: each step stands on
+its own, and step 2 tells you which situation you are in before any
+version-specific advice is relevant.
 
 
 ## macOS
@@ -168,8 +167,8 @@ Three things differ, and all three are worth reading rather than assuming:
   notification hop is a direct ssh (`ControlMaster` + `ControlPersist`) set up
   once with `lacode tunnel setup` — no reverse forward, no listening port, no
   systemd unit. See [Remote hosts](../README.md#remote-hosts) and docs/TUNNEL.md.
-- The repo still carries the author's personal, Linux-only tooling from the older
-  reverse-forward setup (`bin/oc`, `bin/oc-notify`, `bin/oc-notify-receiver`,
+- The repo carries the author's personal, Linux-only reverse-forward tooling
+  (`bin/oc`, `bin/oc-notify`, `bin/oc-notify-receiver`,
   `bin/oc-sync`). None of it is in the published package, and none of it is needed
   for the npm-client path above.
 
@@ -182,7 +181,8 @@ or no GNU `timeout` — rather than passing silently or failing confusingly.
 
 ## The `lacode` CLI
 
-The package also ships the `lacode` CLI (`notify`, `forward`, `doctor`, `receive`, `tunnel setup`) — see
+The package also ships the `lacode` CLI (`notify`, `forward`, `doctor`, `version`,
+`update`, `receive`, `tunnel setup`) — see
 [Remote hosts](../README.md#remote-hosts). The plugin install does **not** put it on your
 `PATH`; run it from the package's `node_modules/.bin`, or install just the CLI
 globally with `npm i -g @lawaty/lacode` if you want the bare command. (That
@@ -204,6 +204,6 @@ Two things are worth knowing about what npm actually hands you:
   `dist/`, built from `src/` at pack time (`prepack` runs the build, so a stale
   `dist/` cannot be published). This is not a preference: node strips types
   natively from 22.18 but **refuses to for files under `node_modules`**, so a
-  package that shipped `.ts` worked fine in a checkout and failed on install —
-  `lacode --help` died with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. A
-  published package cannot depend on its consumer's loader being lenient.
+  package that ships `.ts` fails on install — `lacode --help` exits with
+  `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. A published package cannot
+  depend on its consumer's loader being lenient.

package/docs/OMNIROUTE.md

@@ -1,6 +1,6 @@
 # OmniRoute gateway integration
 
-[OmniRoute](https://github.com/diegosouzapw/OmniRoute) is a local OpenAI-compatible gateway that routes a request across many providers with fallback and "combos". LaCode can register it as an opencode provider. It is **off by default**. The summary is in the [README](../README.md#configure); this page is the full reference, including a latency-measured combo that is worth applying on a new client.
+[OmniRoute](https://github.com/diegosouzapw/OmniRoute) is a local OpenAI-compatible gateway that routes a request across many providers with fallback and "combos". LaCode can register it as an opencode provider. It is **off by default**. The summary is in the [README](../README.md#configure); this page is the full reference, including a combo ordered for latency that is worth applying on a new client.
 
 ## Configuring OmniRoute
 
@@ -119,11 +119,10 @@ fails; every other slot keeps working. See
 
 `combo: "auto"` is the zero-configuration default, but `auto` inherits whatever
 the gateway chooses, and on a busy free tier that is frequently the slowest
-chain available. The combo below was **measured** against a live free-tier
-gateway and is ordered for latency rather than for breadth. Apply it during the
-"Setting it up on a client machine" steps above and pooled work is usable
-straight away, instead of starting from a gateway that queues for half a minute
-per call.
+chain available. The combo below is ordered for latency rather than for
+breadth. Apply it during the "Setting it up on a client machine" steps above
+and pooled work is usable straight away, instead of starting from a gateway that
+queues for half a minute per call.
 
 ```jsonc
 {
@@ -146,33 +145,21 @@ per call.
 }
 ```
 
-Why this order, from 859 calls over a single day against that gateway:
+Why this order — it is the two free-tier failure modes, a hard reject and a
+slow queue-budget timeout:
 
-| Model | Observed behaviour | Position |
+| Model | Behaviour on a busy free tier | Position |
 | --- | --- | --- |
-| `gemini/gemini-3.1-flash-lite` | **165/172 succeeded (96%)**, ~4.5s median | **first** |
-| `gemini-3.8-flash` / `3.7-flash` / `3-flash-preview` | succeed intermittently, but **burn exactly 30.0s** on a `503` queue-budget timeout when they do not | next |
-| `openrouter/*:free` | **~90% `429`**, but fails *fast* (~1.8s) and occasionally succeeds | last, as a cheap final fallback |
+| `gemini/gemini-3.1-flash-lite` | succeeds on the large majority of calls, ~4.5s median | **first** |
+| `gemini-3.8-flash` / `3.7-flash` / `3-flash-preview` | succeed intermittently, but **stall ~30s** on a `503` queue-budget timeout when they do not | next |
+| `openrouter/*:free` | **mostly `429`**, but fail *fast* (~1.8s) and occasionally succeed | last, as a cheap final fallback |
 | `gemini-2.5-flash`, `gemini-2.5-flash-lite` | **`404` on every attempt** — dead ids | **omitted entirely** |
 
 The ordering matters because a combo pays for *every* step it walks past. Put the
-96%-success model first and the common case is a single hop; the 30s models sit
+reliable model first and the common case is a single hop; the 30s models sit
 behind it where they cost nothing, and the 429s sit last where they give up in
 under two seconds.
 
-Measured on the same gateway, same day, `max_tokens: 10`:
-
-| | Before | After |
-| --- | --- | --- |
-| `free-mix` response | 42.7s / 41.8s / 34.7s | 4.1s / 3.1s / 3.2s / 4.0s / 3.2s |
-| Median | **~41.8s** | **~3.2s** |
-| Provider time burned on calls >25s | **56.9 of 102.4 min (56%)** | — |
-
-Before the change, the real call sequence was a `429` after 2.7s, then a `503`
-after 30.0s, then the actual work in 5.7s — roughly **33 seconds of dead time in
-front of every successful request**, and a p90 of 100s when three 30s steps
-chained.
-
 These free-tier endpoints change availability constantly, so treat the ordering
 as a **starting point to re-measure, not a permanent truth**. Re-check it with
 OmniRoute's own call logs before assuming it still holds:

package/docs/TUNNEL.md

@@ -38,10 +38,10 @@ as one newline-delimited argument:
 title\nmessage\nurgency\nicon\nsound
 ```
 
-Five fields, and only the last one is new: `sound` is `none`, `done`,
-`question`, `permission` or `error`. A sender that stops at `icon` simply
-leaves it empty, and an empty or unrecognised name is `none`, so a four-field
-payload is still a valid one.
+Five fields — `title`, `message`, `urgency`, `icon`, `sound`. `sound` is `none`,
+`done`, `question`, `permission` or `error`. A sender that stops at `icon`
+simply leaves it empty, and an empty or unrecognised name is `none`, so a
+four-field payload is a valid one.
 
 Newline is safe as the delimiter because both ends strip control characters from
 the free-text fields before assembling or reading it, and `urgency`, `icon` and
@@ -93,7 +93,7 @@ lacode doctor
 
 SOUND is optional and last: `none`, `done`, `question`, `permission` or `error`,
 one bundled tone per outcome. Leave it off and nothing plays; the line above
-without a fifth word is still correct.
+without a fifth word is correct.
 
 `notify` is fire-and-forget by design. An unreachable desktop, a missing key, no
 notifier installed at all — all of them print a warning on stderr and exit 0. A
@@ -124,7 +124,8 @@ runs the session and has no speakers. The name is validated against the sound
 whitelist at the same trust boundary as `urgency` and `icon`, and the receiver
 looks the file up in the package's own `sounds/` directory — the sender's word
 never becomes a path. `afplay` plays it on macOS, `paplay`, `aplay` or
-`pw-play` on Linux, and a machine with none of them still gets the notification.
+`pw-play` on Linux, and a machine with none of them gets the notification
+regardless.
 
 ## Configuration
 
@@ -135,7 +136,7 @@ never becomes a path. `afplay` plays it on macOS, `paplay`, `aplay` or
 | `OC_NOTIFY_KEY` | `~/.ssh/lacode_notify` | The dedicated key. Never a personal key. |
 | `OC_CONNECT_TIMEOUT_MS` | `5000` | Ceiling on the hop. |
 | `OC_SSH_TIMEOUT_MS` | `30000` | Ceiling on `forward`. |
-| `OC_TUNNEL_PORT` | `10022` | **Legacy** reverse-forward listener port. Used only when `OC_LOCAL_HOST` is unset. |
+| `OC_TUNNEL_PORT` | `10022` | Reverse-forward listener port. Used when `OC_LOCAL_HOST` is unset. |
 
 `OC_LOCAL_USER` is read rather than probed on purpose. `id -un` on a remote
 account frequently returns `root`, and a dbus path built from that reaches
@@ -151,11 +152,12 @@ documented with the other plugin options in the README. Set it to `0`, `false`,
 `off` or `no` to silence notifications; anything else — a typo included — leaves
 sound on, because a misspelt variable must not be how you turn a feature off.
 
-## Legacy: the reverse forward
+## The reverse forward
 
-The original design opened a reverse forward (`ssh -R`) held by a `systemd --user`
-unit on the desktop, and delivered to a `notify-send`-only bash receiver
-(`bin/oc-notify-receiver`). It is kept only for hosts that still set
-`OC_TUNNEL_PORT` and leave `OC_LOCAL_HOST` unset: `sendRemote` falls back to an
-ssh call to `localhost:<port>`. New setups should use the direct ssh above. See
-the git history for the old systemd unit shape.
+A host that sets `OC_TUNNEL_PORT` and leaves `OC_LOCAL_HOST` unset reaches the
+desktop through a reverse forward: `sendRemote` falls back to an ssh call to
+`localhost:<port>`, where a `systemd --user` unit on the desktop holds an
+`ssh -R` forward open and delivers to a `notify-send`-only bash receiver
+(`bin/oc-notify-receiver`). That receiver is the Linux end of the hop: it
+delivers through `notify-send`, and libnotify is a Linux thing, so a Mac cannot
+be this end of the tunnel.

package/docs/USER-STORIES.md

@@ -4,8 +4,8 @@
 
 Every story below is a behavioural contract, not a feature wish. Each one is
 traceable to a pain point the author actually hit, and each carries acceptance
-criteria written so that a test can assert them mechanically. Phase 3 fills in
-the test file for each row of the Coverage table.
+criteria written so that a test can assert them mechanically. Every row of the
+Coverage table has a test file.
 
 **Reading the criteria.** Every criterion is written as *Given … When … Then …
 * so that it maps to one test case. "Given" is a state or fixture, "When" is a
@@ -27,13 +27,13 @@ spawn recorded in `claims.<pid>.json`. A *context map* is the five-file
 
 | Epic | Pain point it solves |
 | --- | --- |
-| **A — Cost control** | Quota exhaustion. Routine work (grep, reading, cartography) was consuming the same expensive budget as design work, and the main model was being spent on file listing. |
-| **B — Provider resilience** | Provider limits. Free-tier quotas are per-provider and per-minute, so a long session would hard-fail the moment one provider's window closed, even while three other providers sat idle. |
-| **C — Hang recovery** | Hangs. A wedged or silently-stalled subagent held its slot forever; one bad task stalled the session with no error and no timeout. |
-| **D — Notifications** | Parallel sessions. With several sessions open, work finishing — or a question blocking — was invisible unless you happened to be looking at that terminal. |
-| **E — Remote hosts** | Remote SSH notification. Work ran on remote hosts, so notifications raised there died on that host's nonexistent desktop instead of reaching the local one. |
+| **A — Cost control** | Quota exhaustion. Routine work (grep, reading, cartography) consumes the same expensive budget as design work, and the main model is spent on file listing. |
+| **B — Provider resilience** | Provider limits. Free-tier quotas are per-provider and per-minute, so a long session hard-fails the moment one provider's window closes, even while three other providers sit idle. |
+| **C — Hang recovery** | Hangs. A wedged or silently-stalled subagent holds its slot forever; one bad task stalls the session with no error and no timeout. |
+| **D — Notifications** | Parallel sessions. With several sessions open, work finishing — or a question blocking — is invisible unless you happen to be looking at that terminal. |
+| **E — Remote hosts** | Remote SSH notification. Work runs on remote hosts, so notifications raised there die on that host's nonexistent desktop instead of reaching the local one. |
 | **F — Adoption and safety** | Installability. A personal config cannot be adopted safely: it either clobbers what you already have, or needs manual surgery before it runs. |
-| **G — Context and cost** | Cold exploration. Every task started by re-discovering the structure of the codebase from scratch, so the same layout was re-read — and re-paid for — on every single run. |
+| **G — Context and cost** | Cold exploration. Every task starts by re-discovering the structure of the codebase from scratch, so the same layout is re-read — and re-paid for — on every single run. |
 
 ---
 
@@ -275,16 +275,16 @@ does not.
 
 **Story ID(s) for tests:** US-26
 **Acceptance criteria:**
-- [ ] Given the notification is raised on macOS, When it is delivered locally, Then it goes to `osascript` — or to `terminal-notifier` if `osascript` is not installed — and not to `notify-send`, which does not exist there. Before this, the send exited 0, printed nothing, and popped up nothing.
+- [ ] Given the notification is raised on macOS, When it is delivered locally, Then it goes to `osascript` — or to `terminal-notifier` if `osascript` is not installed — and not to `notify-send`, which does not exist there.
 - [ ] Given the channel is chosen, When it is picked, Then it is decided by `process.platform` and by which binary is actually installed, never by guessing, and every platform other than macOS keeps the `notify-send` call it has always made.
 - [ ] Given the title and the body reach `osascript`, When the script runs, Then they are passed as arguments to an `on run argv` handler and never concatenated into the script source, because both fields are attacker-influenced text — a session title, a file path, a command.
 - [ ] Given a body containing `"`, `'`, `;`, `$(…)` or backticks, When the macOS send runs, Then it reaches `display notification` byte-for-byte as data and nothing is executed.
 - [ ] Given a machine has no notifier for its platform, When a notification is sent, Then the result is a failed delivery with a reason and no exception, and `lacode doctor` names the channel that would run — or reports that there is none — instead of reporting a binary that is not used there.
 - [ ] Given the CLI runs on macOS, When the send does not complete, Then it is still bounded by a timeout, exactly as on Linux.
-- [ ] Given the notification hop, When it is documented, Then the doc leads with the shipped path — the npm-installed plugin, a direct ssh hop (`ControlMaster`) set up by `lacode tunnel setup`, and the portable `lacode receive` forced command that delivers through the platform channel (`notify-send` or `osascript`) — and marks the older reverse-forward scripts (`bin/oc`, `bin/oc-notify`, `bin/oc-notify-receiver`, `bin/oc-sync`) as the author's legacy tooling, so a Mac user is not sent to debug a script that was never meant to run on their machine.
-- [ ] Given a machine without GNU `timeout` or with bash older than 4.0, When `bin/oc-sync` runs, Then it refuses **before** touching anything, names each missing prerequisite, and names the `lacode` subcommand to use instead. It must never report a misleading cause: the host list is read with `mapfile`, so without it the run used to die at "no hosts configured" — a confident wrong answer that sends the reader to edit `.env`.
+- [ ] Given the notification hop, When it is documented, Then the doc leads with the shipped path — the npm-installed plugin, a direct ssh hop (`ControlMaster`) set up by `lacode tunnel setup`, and the portable `lacode receive` forced command that delivers through the platform channel (`notify-send` or `osascript`) — and marks the reverse-forward scripts (`bin/oc`, `bin/oc-notify`, `bin/oc-notify-receiver`, `bin/oc-sync`) as the author's legacy tooling, so a Mac user is not sent to debug a script that was never meant to run on their machine.
+- [ ] Given a machine without GNU `timeout` or with bash older than 4.0, When `bin/oc-sync` runs, Then it refuses **before** touching anything, names each missing prerequisite, and names the `lacode` subcommand to use instead. It must never report a misleading cause: the host list is read with `mapfile`, so without it the run dies at "no hosts configured" — a confident wrong answer that sends the reader to edit `.env`.
 - [ ] Given `bin/oc-notify-receiver` runs where `notify-send` does not exist, When it is invoked, Then it exits non-zero and names both the missing channel and the portable path, because its stderr reaches whoever opened the ssh connection and nobody else, and a bare "command not found" reads as a desktop that quietly stopped notifying.
-- [ ] Given the payload is parsed, When the receiver splits `$SSH_ORIGINAL_COMMAND`, Then it splits on newlines only using constructs that exist in bash 3.2 as well as bash 5, and the suite **proves the split by running the receiver** rather than by finding the word `mapfile` in the file. Under bash 3.2 — the version macOS ships — a bash-4-only builtin left every field at its default, so the popup said "LaCode" with an empty body and no error anywhere: the same silent blank notification the argv bug caused once, reached again through a different door.
+- [ ] Given the payload is parsed, When the receiver splits `$SSH_ORIGINAL_COMMAND`, Then it splits on newlines only using constructs that exist in bash 3.2 as well as bash 5, and the suite **proves the split by running the receiver** rather than by finding the word `mapfile` in the file. Under bash 3.2 — the version macOS ships — a bash-4-only builtin leaves every field at its default, so the popup says "LaCode" with an empty body and no error anywhere: the same silent blank notification the argv bug causes, reached through a different door.
 - [ ] Given the whole suite, When it runs on macOS, Then it passes there too. Checks that exercise the Linux-only shell scripts **skip** on a machine that cannot run them, each naming the specific missing prerequisite (a bash version below 4.0, an absent GNU `timeout`) rather than passing silently.
 - [ ] Given the local notification channel differs by platform, When a test asserts on the notifier's argv, Then it reads **every** channel's stub rather than only `notify-send`. A Mac picks `osascript` and never invokes `notify-send` at all, so a suite that stubbed only `notify-send` would pass on Linux, read an empty log on a Mac, and in the process invoke the runner's real `osascript` against a desktop session that is not there.
 
@@ -300,7 +300,7 @@ does not.
 - [ ] Given a fresh machine with no LaCode config, When the install runs, Then one config line is sufficient and no further manual step is required.
 - [ ] Given no configuration is present at all, When LaCode boots, Then it falls back to shipped defaults and still functions.
 - [ ] Given the plugin package is installed, When its peer dependency is unmet, Then the requirement is declared rather than silently duplicated inside the package.
-- [ ] Given the published manifest, When a plugin loader looks for an entry point, Then it finds one in both shapes a resolver may consult — a top-level `main` and `exports["./server"]` — while `exports["."]` keeps pointing at the same built plugin, and the documentation states plainly that these are forward-compatibility metadata and **not** a fix for opencode 1.18.35, where adding them to the installed copy was tested and the bare specifier still loaded nothing.
+- [ ] Given the published manifest, When a plugin loader looks for an entry point, Then it finds one in both shapes a resolver may consult — a top-level `main` and `exports["./server"]` — while `exports["."]` keeps pointing at the same built plugin, and the documentation states plainly that these are forward-compatibility metadata and **not** a fix for opencode 1.18.35, where the bare specifier still loads nothing.
 - [ ] Given an opencode that does not load the bare specifier, When the reader follows the install documentation, Then the README offers a numbered procedure that holds **whichever version they run** — write the bare specifier and restart, verify with `opencode agent list`, and only if the agents are still missing while the package is installed, add a `file://` entry and restart — rather than instructions scoped to one build. Each step is justified by what the previous step showed, not by what the reader's version is known to do.
 - [ ] Given a version nobody has tested, When the reader checks the version table, Then **every** row other than the measured one is marked untested or unknown, the README claims no loading behaviour for any version it has not run, and it tells the reader to follow the procedure rather than to read the table as coverage of their build. The one row that does claim behaviour records the evidence behind it, and says that installing the package and then silently dropping it is what was measured.
 - [ ] Given any operating system, When the reader needs the package directory to build a `file://` entry, Then the path comes from `opencode debug paths` rather than a hardcoded root, and any literal path in the document is marked as an illustration of one platform's layout instead of a value to copy. Where a platform's cache root has not been established, the README says so rather than guessing it.
@@ -329,7 +329,7 @@ does not.
 ### US-24: Tool grants are documented, not injected, because a plugin cannot set them
 **As a** user who keeps a global `"tools"` block, **I want** to know that per-agent tool grants must be declared in my own config, **so that** browser automation is not silently denied on the agents that need it.
 
-The pain: LaCode once shipped a `tools: { "playwright_*": true }` grant on its four exploration and implementation tiers, with a comment claiming it rescued anyone who had globally disabled Playwright. It did not. opencode folds an agent's `tools` into its permission list **at config-load time**, inside the schema decode that runs before any plugin is called; a plugin's `config` hook mutates the already-decoded object, so the fold never re-runs and the injected value is read by nothing. The grant was dead code asserting a rescue it never performed. The fix is not to re-inject it — it is to tell the truth about it and document the one-line fix the user can apply themselves.
+A plugin cannot set per-agent tool grants. opencode folds an agent's `tools` into its permission list **at config-load time**, inside the schema decode that runs before any plugin is called; a plugin's `config` hook mutates the already-decoded object, so the fold never re-runs and any injected `tools` value is read by nothing. A `tools: { "playwright_*": true }` grant on the exploration and implementation tiers would therefore be dead code asserting a rescue it never performs. The fix is not to inject it — it is to tell the truth about it and document the one-line fix the user can apply themselves.
 
 **Story ID(s) for tests:** US-24
 **Acceptance criteria:**
@@ -343,7 +343,7 @@ The pain: LaCode once shipped a `tools: { "playwright_*": true }` grant on its f
 ### US-27: The package keeps itself current, without npm and without being asked
 **As a** user who installed LaCode once, **I want** each new release to reach my machine automatically, **so that** I never have to learn that opencode freezes the plugin version and hand-clear a cache to upgrade.
 
-The pain: opencode's plugin cache is **write-once**. It resolves `@lawaty/lacode` to an exact version once and never re-resolves — not on restart, not with `opencode plugin -g -f`, not with a range pin, not with a tagged config spec (all four verified against opencode 1.18.34). A published release therefore reaches a client only when something installs it into that cache again, and nothing in opencode ever does. The plugin has to do it itself, and it may assume only one tool: the opencode binary the code already runs inside.
+opencode's plugin cache is **write-once**. It resolves `@lawaty/lacode` to an exact version once and never re-resolves — not on restart, not with `opencode plugin -g -f`, not with a range pin, not with a tagged config spec (all four verified against opencode 1.18.34). A published release therefore reaches a client only when something installs it into that cache again, and nothing in opencode ever does. The plugin has to do it itself, and it may assume only one tool: the opencode binary the code already runs inside.
 
 **Story ID(s) for tests:** US-27
 **Acceptance criteria:**
@@ -361,11 +361,11 @@ The pain: opencode's plugin cache is **write-once**. It resolves `@lawaty/lacode
 
 ## Epic G — Context and cost (a maintained map instead of cold exploration)
 
-The pain: every task opened by exploring the repository from scratch. The same
-directory layout, the same entry points and the same layering were rediscovered
-— and re-paid for — on every run, and nothing written down survived the session
-that learned it. LaCode keeps a five-file codemap at `.opencode/context/` and
-makes agents read it before they explore, then keeps it current on its own.
+Every task opens by exploring the repository from scratch. The same directory
+layout, the same entry points and the same layering are rediscovered — and
+re-paid for — on every run, and nothing written down survives the session that
+learned it. LaCode keeps a five-file codemap at `.opencode/context/` and makes
+agents read it before they explore, then keeps it current on its own.
 
 ### US-19: Curated map replaces cold exploration
 **As a** user, **I want** agents to start from a maintained map of the codebase, **so that** each task spends fewer tokens on re-discovering structure that is already written down.
@@ -458,10 +458,9 @@ table was filled in.
 | US-21 | G | `tests/stories/g-context-management.test.mjs`, `tests/permission-test.mjs` |
 | US-22 | G | `tests/stories/g-context-management.test.mjs` |
 
-The nine suites under `tests/` are unit-style and are kept as they are; the
-`tests/stories/` suites are the behavioural layer, written one epic per file with
-every test name carrying its story id. Run everything with `npm test`.
+The nine suites under `tests/` are unit-style; the `tests/stories/` suites are
+the behavioural layer, written one epic per file with every test name carrying
+its story id. Run everything with `npm test`.
 
-**No story is uncovered.** The previously uncovered set — US-1, US-2, US-3,
-US-6, and all of epic F — now has tests, and the coverage guard fails the build
-if any of them loses one.
+**No story is uncovered.** US-1, US-2, US-3, US-6, and all of epic F have tests,
+and the coverage guard fails the build if any of them loses one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",
@@ -60,5 +60,8 @@
   },
   "peerDependencies": {
     "@opencode-ai/plugin": "1.18.34"
+  },
+  "publishConfig": {
+    "tag": "beta"
   }
 }