@zerotal/arch 1.7.4 → 1.8.0

package/docs/validator.md

@@ -89,7 +89,7 @@ export class StorePostRequest extends FormRequest {
 Call `validate()` as a static method on the class. It reads `HttpContext` from
 `AsyncLocalStorage` — no arguments needed.
 
-```typescript
+```typescript fragment
 // in a controller
 const data = await StorePostRequest.validate();
 
@@ -116,7 +116,7 @@ never need to catch them yourself.
 `authorize()` runs **before** validation. Returning `false` throws a
 `ForbiddenError` (403) without touching the request body.
 
-```typescript
+```typescript fragment
 // in a FormRequest subclass
 
 // Check the current user's role:
@@ -141,7 +141,7 @@ async authorize(): Promise<boolean> {
 Because `rules()` is an instance method, you have full access to `this.context`
 for rules that depend on the current user, route params, or session state:
 
-```typescript
+```typescript fragment
 // in a FormRequest subclass
 rules(r: RuleBuilder) {
   const userId = this.context.user?.id;
@@ -157,7 +157,7 @@ rules(r: RuleBuilder) {
 
 For simple one-off validation without a dedicated class:
 
-```typescript
+```typescript fragment
 // in a controller
 import { validate } from "@zerotal/validator";
 
@@ -180,7 +180,7 @@ For CLI commands, services, or background jobs — where there is no request to
 redirect and no response to throw — use the `Validator` facade. It returns a
 `{ success, data, errors }` outcome and never throws.
 
-```typescript
+```typescript fragment
 // in a command or service
 import { Validator } from "@zerotal/validator";
 
@@ -200,7 +200,7 @@ if (!result.success) {
 
 Start every rule chain with a type method on `RuleBuilder`:
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 const r = new RuleBuilder(); // or the `r` param in rules()
 
@@ -247,7 +247,7 @@ These are available on **every** rule type:
 
 ### Custom validator
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 username: r.string().custom(async (value) => {
   const taken = await User.findBy("username", value as string);
@@ -257,7 +257,7 @@ username: r.string().custom(async (value) => {
 
 ## String rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.string()
   .min(3) // minimum character length
@@ -292,7 +292,7 @@ r.string()
 
 ## Number rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.number()
   .min(0) // minimum value (inclusive)
@@ -305,7 +305,7 @@ r.number()
 
 ## Boolean rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.boolean()
   .accepted() // truthy — for "agree to terms" checkboxes
@@ -314,7 +314,7 @@ r.boolean()
 
 ## Date rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.date()
   .after("2026-01-01") // strictly after date
@@ -325,7 +325,7 @@ r.date()
 
 ## Array rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.array(r.string()) // array of strings
   .min(1) // minimum item count
@@ -340,7 +340,7 @@ r.array(r.object({ name: r.string(), age: r.number() }));
 
 ## Object rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.object({
   street: r.string(),
@@ -357,7 +357,7 @@ r.object({
 
 Validates `File` objects from `multipart/form-data` uploads:
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 avatar: r.file()
   .mimes(["jpg", "jpeg", "png", "webp"]) // allowed extensions
@@ -368,7 +368,7 @@ avatar: r.file()
 
 ## Password rules
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 r.password()
   .min(8) // minimum length (default: 8)
@@ -390,7 +390,7 @@ The third argument ignores a record on update — pass the current record's ID,
 a `UniqueOptions` object (`{ ignoreId }`) for clarity. A fourth argument
 overrides the error message.
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 email: r.string().email().unique("users", "email");
 
@@ -403,7 +403,7 @@ email: r.string().email().unique("users", "email", { ignoreId: userId });
 
 ### exists — value must exist in the DB
 
-```typescript
+```typescript fragment
 // in a rules() method or factory
 userId: r.number().exists("users", "id");
 roleSlug: r.string().exists("roles", "slug");
@@ -450,7 +450,7 @@ back to the previous page.
 Errors and old input are stored in the [session](/docs/session) under the keys
 `'errors'` and `'old'`. Read them on the next request:
 
-```typescript
+```typescript fragment
 // in a controller
 const errors = ctx.flashed<Record<string, string[]>>("errors");
 const old = ctx.flashed<Record<string, unknown>>("old");
@@ -500,7 +500,7 @@ would not.
 **A `FormRequest` fails the HTTP request**, so test it through the route it
 guards. The status tells you which failure mode you got:
 
-```typescript
+```typescript fragment
 // tests/http/register.test.ts
 const res = await app.post("/register", { email: "not-an-email" });
 

package/docs/view.md

@@ -67,7 +67,7 @@ use the [`safe()` helper or `Raw` component](#embedding-raw-html).
 
 The runtime renders attributes from props with a few rules:
 
-```tsx
+```tsx fragment
 // in a component
 <input type="text" value={name} disabled={isLocked} required={false} data-id={42} />
 // → <input type="text" value="…" disabled data-id="42">
@@ -97,7 +97,7 @@ Children are rendered by type, which is the engine's security boundary:
 
 Two consequences worth remembering:
 
-```tsx
+```tsx fragment
 // in a component
 {
   user && <Welcome name={user.name} />;
@@ -123,7 +123,7 @@ Call `view()` from a controller action to set the response. It accepts any value
 whose `.toString()` returns HTML — a `SafeHtml` instance from JSX is the normal
 case:
 
-```tsx
+```tsx fragment
 // app/controllers/PostController.tsx
 import { view } from "zerotal";
 import type { HttpContext } from "zerotal";
@@ -159,7 +159,7 @@ export default function Welcome(ctx: HttpContext, { title }: { title: string })
 }
 ```
 
-```ts
+```ts fragment
 // routes/index.ts — the HttpContext is injected; you only pass the extra props
 import { Router } from "zerotal";
 import Welcome from "../resources/views/Welcome.tsx";
@@ -213,7 +213,7 @@ export function AppLayout({ title, children }: AppLayoutProps) {
 }
 ```
 
-```tsx
+```tsx fragment
 // resources/views/About.tsx
 import { defineLayout } from "zerotal/view";
 import { AppLayout } from "./layouts/AppLayout.tsx";
@@ -229,7 +229,7 @@ export const AboutPage = wrap<{ heading: string }>(({ heading }) => (
 ));
 ```
 
-```ts
+```ts fragment
 // routes/index.ts
 import { Router } from "zerotal";
 import { AboutPage } from "../resources/views/About.tsx";
@@ -246,7 +246,7 @@ directly with `Router.view()`. The third argument is the props — a **static
 object**, or a **per-request factory** that receives the `HttpContext` and may be
 async:
 
-```ts
+```ts fragment
 // routes/index.ts
 // Static props — evaluated once at registration (marketing / info pages):
 Router.view("/about", AboutPage, { title: "About Us" });
@@ -263,7 +263,7 @@ Router.view("/privacy", PrivacyPage);
 
 The returned registration is chainable:
 
-```ts
+```ts fragment
 // routes/index.ts
 Router.view("/terms", TermsPage)
   .name("terms") // name the route for url() generation
@@ -276,7 +276,7 @@ Under [file-based routing](/docs/routing), a page file's **default export**
 becomes a `GET` route automatically. The page is a function of `(http, params)`
 and may be async:
 
-```tsx
+```tsx fragment
 // app/views/posts/[slug].tsx  →  GET /posts/:slug
 import type { HttpContext } from "zerotal";
 import { Post } from "../../models/Post.ts";
@@ -311,7 +311,7 @@ export default definePage((http, params) => `<h1>Hello ${params.name}</h1>`);
 When you have pre-rendered markup (e.g. from a Markdown renderer) use `safe()` or
 `<Raw>` to bypass escaping:
 
-```tsx
+```tsx fragment
 // in a component
 import { safe, Raw } from "zerotal/view";
 
@@ -335,7 +335,7 @@ import { safe, Raw } from "zerotal/view";
 `esc()` escapes a value for use in raw string templates, where automatic JSX
 escaping isn't available:
 
-```ts
+```ts fragment
 // in a helper
 import { esc } from "zerotal/view";
 
@@ -367,7 +367,7 @@ function returning a node that stringifies, so most of it tests without a server
 **Render the component and assert on the string.** No request, no router, no
 browser:
 
-```typescript
+```typescript fragment
 // tests/views/PostCard.test.ts
 import { test, expect } from "bun:test";
 import { PostCard } from "../../resources/views/PostCard.tsx";
@@ -383,7 +383,7 @@ test("renders the title and author", () => {
 **Escaping is the test that matters.** Every view that renders user input has one
 job beyond looking right, and it is the job that becomes a security incident:
 
-```typescript
+```typescript fragment
 // tests/views/PostCard.test.ts
 test("escapes markup in user-supplied text", () => {
   const html = String(PostCard({ post: { title: "<script>alert(1)</script>" } }));
@@ -400,7 +400,7 @@ fails if someone later routes user input into it.
 **Through a route, assert the rendered text** rather than the markup around it.
 `assertSee` survives a class rename; a full-HTML comparison does not:
 
-```typescript
+```typescript fragment
 // tests/http/posts.test.ts
 const res = await app.get("/posts");
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.7.4",
+  "version": "1.8.0",
   "license": "MIT",
-  "maturity": "beta",
+  "maturity": "stable",
   "private": false,
   "type": "module",
   "main": "./src/index.ts",
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.7.4"
+    "@zerotal/core": "1.8.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.7.4"
+    "@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/index.ts

@@ -27,7 +27,15 @@ export * from "./errors.ts";
 // serve a subset, or add its own alongside them.
 export { archTools, vendoredDocsDir } from "./tools/index.ts";
 export type { ToolContext } from "./tools/index.ts";
+// Subprocess plumbing, not API. `_probe.ts` carries the underscore this repo uses
+// for a module nobody outside its package should reach for, nothing in the tree
+// imports these from here, and the export block above says why the tools and the
+// probe topics are public without ever saying why these are. Marked before the
+// stable promise attaches, because withdrawing them afterwards is a breaking
+// change made on behalf of a caller that does not exist.
+/** @internal */
 export { findApp, spawnProbe } from "./tools/_probe.ts";
+/** @internal */
 export type { ProbeResult, ProbeRunner, SpawnProbeOptions } from "./tools/_probe.ts";
 
 // The in-app reads, for anyone wanting them without the subprocess.
@@ -45,12 +53,28 @@ export type {
   SchemaReport,
 } from "./probe/topics.ts";
 
-// The install writers, so a project can generate the same files its own way.
+// The writers behind `arch:install`. Exported for the command and its tests to
+// reach, not as API.
+//
+// They were public on the reasoning that "a project can generate the same files
+// its own way" — a use nobody has, and a promise about the shape of `.mcp.json`
+// writing, agent detection and marker fencing that would hold for the rest of
+// the 1.x line. `ArchInstallCommand` is the only caller in the tree. Under `beta`
+// that was a cheap bet; the stable label is what makes it expensive, so they are
+// marked now rather than withdrawn later on behalf of a caller who never arrived.
+/** @internal */
 export { detectAgents } from "./install/detect.ts";
+/** @internal */
 export type { Detected, McpTarget } from "./install/detect.ts";
+/** @internal */
 export { applyMcpConfig, serverEntry, SERVER_ENTRY_PATH } from "./install/mcpConfig.ts";
+/** @internal */
 export type { ConfigOutcome } from "./install/mcpConfig.ts";
+/** @internal */
 export { applyBlock, fence, BLOCK_END, BLOCK_START } from "./install/markers.ts";
+/** @internal */
 export type { BlockOutcome } from "./install/markers.ts";
+/** @internal */
 export { agentsPreamble, buildGuidelines, claudeShim } from "./install/guidelines.ts";
+/** @internal */
 export type { GuidelineOptions } from "./install/guidelines.ts";

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"

package/src/install/guidelines.ts

@@ -11,6 +11,8 @@
  * would summarise are the ones those tools return in full.
  */
 
+import type { ProjectShape } from "./shape.ts";
+
 /** A block contributed by one installed package. */
 interface PackageBlock {
   /** The package that triggers it. */
@@ -144,6 +146,11 @@ export interface GuidelineOptions {
   packages: string[];
   /** The key the MCP server is registered under, so the text names it correctly. */
   serverName: string;
+  /**
+   * How this project is configured, from {@link detectShape}. Omitted, the block
+   * is what it always was — a function of the package list.
+   */
+  shape?: ProjectShape;
 }
 
 /**
@@ -191,6 +198,9 @@ export function buildGuidelines(options: GuidelineOptions): string {
     );
   }
 
+  const shape = options.shape ? shapeSection(options.shape) : "";
+  if (shape) sections.push("", shape);
+
   sections.push(rulesSection());
 
   return sections
@@ -258,6 +268,80 @@ function commandSection(): string {
   ].join("\n");
 }
 
+/**
+ * What this project is configured to be, where that changes what to write.
+ *
+ * The rest of this file describes the framework; this describes *this app*. The
+ * distinction matters because the framework's contracts are not uniform, and the
+ * places they differ are places where guessing wrong compiles cleanly and fails
+ * at runtime. An `EmailVerification` mixin needs a migration in one app and not
+ * in another, and the app that needed one lost 419 tests to a column that was
+ * never created.
+ *
+ * Only facts that change an instruction are emitted. "This app uses SQLite" is
+ * trivia; "migrations own the schema here, so a new column needs one" is a
+ * decision the agent would otherwise get wrong half the time.
+ */
+function shapeSection(shape: ProjectShape): string {
+  const lines: string[] = [];
+
+  if (shape.schemaSource === "migrations") {
+    lines.push(
+      "- **Migrations own the schema.** A new or changed column needs a migration — including " +
+        "columns a mixin registers imperatively, which are added to tables that already exist " +
+        "but never create one. Generate with `bun zt make:migration`, guard an added column " +
+        "with `Schema.hasColumn`, and never hand-edit a migration that has run.",
+    );
+  } else if (shape.schemaSource === "models") {
+    lines.push(
+      "- **The models own the schema** (`database.synchronize`). The table is built from what " +
+        "the models declare, so a `@column` is the whole change and there is no migration to " +
+        "write. Check `schema` after adding one to confirm it landed.",
+    );
+  } else if (shape.schemaSource === "both") {
+    lines.push(
+      "- **Both `database.synchronize` and migrations are present**, which is deliberate in " +
+        "some apps (sync locally, migrations in production) and a mistake in others. Run " +
+        "`doctor` and read what it says about the source of truth before adding a column — " +
+        "the answer decides whether a migration is required or would collide.",
+    );
+  }
+
+  if (shape.routeTypes) {
+    lines.push(
+      "- **Route names are typed.** `types/routes.generated.ts` exists, so `route()` is checked " +
+        "against it and a stale file turns a working call into a type error. Run " +
+        "`bun zt route:types` after any route change.",
+    );
+  }
+
+  if (shape.strict.exactOptionalPropertyTypes) {
+    lines.push(
+      "- **`exactOptionalPropertyTypes` is on.** `{ x: undefined }` is not assignable to " +
+        "`{ x?: T }`. Build optional properties conditionally — `...(v ? { x: v } : {})` — " +
+        "rather than assigning `undefined` and expecting the key to be treated as absent.",
+    );
+  }
+
+  if (shape.strict.noUncheckedIndexedAccess) {
+    lines.push(
+      "- **`noUncheckedIndexedAccess` is on.** Every index read is `T | undefined`. Narrow it; " +
+        "do not reach for `!` to silence it.",
+    );
+  }
+
+  if (shape.hasTests) {
+    lines.push(
+      "- **This app has tests.** Run `bun zt test` before calling a task done — `doctor` checks " +
+        "configuration, not behaviour, and only one of the two notices that a change broke " +
+        "something.",
+    );
+  }
+
+  if (lines.length === 0) return "";
+  return ["### How this app is set up", "", ...lines].join("\n");
+}
+
 function rulesSection(): string {
   return [
     "",