@zerotal/arch 1.7.4 → 1.8.0

package/CHANGELOG.md

@@ -4,11 +4,95 @@ All notable changes to this package are documented here. The format is
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-**Maturity: beta.** The API is close to final and breaking changes are rare, called out
-here with migration steps — but a minor release may still contain one.
+**Maturity: `stable`** — matching this package's `maturity` field. The public API
+follows SemVer strictly: anything importable without an `@internal` marker keeps its
+shape for the rest of the 1.x line, and `api-surface.md` is diffed by CI on every
+change. That promise covers the MCP tool contract too — the tool names, their inputs
+and the shape of what they return — which is the part an agent client is configured
+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
+
+- **`@zerotal/arch` is `stable`.** Reviewed ahead of its 1.9.0 date. The public API
+  follows SemVer strictly from here, and that promise covers the MCP tool contract —
+  tool names, their inputs, and the shape of what they return — because that is what
+  an agent client is configured against and nothing type-level can see it. The
+  protocol revision the server speaks is not covered; it follows the protocol.
+
+- **INTERNAL — the writers behind `arch:install` are no longer public API.** `detectAgents`,
+  `applyMcpConfig`, `serverEntry`, `SERVER_ENTRY_PATH`, `applyBlock`, `fence`,
+  `BLOCK_START`, `BLOCK_END`, `agentsPreamble`, `buildGuidelines`, `claudeShim` and
+  their types. They are still exported and still work; they are no longer promised.
+  Their only caller is `ArchInstallCommand`, and freezing them would have committed
+  the shape of `.mcp.json` writing and marker fencing to the rest of the 1.x line on
+  behalf of a caller who never arrived. Marked before the label attached rather than
+  withdrawn after.
+
+- **INTERNAL — `api-surface.md` now honours `@internal` across every package.** The
+  contract has always been stated as "anything importable without an `@internal`
+  marker keeps its shape", and the generator did not read the tag: symbols already
+  marked internal were recorded as though promised. They are omitted now — 374
+  entries across 13 packages, every one verified marked, either at its declaration
+  or by a module docblock covering a whole subpath as `@zerotal/core/dev` does.
+  Nothing changes at runtime or in the types. What changed is that the file listing
+  the promises lists the promises.
+
 ## [1.7.1] — 2026-08-16
 
 ### Fixed

package/README.md

@@ -1,7 +1,9 @@
 # @zerotal/arch
 
