@zerotal/arch 1.7.5 → 1.8.0

package/CHANGELOG.md

@@ -13,6 +13,58 @@ against. `mcp-surface.md` is diffed alongside it.
 
 ## [Unreleased]
 
+## [1.8.0] — 2026-08-24
+
+### Added
+
+- **Agent skills — the depth the upfront block cannot afford.** The generated `AGENTS.md`
+  is short because every prompt it lands in pays for its whole length, so it points rather
+  than teaches. That constraint has a cost: an agent gets a map and no detail, and the
+  detail is where the expensive mistakes live. A skill is a file with a one-line
+  description that costs nothing until an agent decides it is relevant, so a procedure can
+  be written out in full. Two ship — `zerotal-schema-changes` (who owns the schema here,
+  the mixin columns nothing declares, and why an unguarded `ALTER TABLE` collides during a
+  release's `migrate`) and `zerotal-releases` (naming your own deploy steps, replacing the
+  asset directory rather than merging into it, `trustedProxies` behind a proxy, and the
+  pipe that hides a test suite's exit status). Both are shaped by the project like the
+  block is: the schema skill states this app's actual answer, and refuses to pick a side
+  when `synchronize` and migrations are both in play.
+
+  Written to `.agents/skills`, the cross-client path, plus `.claude/skills` when that agent
+  is detected. Frontmatter descriptions are JSON-quoted, because unquoted a colon makes the
+  rest a nested mapping and the file stops parsing — an inert skill looks exactly like an
+  installed one. Overriding a shipped skill is deleting its marker line: a `SKILL.md`
+  without the marker is yours and is never rewritten. Turn the whole feature off with
+  `ArchConfig({ skills: false })`.
+
+- **`doctor` reports agent instructions that no longer describe this project.** The block
+  used to describe the framework, which moved when the framework did. It now also describes
+  the project, and every fact in it moves without anyone thinking about the file — add a
+  migrations directory, turn `synchronize` off, install a package. It still reads as current
+  while describing the app you used to have, and guidance that is confidently out of date
+  gets followed. Skills rot the same way and are easier to miss, because nothing reads one
+  until an agent decides it is relevant, by which point it is being acted on. The check
+  regenerates both in memory and compares, naming `arch:update` as the fix. A warning, never
+  a failure: a misleading instruction file does not stop an application working, and this
+  check earns the right to gate a deploy by failing only for what would. The server name is
+  read back from `.mcp.json` rather than assumed, so a project that renamed its server is
+  not reported as permanently stale.
+
+### Changed
+
+- **The generated `AGENTS.md` block describes how this app is set up, not only what it
+  installed.** A package list answers "what is available here", which is not the question that
+  decides what to write: the framework's contracts are not uniform across projects, and the
+  places they differ are the places where guessing wrong compiles cleanly and fails at runtime.
+  `detectShape()` reads four facts off disk and the block states only the ones that change an
+  instruction — who owns the schema, whether route names are typed, whether
+  `exactOptionalPropertyTypes` or `noUncheckedIndexedAccess` are on, and whether there are
+  tests to run. Read from files rather than a booted app, because a project that will not boot
+  is often why the agent surface is being installed; `.env` is deliberately not among them,
+  since this output is committed and pasted into prompts. The `extends` chain is followed, so
+  an app inheriting a strict base is not read as unstrict. Additive — a caller that passes no
+  shape gets the block it got before.
+
 ## [1.7.5] — 2026-08-22
 
 ### Changed

package/api-surface.md

@@ -94,6 +94,7 @@ interface ArchConfigShape = {
   mcpConfig: boolean
   mcpConfigPath: string
   serverName: string
+  skills: boolean
 }
 
 interface Detected = {
@@ -118,6 +119,7 @@ interface DoctorReport = {
 interface GuidelineOptions = {
   packages: string[]
   serverName: string
+  shape?: ProjectShape
 }
 
 interface InstalledPackage = {

package/docs/changelog.md

@@ -27,6 +27,169 @@ the section for every version you cross and apply its migration notes, not only
 majors. [Releases and versioning](/docs/support-policy#releases-and-versioning) explains
 when that carve-out ends.
 
+## 1.8.0 — 2026-08-24
+
+The first render mode, the codemod runner 2.0 depends on, and four failures that
+each looked like something other than what they were.
+
+### Added
+
+- **`static interactive = false` — the first rung of Flow's render modes.** Every component
+  until now was maximally interactive: rendered on the server, dehydrated into a snapshot,
+  tracked by the client, reachable over a socket. Right for a counter, wasteful for a nav rail.
+  A static component is rendered in full by its parent and nothing else — no `onDehydrate`, no
+  snapshot, no `<script type="application/json">`, no entry in the client's registry, and no
+  `data-flow-root`, which would freeze it at its first render since its only route to an update
+  is the parent re-rendering it. It takes no place in `_childIds` and does not shift its
+  interactive siblings' ids, so no sibling remounts and loses its state when a static one
+  appears above it. `lazy`, `defer` and `stream` throw rather than being ignored: each waits
+  for the client to ask for the real render, and a static child never registers to do the
+  asking.
+
+  Opt-in — nothing existing changes. `this.isInteractive` reports the mode from inside the
+  component, and being a new public member it takes that name away from applications; it is on
+  the documented reserved list. See [Static children](/docs/flow/layouts#static-children).
+
+- **`zt upgrade` — the codemod runner.** The 2.0 ledger's rule is that every entry that can
+  have a codemod has one before 2.0 ships, and until now nothing had been built, which made
+  the ledger a list of changes nobody could afford to make.
+
+  **Dry by default**, which is backwards from most tools and deliberate: it rewrites source
+  across a whole project, and the first run should be something you can read and disagree with.
+  `--write` applies it. Nothing is written until the whole plan is known, so a run that fails
+  halfway leaves no half-upgraded tree, and `--dry` exercises the same code path as the real
+  thing rather than a parallel one that can drift from it. Codemods see each other's output,
+  because two of them touching one file across a version range is ordinary.
+
+  **What it could not do is the headline.** A codemod that walks past what it does not
+  understand is worse than none, since the changes it _did_ make imply the job is finished. So
+  every codemod returns two lists and the runner prints the second last and loudest, with file,
+  line and a reason. The first codemod covers the deprecated aliases — `BaseModel` → `Model`,
+  `routes:types` → `route:types`, `serve --dev` → `dev`. See [Commands](/docs/commands).
+
+- **`--clean` on `assets:build` and `inertia:build`.** Pruning is conservative by default:
+  chunk-shaped filenames, plus whatever the last build on this machine recorded in `.zerotal/`.
+  That cannot recognise output some other naming produced. `--clean` needs no record — the
+  output directory belongs to the build, and what the build did not write does not belong in
+  it. It refuses `public/` and the project root, where deleting what was not rebuilt takes the
+  app's images and favicon with it, which is the one failure here that building again cannot
+  undo. Pruning stays the default; only you can say the directory holds nothing else.
+
+- **Agent skills, from `@zerotal/arch`.** `AGENTS.md` is short because every prompt it lands
+  in pays for its whole length, so it points rather than teaches. That has a cost: an agent
+  gets a map and no detail, and the detail is where the expensive mistakes live. A skill is a
+  file with a one-line description that costs nothing until an agent decides it is relevant,
+  so a procedure can be written out in full. Two ship — one on changing the schema (who owns
+  it in your app, the mixin columns nothing declares, and why an unguarded `ALTER TABLE`
+  collides during a release's `migrate`) and one on shipping a release (naming your own deploy
+  steps, replacing the asset directory rather than merging into it, `trustedProxies` behind a
+  proxy, and the pipe that hides a test suite's exit status).
+
+  Written to `.agents/skills`, plus `.claude/skills` when that agent is detected. To replace
+  one this ships, edit it and delete its marker line — a `SKILL.md` without the marker is
+  yours and is never rewritten. `ArchConfig({ skills: false })` turns the feature off. Run
+  `zt arch:update` to install them.
+
+- **`zt doctor` reports agent instructions that no longer describe your project.** Every fact
+  in the generated block moves without anyone thinking about the file: add a migrations
+  directory, turn `synchronize` off, install a package. It goes on reading as current while
+  describing the app you used to have, and guidance that is confidently out of date gets
+  followed rather than questioned. Skills rot the same way and are easier to miss, since
+  nothing reads one until an agent decides it is relevant — by which point it is being acted
+  on. The check regenerates both and compares, and names `zt arch:update` as the fix. A
+  warning, not a failure: it misleads a reader, it does not stop the app working.
+
+### Changed
+
+- **A Flow page with nothing interactive on it opens no socket.** Every page connected at
+  boot, unconditionally — so a marketing page, a docs article or a rendered report held a
+  WebSocket per visitor, open on both ends for the life of the visit, to carry nothing. Both
+  paths that write to the socket take a `FlowComponent`, so with none registered there was not
+  a frame that _could_ be sent. The connection is made when something needs it now: after the
+  initial scan, after an SPA navigation, after a patch registers a child. `<Link navigate>`
+  fetches over HTTP, so a static page with links stays disconnected. A routed page honours the
+  same static, which is the half that matters — a page is a component, and one whose children
+  are static but which is interactive itself still connects.
+
+- **The `@zerotal/arch` agent block describes how your app is set up, not only what it
+  installed.** A package list answers "what is available here", which is not the question that
+  decides what an agent should write: the framework's contracts are not uniform across
+  projects, and the places they differ are the places where guessing wrong compiles cleanly and
+  fails at runtime. `AGENTS.md` now states the four facts that change an instruction — who owns
+  the schema, whether route names are typed, whether `exactOptionalPropertyTypes` or
+  `noUncheckedIndexedAccess` are on, and whether there are tests to run. Read off disk rather
+  than from a booted app, because a project that will not boot is often why the agent surface
+  is being installed. `.env` is deliberately not among the files read: this output is committed
+  and pasted into prompts, and a detector that reads secrets is one refactor away from emitting
+  them. Re-run `zt arch:update` to pick it up.
+
+### Fixed
+
+- **No mail could be sent over port 587.** A STARTTLS upgrade hands back a new socket and
+  leaves the old one attached, still firing its callbacks — and what that one delivers from
+  then on is the undecrypted TLS stream. Both sets of handlers appended to a single reply
+  buffer, so handshake records and ciphertext sat in the middle of the server's replies and no
+  line in the buffer matched a reply any more: the driver waited out its timeout without ever
+  parsing the `250`, and the server logged a connection lost after STARTTLS. Measured, 1,737
+  bytes of ciphertext went into the discarded socket's handler while the TLS handler received
+  the replies.
+
+  `close` and `error` were worse than `data`. The plaintext socket ending is a normal part of
+  handing over to TLS, and it marked the live connection closed — rejecting whatever was
+  waiting on the session that had just replaced it. Each set of callbacks now captures the
+  generation it was installed for, and an upgrade bumps it.
+
+- **An Inertia `303` redirect left the browser doing nothing at all.** `X-Inertia: true` was
+  set inside the 302-to-303 conversion, so it only ever reached a redirect that arrived as a
+  301 or 302 from a non-GET handler. A handler returning the 303 the protocol asks for skipped
+  the only line that marked its response — and `redirect(to, 303)` is what
+  [Authentication](/docs/authentication) tells people to write, in eight places. The form
+  submitted, the row was written, the mail went out, and the fields stayed filled in: a hang
+  from both ends, which is the worst shape a failure can take. Marking now happens for every
+  redirect status on an Inertia request, with the conversion a separate decision on top of it.
+  `307` and `308` are marked but left alone, since preserving the method is the whole reason to
+  choose them.
+
+- **Answering the busy-port menu killed `serve --dev` on the spot.** The banner printed, then
+  `exited with code 1`, and nothing said why. Reading a prompt locks Bun's stdin stream, and
+  the lock is deliberately held for the life of the command so a second prompt can still read —
+  so the dev deck taking the terminal over threw `ReadableStream is locked`. It died inside the
+  alternate screen buffer, and restoring the terminal on the way out erased the error along
+  with everything else drawn there, which is why this was reported as "it just exits" rather
+  than as the error it was. The prompt hands stdin back where it took it; a deck that still
+  cannot have stdin degrades to streaming rather than dying, and a dev-mode failure stops the
+  deck before it reports.
+
+- **Two builds sharing an output directory deleted each other's files.** Nothing forbids
+  `inertia:build` and `assets:build` writing to the same place, and the defaults invite it: one
+  writes to `public/assets`, `app.assets.outDir` often names the same directory, and the
+  default release pipeline runs them one after the other. The record of what to prune was one
+  flat list per directory, so each build read the other's files as its own previous build and
+  removed them. The release ended with whichever ran last and nothing reported a problem — the
+  build that lost still said "Build complete" on its way out, and the page it served then 404'd
+  its own script. The record is keyed by entry point now: a file another build claimed is not
+  this one's to remove, while chunks nobody claims are still swept.
+
+- **`zt doctor` failed a schema configuration that works.** Sync on plus migrations present
+  read as "the schema needs exactly one source of truth", which misses the documented
+  arrangement where sync builds the schema from the models so a fresh clone runs without a
+  migration step, and `synchronize` is an expression that is false in production, where the
+  deploy runs `migrate`. The two never apply in the same environment. It fails in production
+  now, where the deploy really does run both, and warns elsewhere. A check that cries wolf
+  against a correct configuration is what stops `zt doctor` ever being trusted to gate a
+  deploy.
+
+### Documented
+
+- **Replace a release directory, do not merge into it.** Chasing 195 orphaned chunks on a
+  server showed the build was never the problem — ten releases of a code-split app into one
+  directory hold steady at the build's own output, and every one of the reporting app's 68
+  chunks is referenced. What accumulates is the _release_: the archive is extracted over the
+  running directory, so every file in it is written and every file not in it is left alone, and
+  nothing on that machine ever runs a build. They stay publicly fetchable at their
+  content-hashed URLs, which is how copy that was taken down went on being served.
+  [Deployment](/docs/deployment) now gives the two spellings that replace the directory.
+
 ## 1.7.5 — 2026-08-23
 
 Two bugs that shipped to every deployed app, a package promoted to `stable`, and

package/docs/commands.md

@@ -315,6 +315,38 @@ Packages register their own — see
 | `bun zt doctor`        | Check the app for silent misconfigurations             |
 | `bun zt key:generate`  | Generate a new `APP_KEY` and write it to `.env`        |
 | `bun zt lint:packages` | Check every workspace package against convention rules |
+| `bun zt upgrade`       | Apply the codemods for a version upgrade               |
+
+### Upgrading between versions
+
+`bun zt upgrade --to <version>` applies the codemods a version gap calls for —
+mechanical rewrites the framework can make on your behalf when an API changes.
+
+```bash
+bun zt upgrade --to 2.0.0            # print the plan, change nothing
+bun zt upgrade --to 2.0.0 --write    # apply it
+```
+
+**It writes nothing unless you ask.** That is the opposite of most tools and
+deliberate: it rewrites source across your whole project, so the first run should
+be something you can read and disagree with. `--from` defaults to the `zerotal`
+version in your `package.json`.
+
+The half worth reading is the last one. A codemod that quietly walks past
+something it does not understand is worse than none, because the changes it _did_
+make suggest the job is finished — so anything it recognised and deliberately did
+not touch is listed with a file, a line and a reason:
+
+```text
+1 place(s) need a decision this cannot make for you:
+  app/models/Post.ts:9  export function all<T extends BaseModel>(rows: T[]): T[] {
+    `BaseModel` in a type position. It resolves to the same class as `Model`, so
+    this compiles either way — renaming it is a readability call, not a
+    correctness one.
+```
+
+Run it again after applying: a second run should report no changes. Codemods are
+idempotent, and that is the cheapest way to confirm one did what it said.
 
 `doctor` runs every static sanity check against the booted app and prints each
 finding with its fix: APP_KEY strength, `database.synchronize` colliding with

package/docs/deployment.md

@@ -71,6 +71,30 @@ Each entry is a `DeployTarget`:
 Omit the file entirely and you get `DEFAULT_DEPLOY_TARGETS`: `production` and
 `staging`, both with the default steps.
 
+The defaults build and migrate; they do not check anything you wrote. A preflight command
+of your own — `release:check`, a smoke test — has to be named in `steps` to run, and
+nothing prompts you to add it, so a command written precisely to guard a release can sit
+there never running. Name every step you want, in the order you want them:
+
+```ts
+// config/deploy.ts
+export default {
+  targets: {
+    production: {
+      url: "https://example.com",
+      steps: ["release:check", "assets:build", "inertia:build", "migrate"],
+    },
+  },
+};
+```
+
+Put a check first. A step that fails stops the release, and a check that runs after the
+migration has already run has missed its moment.
+
+Two things worth adding while you are there: `assets:build` and `inertia:build` accept
+`--clean`, which removes anything in the output directory the build did not write — see
+[Build assets](#build-assets).
+
 > **Note** — `deploy:<env>` runs **where the app runs**, with that environment's
 > variables. It does not reach another machine over SSH. Run it on the box, or in
 > the container build, as the step before the restart.
@@ -176,6 +200,56 @@ release that built its assets ahead of time and locked the tree down serves what
 shipped, and logs one line saying so. That is what lets the service run under a properly
 hardened unit; see [Hardening the service](#hardening-the-service).
 
+### Replace the asset directory on release, do not merge into it
+
+Code splitting names every chunk after its content, so each build emits a new set and
+abandons the last. Both build commands clean those up as they go, and they do it without
+needing anything to have survived from the previous build — so the directory a build
+writes holds that build's output and nothing else, on a developer's machine and a fresh CI
+checkout alike.
+
+What the build cannot clean is a directory it never sees. A release that is **unpacked over
+the top** of the running one — `tar -xzf` into the app directory, `rsync` without
+`--delete` — merges: every file in the archive is written, and every file that is not in
+the archive is left exactly where it was. Nothing on that server ever ran a build, so
+nothing ever removes last release's chunks, and they collect one release at a time.
+
+That is not only clutter. They stay publicly fetchable at their content-hashed URLs, so a
+page whose copy you withdrew is still readable by anyone holding the link — pricing you
+took down, a policy you replaced, a feature you pulled.
+
+Clear the directory as part of the release, before the new files land:
+
+```bash
+# on the server, before extracting
+rm -rf "$APP_DIR/public/assets"
+tar -xzf release.tgz -C "$APP_DIR"
+
+# or let rsync do it
+rsync -a --delete public/assets/ "$HOST:$APP_DIR/public/assets/"
+```
+
+Ordering matters if the old release is still serving traffic: clearing the directory takes
+its bundles away, so do it as close to the swap as you can, or stage the release in a new
+directory and move it into place.
+
+### `--clean` for a directory the build does not own outright
+
+The cleanup above recognises the filenames `Bun.build()` produces. An app that sets its own
+`naming`, or that writes a second bundle into the same directory by other means, can leave
+output the build does not recognise as its own. `--clean` needs no recognition — whatever
+this build did not write, goes:
+
+```bash
+# in your project root
+bun zt assets:build --clean
+bun zt inertia:build --production --clean
+```
+
+It refuses `public/` itself and the project root, where deleting what was not rebuilt would
+take the app's images and favicon with it. Point the build at a directory of its own —
+`public/assets` is the Inertia default.
+
 Bump your asset version (or hash the bundle) so clients reload onto the new build — see
 [Inertia › Asset versioning](/docs/inertia/middleware#asset-versioning).
 
@@ -253,6 +327,29 @@ Origins are compared exactly: no wildcards and no suffix matching, because
 
 > **Warning** — an app with the wrong origin configured renders every page correctly and refuses every action. There is no 500, nothing in the logs, and a status-code health check passes. The only symptom is that buttons do nothing.
 
+### Rate limiting counts the proxy, not the visitor
+
+`ThrottleMiddleware` identifies a client by the address the request arrived from. Behind a
+proxy that address is the proxy — `127.0.0.1` for every visitor on the site — so one bucket
+is shared by everybody, and a single busy client can lock the whole site out.
+
+Tell it how many proxies sit in front of the app:
+
+```ts fragment
+// One proxy (Caddy, nginx, a load balancer) between the internet and the app.
+ThrottleMiddleware.with({ maxAttempts: 60, trustedProxies: 1 });
+```
+
+The count is how many entries to skip from the right of `X-Forwarded-For`. It is opt-in and
+defaults to zero because the header is written by the client until something trusted
+overwrites it: trusting it by default would let anyone forge an address and walk around
+every limit you set. Zero is the safe default and the wrong answer once you deploy behind
+something — which is easy to do and never revisit, because nothing about it fails loudly.
+The symptom is a legitimate visitor getting a 429 they did not earn.
+
+Count the proxies you actually run. Setting `trustedProxies: 3` with one proxy in front
+reads an entry the client supplied.
+
 ### Never gate the transport path
 
 **Browsers do not attach basic-auth credentials to a WebSocket handshake.** An HTTP auth

package/docs/flow/index.md

@@ -195,7 +195,7 @@ The names in use:
 | Group             | Names                                                                                                                 |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
 | Lifecycle         | `onBoot` `onMount` `onHydrate` `onDehydrate` `onRendering` `onRendered` `onUpdate` `onUpdating` `onUpdated` `onError` |
-| Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child`                                                              |
+| Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child` `isInteractive`                                              |
 | Actions & state   | `bind` `validate` `resetValidation` `errors` `addError` `refresh` `$refresh` `$set` `cancelled` `signal`              |
 | Navigation        | `redirect` `redirectRoute` `redirectIntended` `currentUrl` `navigateCurrent`                                          |
 | Events & realtime | `dispatch` `dispatchSelf` `dispatchTo` `stream` `client` `$`                                                          |

package/docs/flow/layouts.md

@@ -365,6 +365,70 @@ export class CounterWidget extends Component {
 
 Props that need to survive WebSocket round-trips must be `@locked` so they are included in the snapshot. A `@locked` prop is set once at mount and stays fixed for the child's lifetime.
 
+### Static children
+
+A child that will never receive an action does not need to be an island. Declare
+`static interactive = false` and it is rendered as plain markup:
+
+```tsx fragment
+export class SiteHeader extends Component {
+  static interactive = false;
+
+  override async render() {
+    return <header class="site-header">{/* … */}</header>;
+  }
+}
+```
+
+No snapshot, no state script, no entry in the client's component registry — and
+nothing on the wire for it beyond the HTML itself. Use it for the parts of a page
+that are structure rather than behaviour: headers, nav rails, footers, marketing
+sections.
+
+**A static child re-renders with its parent.** That is the difference that
+matters. An interactive child is preserved across a parent update — its DOM and
+state are left alone, which is the point of an island. A static child has no
+state to preserve, so it is rendered fresh every time the parent renders, and
+props passed to it are simply current.
+
+It cannot be `lazy`, `defer` or `stream`: each of those waits for the client to
+ask for the real render, and a static child never registers with the client to
+do the asking. Passing one throws rather than leaving a placeholder that never
+resolves.
+
+Inside the component, `this.isInteractive` reports which mode it is in — useful
+for leaving out something that only makes sense with a client attached.
+
+### A wholly static page opens no socket
+
+`static interactive = false` works on a routed page as well as on a child, and the
+page is the one that matters: a page is a component too, so a page whose children
+are all static but which is interactive itself still registers with the client —
+and still connects.
+
+```tsx fragment
+export class ChangelogPage extends Component {
+  static interactive = false;
+
+  override async render() {
+    return <article>{/* … */}</article>;
+  }
+}
+```
+
+When nothing on the page registers, **no WebSocket is opened at all**. Not opened
+and idle — never created. For a marketing page, a documentation article or a
+rendered report, that is one connection per visitor that no longer exists on
+either end.
+
+The connection is made when it is needed rather than at boot, so a page that
+becomes interactive later — an SPA navigation to one that is, a deferred child
+arriving — connects at that moment. `<Link navigate>` needs nothing: it fetches
+over HTTP.
+
+A page with a single interactive component still connects, as before. One is
+enough.
+
 ### Slots
 
 Where props pass **data** into a child, slots pass **markup**. A child component's plain children become its **default slot**; a `slots={{ … }}` prop supplies **named slots**. Inside the child, place each with `this.slot(name)` (or `this.slot()` for the default), and branch on `this.hasSlot(name)` to drop an optional wrapper entirely. This is the pattern for reusable shells — cards, modals, panels, page headers — where the container is fixed but the contents vary per use.

package/docs/testing/index.md

@@ -209,6 +209,32 @@ observers, global scopes, and state-machine callbacks, plus framework event
 subscriptions. `createTestApp()` and `testApp.close()` call it for you, so suites
 using those helpers don't need the explicit `afterEach`.
 
+## Running the suite from a script
+
+A script that gates on the tests has to read the tests' exit status, and a pipe hides it:
+
+```bash
+bun test 2>&1 | tail -3     # the status is tail's. Always 0, however the suite went.
+```
+
+The suite is verbose enough that piping it somewhere is the natural thing to write, which
+is what makes this worth saying: a deploy script written that way prints `1 fail` and
+carries straight on to upload and restart. Nothing is wrong with the output — it is the
+`$?` behind it that belongs to the last command in the pipe.
+
+Either turn the pipe honest, or do not pipe:
+
+```bash
+set -o pipefail             # bash/zsh: the pipeline fails if any stage does
+bun test 2>&1 | tail -3
+
+# or keep the status and the output separately
+bun test > test.log 2>&1 || { tail -20 test.log; exit 1; }
+```
+
+`set -e` alone does not cover it — the pipeline succeeded, as far as the shell is
+concerned.
+
 ## References
 
 The most-used members exported from `@zerotal/testing`. Each area's page documents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.7.5",
+  "version": "1.8.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.7.5"
+    "@zerotal/core": "1.8.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.7.5"
+    "@zerotal/orm": "1.8.0"
   },
   "description": "The Zerotal agent surface — an MCP server that hands coding agents the framework's machine-readable truth: exact API signatures, live routes and schema, version-matched docs, and `zt doctor`.",
   "keywords": [

package/src/config.ts

@@ -22,6 +22,13 @@ export interface ArchConfigShape {
    * `AGENTS.md` natively, and two files of guidance drift apart.
    */
   claudeFile: boolean;
+  /**
+   * Write the agent skill files.
+   *
+   * On by default: they cost nothing until an agent decides one is relevant,
+   * which is the entire reason they are files rather than more of `AGENTS.md`.
+   */
+  skills: boolean;
   /** Write the MCP client configuration. Default: `true`. */
   mcpConfig: boolean;
   /** Path of the MCP client config, relative to the project root. */
@@ -37,6 +44,7 @@ export interface ArchConfigShape {
 const defaults: ArchConfigShape = {
   agentsFile: true,
   claudeFile: true,
+  skills: true,
   mcpConfig: true,
   mcpConfigPath: ".mcp.json",
   serverName: "zerotal",

package/src/install/ArchInstallCommand.ts

@@ -19,6 +19,9 @@ import { NoProjectRootError } from "../errors.ts";
 import { installedPackages } from "../probe/topics.ts";
 import { detectAgents } from "./detect.ts";
 import { agentsPreamble, buildGuidelines, claudeShim } from "./guidelines.ts";
+import { detectShape } from "./shape.ts";
+import { selectSkills, renderSkill, skillPaths, SKILL_MARKER } from "./skills.ts";
+import type { ProjectShape } from "./shape.ts";
 import { applyBlock } from "./markers.ts";
 import { applyMcpConfig } from "./mcpConfig.ts";
 
@@ -52,11 +55,15 @@ export class ArchInstallCommand extends Command {
 
     const detected = await detectAgents(root);
     const packages = (await installedPackages(root)).map((pkg) => pkg.name);
+    // Read off disk rather than from a booted app: a project that will not boot is
+    // often exactly why someone is installing the agent surface.
+    const shape = await detectShape(root);
 
     const changes: Change[] = [
       ...(config.mcpConfig ? await this._mcpChanges(root, config, detected.targets) : []),
-      ...(config.agentsFile ? [await this._agentsChange(root, config, packages)] : []),
+      ...(config.agentsFile ? [await this._agentsChange(root, config, packages, shape)] : []),
       ...(config.claudeFile ? [await this._claudeChange(root)] : []),
+      ...(config.skills ? await this._skillChanges(root, packages, shape, detected.agents) : []),
     ];
 
     this.section(dry ? "arch:install — dry run" : "arch:install");
@@ -77,7 +84,7 @@ export class ArchInstallCommand extends Command {
         continue;
       }
       if (change.status === "unchanged") {
-        this.dim(`  · ${change.path} — already up to date`);
+        this.dim(`  · ${change.path} — ${change.detail ?? "already up to date"}`);
         continue;
       }
       if (!dry && change.text !== undefined) {
@@ -153,10 +160,11 @@ export class ArchInstallCommand extends Command {
     root: string,
     config: ArchConfigShape,
     packages: string[],
+    shape: ProjectShape,
   ): Promise<Change> {
     const outcome = applyBlock(
       await readIfPresent(join(root, "AGENTS.md")),
-      buildGuidelines({ packages, serverName: config.serverName }),
+      buildGuidelines({ packages, serverName: config.serverName, shape }),
       agentsPreamble(),
     );
     return outcome.status === "conflict"
@@ -164,6 +172,41 @@ export class ArchInstallCommand extends Command {
       : { path: "AGENTS.md", status: outcome.status, text: outcome.text };
   }
 
+  /**
+   * The skill files, one per applicable skill per agent directory.
+   *
+   * A file without {@link SKILL_MARKER} is left exactly as it is. That is the
+   * whole override mechanism: to replace a skill this ships, edit it and delete
+   * the marker line. Anything cleverer would be a second config to keep in step
+   * with the thing it configures.
+   */
+  private async _skillChanges(
+    root: string,
+    packages: string[],
+    shape: ProjectShape,
+    agents: string[],
+  ): Promise<Change[]> {
+    const changes: Change[] = [];
+
+    for (const skill of selectSkills(packages, shape)) {
+      const text = renderSkill(skill, shape);
+      for (const path of skillPaths(skill.name, agents)) {
+        const existing = await readIfPresent(join(root, path));
+        if (existing !== undefined && !existing.includes(SKILL_MARKER)) {
+          changes.push({ path, status: "unchanged", detail: "yours — left alone" });
+          continue;
+        }
+        changes.push(
+          existing === text
+            ? { path, status: "unchanged" }
+            : { path, status: existing === undefined ? "created" : "updated", text },
+        );
+      }
+    }
+
+    return changes;
+  }
+
   private async _claudeChange(root: string): Promise<Change> {
     const outcome = applyBlock(await readIfPresent(join(root, "CLAUDE.md")), claudeShim());
     return outcome.status === "conflict"