-**Maturity: beta.** The API is close to final and breaking changes are rare, called out
-in release notes with migration steps — but a minor release may still contain one. See
+**Maturity: stable.** The public API follows SemVer strictly: anything importable
+without an `@internal` marker keeps its shape for the rest of the 1.x line. That
+covers the MCP tool contract too — tool names, their inputs, and the shape of what
+they return — since that is what an agent client is configured against. See
 the [support policy](https://zerotal.dev/docs/support-policy#maturity-levels).
 
 The Zerotal agent surface: an MCP server that hands a coding agent the framework's

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/about.md

@@ -131,7 +131,7 @@ my-app/
 `zt.ts` is the entry point for **everything** — `bun zt serve`, `migrate`, `test`,
 and every `make:*` generator run through it. It boots `bootstrap/app.ts`:
 
-```ts
+```ts fragment
 // bootstrap/app.ts
 import { Application } from "zerotal";
 import { Handler } from "../app/exceptions/Handler.ts";
@@ -166,7 +166,7 @@ Read [Request Lifecycle](/docs/lifecycle) for the exact sequence.
 Routes are registered by calling static `Router` methods at module load — map a path
 to a controller + action, or to an inline closure:
 
-```ts
+```ts fragment
 // routes/index.ts
 import { Router, view, type HttpContext } from "zerotal";
 import HomeController from "../app/controllers/HomeController.ts";
@@ -200,7 +200,7 @@ the app builder. Full details in [Routing](/docs/routing).
 Controllers are plain classes; the action receives the request `HttpContext` and
 dependencies resolve from the container:
 
-```ts
+```ts fragment
 // app/controllers/PostController.ts
 import type { HttpContext } from "zerotal";
 import Post from "../models/Post.ts";
@@ -233,7 +233,7 @@ e.g. `ctx: HttpContext<{ post: Post }>`. More in [Controllers](/docs/controllers
 Active Record–style models backed by `Bun.sql`. Columns and relationships are
 decorators; the table name is derived by convention (so `@table` is optional):
 
-```ts
+```ts fragment
 // app/models/Post.ts
 import { Model, table, column, hasMany, belongsTo } from "@zerotal/orm";
 
@@ -255,7 +255,7 @@ export default class Post extends Model {
 
 The fluent query builder and relationship loading:
 
-```ts
+```ts fragment
 // in a controller or service
 const posts = await Post.query()
   .withScopes((s) => s.published())
@@ -321,7 +321,7 @@ export class StorePostRequest extends FormRequest {
 }
 ```
 
-```ts
+```ts fragment
 // in a controller — reads the current HttpContext, returns typed data,
 // throws a 422 (JSON) or a redirect-back on failure.
 const data = await StorePostRequest.validate();
@@ -333,7 +333,7 @@ More rules and patterns in [Validation](/docs/validator).
 
 Session auth, bearer tokens, and policy-based authorization ship together:
 
-```ts
+```ts fragment
 // in a controller / service
 import { Auth, Gate, createToken } from "@zerotal/auth";
 
@@ -415,7 +415,7 @@ decorator and directive set.
 Build a React or Vue SPA with no separate API layer. Controllers return page
 responses; the Inertia client renders the matching component:
 
-```ts
+```ts fragment
 // app/controllers/DashboardController.ts
 import { inertia } from "@zerotal/inertia";
 import { Post } from "../models/Post.ts";
@@ -428,7 +428,7 @@ export class DashboardController {
 }
 ```
 
-```tsx
+```tsx fragment
 // resources/js/pages/Dashboard.tsx (React)
 import { Link } from "@inertiajs/react";
 
@@ -457,7 +457,7 @@ reloads, deferred props, SSR, and precognition. See [Inertia](/docs/inertia).
 Push slow work off the request. Jobs serialize to a plain payload so they survive the
 queue:
 
-```ts
+```ts fragment
 // app/jobs/SendWelcomeEmail.ts
 import { Job, JobRegistry } from "@zerotal/queue";
 import { User } from "../models/User.ts";
@@ -487,7 +487,7 @@ export class SendWelcomeEmail extends Job {
 JobRegistry.register(SendWelcomeEmail);
 ```
 
-```ts
+```ts fragment
 // dispatch from anywhere
 import { Queue, Bus } from "@zerotal/queue";
 
@@ -504,7 +504,7 @@ Run a worker with `bun zt queue:work`. There's also a
 
 ## Cache
 
-```ts
+```ts fragment
 // in a controller or service
 import { Cache } from "@zerotal/cache";
 
@@ -512,7 +512,7 @@ const posts = await Cache.remember("posts.recent", 60, () =>
   Post.query().orderBy("created_at", "desc").limit(10).get(),
 );
 
-await Cache.put("key", value, 300);
+await Cache.set("key", value, 300);
 await Cache.forget("key");
 
 // Tag-based invalidation
@@ -527,7 +527,7 @@ In-memory and Redis drivers, plus idempotency helpers. See [Cache](/docs/cache).
 One `Notification` class fans out across channels — mail, database, broadcast, Slack,
 SMS:
 
-```ts
+```ts fragment
 // app/notifications/InvoicePaid.ts
 import { Notification, MailMessage } from "@zerotal/notifications";
 
@@ -548,7 +548,7 @@ export class InvoicePaid extends Notification {
 }
 ```
 
-```ts
+```ts fragment
 // The User model mixes in Notifiable, which provides .notify()
 await user.notify(new InvoicePaid(invoice));
 ```
@@ -584,7 +584,7 @@ Generate or rotate the key with `bun zt key:generate`. Full system in
 
 First-class HTTP, database, and fake helpers:
 
-```ts
+```ts fragment
 // tests/posts.test.ts
 import { createTestApp, Factory, assertDatabaseHas } from "@zerotal/testing";
 import { NotificationFake } from "@zerotal/notifications";

package/docs/admin/actions.md

@@ -9,7 +9,7 @@ Actions power the row, header, and bulk buttons. The defaults are
 `viewAction()/editAction()/deleteAction()` (rows), `createAction()` (header), and
 `bulkDeleteAction()` (bulk) — override the corresponding methods to customize.
 
-```ts
+```ts fragment
 import { action, editAction, deleteAction, textInput } from "@zerotal/admin";
 
 static recordActions() {
@@ -28,7 +28,7 @@ static recordActions() {
 A row with more than three visible actions collapses the surplus into an overflow
 menu. Actions can also open a **modal form**:
 
-```ts
+```ts fragment
 action("assign")
   .label("Assign reviewer")
   .form([ select("reviewer_id").options(reviewers).required() ])
@@ -43,7 +43,7 @@ action("assign")
 A row with seven buttons is unreadable. `actionGroup` collapses several into one
 labelled dropdown, so the row keeps the two people reach for and files the rest:
 
-```ts
+```ts fragment
 import { actionGroup, replicateAction, deleteAction } from "@zerotal/admin";
 
 static recordActions() {
@@ -67,7 +67,7 @@ nothing. Groups work in the header and the bulk toolbar too.
 `replicateAction()` copies a record and opens the copy for editing. The primary key
 and timestamps are always dropped; name anything else that must stay unique:
 
-```ts
+```ts fragment
 replicateAction()
   .excludeAttributes(["sku", "slug"])
   .beforeReplicaSaved((data) => ({ ...data, name: `${data.name} (copy)`, status: "draft" })),
@@ -75,7 +75,7 @@ replicateAction()
 
 ## Import and export
 
-```ts
+```ts fragment
 import { exportAction, importAction, bulkExportAction } from "@zerotal/admin";
 
 static headerActions() {
@@ -94,7 +94,7 @@ exports the selection instead.
 
 Pass `"xlsx"` for a spreadsheet instead:
 
-```ts
+```ts fragment
 return [createAction(), exportAction(), exportAction("xlsx")];
 ```
 
@@ -107,7 +107,7 @@ header row is frozen with a filter over the used range.
 Keep a column out of the file with `.exportable(false)`. Pay, internal notes and
 anything else that should not travel in a spreadsheet belongs behind that flag:
 
-```ts
+```ts fragment
 text("salary").exportable(false),
 ```
 
@@ -129,7 +129,7 @@ An import runs inline by default, capped at 2,000 rows — a synchronous import
 holds a WebSocket round-trip open, and a bigger file looks like a hang. Hand it
 to a queue instead and the cap lifts:
 
-```ts
+```ts fragment
 static headerActions() {
   return [createAction(), exportAction(), importAction({ queue: true })];
 }
@@ -153,7 +153,7 @@ imported only when an import is actually queued.
 
 Relation managers appear as tables on the View page.
 
-```ts
+```ts fragment
 import { hasMany, belongsToMany } from "@zerotal/admin";
 
 static relations() {

package/docs/admin/auth.md

@@ -9,7 +9,7 @@ Opt in with `Panel.auth({...})` (or `Panel.configure({ auth: {...} })`). The pag
 live behind the `@zerotal/admin/auth` subpath, so the `@zerotal/auth` dependency
 stays optional unless you enable them.
 
-```ts
+```ts fragment
 import { Panel } from "@zerotal/admin";
 
 Panel.auth({
@@ -52,7 +52,7 @@ left to your auth middleware — the rest of the flow ships here.
 
 The panel is public until you set guard middleware. A typical setup:
 
-```ts
+```ts fragment
 Panel.configure({ middleware: [AuthMiddleware, RequireRoleMiddleware.with("admin")] });
 Panel.auth({ enabled: true }); // login lives outside that guard automatically
 ```

package/docs/admin/dashboard.md

@@ -7,7 +7,7 @@ description: Widgets, global search, the command palette, notifications, and the
 
 Register widgets with `Panel.widgets(...)`; they render on the dashboard.
 
-```ts
+```ts fragment
 import { Panel, statsWidget, stat, chartWidget, tableWidget } from "@zerotal/admin";
 
 Panel.widgets(
@@ -41,7 +41,7 @@ The dashboard answers "how is the business doing". A resource's own widgets
 answer "what is going on in _this_ list" — a pending count above the orders
 table, stock value above products:
 
-```ts
+```ts fragment
 export class OrderResource extends Resource {
   static override widgets() {
     return [
@@ -62,7 +62,7 @@ someone watching a queue actually wants.
 A dashboard on a second screen is stale the moment it renders. `.poll()` gives a
 widget an interval:
 
-```ts
+```ts fragment
 statsWidget(async () => [
   stat("Awaiting payment", await Order.query().where("status", "pending").count()),
 ]).poll("30s"),
@@ -85,7 +85,7 @@ page.
 The admin owns the bell + notifications page UI; your app supplies the data through a
 provider (the same split as relations — admin UI, app data):
 
-```ts
+```ts fragment
 import { Panel } from "@zerotal/admin";
 
 Panel.notifications({
@@ -124,7 +124,7 @@ notifications" depends on your auth and your schema. When both are the ordinary
 ones — `@zerotal/auth` for the user, `@zerotal/notifications`' `DatabaseChannel`
 for storage — there is a ready-made one:
 
-```ts
+```ts fragment
 import { databaseNotifications } from "@zerotal/admin";
 
 Panel.notifications(databaseNotifications());

package/docs/admin/extending-ui.md

@@ -23,7 +23,7 @@ everything else alone.
 **Table cells.** The column still owns its label, sorting, search and export;
 only the cell is yours:
 
-```ts
+```ts fragment
 text("health")
   .label("Health")
   .sortable()
@@ -32,7 +32,7 @@ text("health")
 
 **Infolist entries.** The section's grid still places it:
 
-```ts
+```ts fragment
 textEntry("route").render((value) => <RouteMap path={String(value)} />),
 ```
 
@@ -40,7 +40,7 @@ textEntry("route").render((value) => <RouteMap path={String(value)} />),
 saves like any other — you supply only the control. Bind your markup to
 `form.<key>` for the value to round-trip:
 
-```ts
+```ts fragment
 customField("coordinates")
   .label("Location")
   .required()
@@ -55,7 +55,7 @@ what lets a control react to a sibling field.
 A contributed page can only add a page. A hook adds markup at a named position
 in the chrome — a trial banner, a compliance notice, an environment badge:
 
-```ts
+```ts fragment
 Panel.renderHook("page.header.end", () => <TrialBanner />);
 
 // Conditional placement: register once, decide per render.
@@ -92,7 +92,7 @@ A resource does not have to be backed by a model. Return rows from `data()` and
 the panel filters, sorts and paginates them in memory, so search, tabs,
 summaries and the query builder all keep working:
 
-```ts
+```ts fragment
 export class RegionResource extends Resource {
   static override async data() {
     return await fetch("https://api.example.com/regions").then((r) => r.json());
@@ -115,7 +115,7 @@ rows and not millions. Past that, back it with a model or a view.
 
 Four statics change how a list renders:
 
-```ts
+```ts fragment
 export class ProductResource extends Resource {
   static override tableLayout = "grid"; // "table" (default) | "grid" | "kanban" | "calendar"
   static override striped = true;
@@ -131,7 +131,7 @@ title, and the next few render as label/value pairs. No second description.
 
 **Kanban** turns a status column into lanes, for records that read as a pipeline:
 
-```ts
+```ts fragment
 static override tableLayout = "kanban";
 static override kanbanColumn = "status";
 static override kanbanLanes = { pending: "Pending", paid: "Paid", shipped: "Shipped" };
@@ -144,7 +144,7 @@ does, not a second source of truth. A value present in the data but missing from
 
 **Calendar** lays the page out as a month grid keyed on a date column:
 
-```ts
+```ts fragment
 static override tableLayout = "calendar";
 static override calendarColumn = "startsOn";
 ```
@@ -159,7 +159,7 @@ on wide or long tables.
 
 A resource whose records nest under each other renders as a tree:
 
-```ts
+```ts fragment
 export class CategoryResource extends Resource {
   static override treeParentColumn = "parentId";
 }
@@ -176,7 +176,7 @@ than disappearing, so a filtered tree never hides a record.
 
 A resource whose text exists in several languages edits one at a time:
 
-```ts
+```ts fragment
 export class PostResource extends Resource {
   static override translatable = ["title", "excerpt"];
   static override locales = ["en", "fr"];
@@ -193,7 +193,7 @@ turning this on for an existing column does not blank it.
 
 A column can carry its own filter box in the table header:
 
-```ts
+```ts fragment
 text("sku").filterable();
 selectColumn("status", STATUS).filterable();
 ```
@@ -209,7 +209,7 @@ the active-filter chips, and land in a saved view.
 Filters sit above the table by default. Once there are more than a few, collapse
 them:
 
-```ts
+```ts fragment
 static override filterLayout = "panel";   // "inline" (default) | "panel" | "drawer"
 ```
 

package/docs/admin/extending.md

@@ -55,11 +55,20 @@ That last row is the important one. A panel with no authorization wired stays
 closed in production, the same posture the panel guard already takes, which is
 what makes it safe for a package to add pages without the app asking.
 
-```ts
+```ts fragment
 // config/admin.ts
-export default {
-  authorize: (ability) => currentUser()?.permissions.includes(ability) ?? false,
-};
+import { AdminConfig } from "@zerotal/admin";
+import { Auth } from "@zerotal/auth";
+
+// Through the factory, not a bare object: it is what types `ability`, and every
+// other config in the framework is written this way.
+export default AdminConfig({
+  // `userOrNull()`, not `user()` — this runs for guests too, and `user()` throws
+  // rather than returning one. `can()` comes from the permissions mixin on your
+  // own User model, which is why this block is a fragment: the type depends on
+  // your app, not on the framework.
+  authorize: (ability) => Auth.userOrNull()?.can(ability) ?? false,
+});
 ```
 
 Resources are the exception: they authorize through their own
@@ -75,7 +84,7 @@ and without depending on `@zerotal/admin`.
 
 A contributing provider resolves the binding in its `onBooting` and pushes:
 
-```ts
+```ts fragment
 // packages/queue/src/admin.ts
 interface AdminHost {
   enabled(id: string): boolean;
@@ -117,7 +126,7 @@ JSX, no `@zerotal/flow` dependency and no build configuration. The panel owns
 the markup, which also means every console looks like the rest of the admin
 without trying to.
 
-```ts
+```ts fragment
 panel.console({
   slug: "jobs",
   title: "Jobs",
@@ -180,7 +189,7 @@ is read early enough.
 Application code can name the panel directly, so it doesn't need the container
 dance. Group a set of related contributions behind an `AdminPlugin`:
 
-```ts
+```ts fragment
 await Panel.plugin({
   id: "billing",
   install: (panel) => {

package/docs/admin/forms.md

@@ -8,7 +8,7 @@ description: Build create and edit forms, and lay out the read-only view screen.
 `form()` returns fields (and layout components). An empty `form()` disables
 Create/Edit for the resource.
 
-```ts
+```ts fragment
 import {
   textInput, textarea, select, toggle, datePicker, fileUpload, richEditor,
   formSection, formTabs, formTab, wizard, wizardStep,
@@ -80,7 +80,7 @@ patch)` runs server-side and merges a patch into the form (e.g. derive a slug).
 `repeater` edits an array of objects sharing one sub-schema; `builder` edits an array
 of typed blocks. Rows can be added, removed, and reordered.
 
-```ts
+```ts fragment
 import { repeater, builder, builderBlock, textInput, textarea, fileUpload } from "@zerotal/admin";
 
 repeater("contacts").minItems(1).addActionLabel("Add contact").schema([
@@ -101,7 +101,7 @@ Repeaters serialize to `[{ ...fields }]`; builders to `[{ type, data }]`.
 `infolist()` describes the read-only detail page. Omit it to fall back to a section
 derived from `columns()`.
 
-```ts
+```ts fragment
 import { section, textEntry, iconEntry } from "@zerotal/admin";
 
 static infolist() {
@@ -136,7 +136,7 @@ usefully read as text:
 `repeatableEntry` is the read side of `repeater`: whatever the form wrote into a
 JSON column, this reads back in the same shape.
 
-```ts
+```ts fragment
 section("Line items").schema([
   repeatableEntry("lines")
     .placeholder("This order has no line items.")

package/docs/admin/index.md

@@ -47,7 +47,7 @@ List / View / Create / Edit page per resource under the configured `path`.
 
 ## Quick start
 
-```ts
+```ts fragment
 // app/admin.ts
 import { Panel, Resource, text, textInput } from "@zerotal/admin";
 import { User } from "./models/User.ts";
@@ -88,7 +88,7 @@ Edit / View / Delete — and the form above on the Create and Edit pages.
 Configure the panel with `Panel.configure(...)` in `app/admin.ts`, or by exporting
 an `admin` config object the provider merges on boot.
 
-```ts
+```ts fragment
 Panel.configure({
   path: "/admin",
   brand: "Acme",