@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/docs/EGRESS.md

@@ -0,0 +1,125 @@
+# Bounded proxy and webhook transport
+
+Outbound requests use a host-owned HTTPS transport. Guests do not receive a fetch
+API. Project declarations express behavior; an external operator policy, pinned
+to the complete project revision, grants exact HTTPS origins separately to proxy
+and signal operations. A configured destination never grants its own authority.
+Binding injection uses existing explicitly granted secrets, resolved before the
+host transport receives a literal header value. Never log those values.
+
+The transport resolves the destination for each request, refuses any DNS response
+containing a nonpublic address, and pins its connection lookup to one validated
+answer. HTTPS certificate and hostname verification remain enabled. There is no
+connection pool, fallback address, redirect following, or automatic retry. Private,
+loopback, link-local, documentation, multicast, IPv4-mapped IPv6 and transition
+addresses are refused. IPv6 filtering is deliberately conservative: 2001::/16,
+2002::/16 and 3fff::/16 are refused along with addresses outside ordinary global
+unicast. Network-level egress controls remain useful defense in depth.
+
+Default limits per client are 16 simultaneous requests, five seconds including
+DNS, 1 MiB request and response bodies and 16 KiB headers. Excess concurrency is
+refused immediately. Requests use bounded buffering rather than streaming. Abort
+and shutdown destroy active HTTP requests; unresolved system DNS operations may
+finish in the background but cannot open a socket after cancellation. Those DNS
+operations retain a separate concurrency slot until they settle, so repeatedly
+timing out DNS cannot create an unbounded underlying lookup backlog. A shared
+64-operation DNS cap also spans all client instances and runtime reloads in the
+host Node isolate; closing a client does not release an unresolved DNS slot. Closing a
+client refuses future requests and drains its bounded outstanding promises.
+Errors carry only a fixed category, never a destination, request, header or secret.
+
+Proxy destinations have a literal HTTPS authority. Path placeholders are encoded
+as individual components; dot-segment values are refused. Query names and incoming
+and outgoing headers require explicit selection. Host, framing, hop-by-hop and
+proxy-authorization headers cannot be supplied. Ambient authorization, cookies,
+forwarding metadata (the entire `x-forwarded-*` family) and Set-Cookie cannot be selected. Explicit host-resolved
+Authorization injection is supported. Set-Cookie forwarding is deliberately
+unsupported because multiple cookie fields cannot safely be represented by the
+portable scalar header contract. Upstream redirects are returned as responses;
+Location is forwarded only if explicitly selected and is never fetched. Headers
+nominated by an incoming or upstream Connection field are removed even if selected.
+Header names are normalized to lowercase; array-valued upstream fields are omitted.
+An encoded request body requires explicitly selecting its Content-Encoding
+header; literal header injection cannot change or replace that coding. Bodies
+remain raw bytes, including content encoding; select Content-Encoding when
+forwarding compressed responses. No transparent decompression occurs.
+
+Webhook signals are best effort. The broker schedules work after the caller's
+synchronous emit operation, with eight concurrent deliveries by default and no
+queue. Saturation and closed brokers drop new events. Each event contains only
+version, declared route pattern, status and method: never the actual request URL,
+parameters, body, client identity, incoming headers or bindings. The webhook
+receives a POST with JSON. Only 2xx responses count as delivered; all other status
+codes and transport failures count as failed. Delivery order is unspecified,
+there are no retries or durability guarantees, and shutdown aborts outstanding
+work and awaits settlement. Counter snapshots report accepted, delivered, failed
+and dropped events without including destination data. Applications must not use
+these signals for guaranteed billing, audit retention or job execution.
+
+The transport is a new security-sensitive host bridge. Unit tests and CI are not
+an independent assessment or proof of hostile multi-tenant readiness. Public
+provider network deployments require separate operator-owned fixtures and evidence.
+
+## Project declarations and external grants
+
+```yaml
+version: "1"
+routes:
+  /items/{id}:
+    proxy:
+      url: https://api.example.com/items/{id}
+      query: [page]
+      requestHeaders: [accept]
+      responseHeaders: [content-type, content-encoding]
+      headers:
+        authorization: {secret: API_TOKEN}
+    parameters:
+      - {name: id, in: path, required: true, schema: {type: string}}
+    secrets:
+      API_TOKEN: {secret: UPSTREAM_AUTHORIZATION}
+    signals:
+      - url: https://hooks.example.com/events
+```
+
+An injected secret is the complete header value (for example an operator-provided
+Bearer value); interpolation and ambient credentials are not supported. Each
+proxy placeholder must name a declared string path parameter. Proxy routes refuse
+middleware in this initial implementation: middleware cannot safely authorize an
+already materialized upstream request. Use host request policies before egress.
+Proxy routes require cache disabled or `no-store`; explicit cache declarations
+cannot override this. Responses always remove CDN cache directives and receive
+`Cache-Control: no-store`. Compressed upstream bytes are refused if their
+Content-Encoding field was not explicitly selected; it cannot be overridden by
+route response headers.
+
+The external version-1 policy has the existing `projectSha256` and route grants:
+
+```json
+{"version":1,"projectSha256":"<reviewed revision hash>","routes":{"/items/{id}":{"secrets":["UPSTREAM_AUTHORIZATION"],"egress":{"proxy":["https://api.example.com"],"signals":["https://hooks.example.com"]}}}}
+```
+
+Use `permissions` to generate requested grants for review. Exact origin strings
+omit a trailing slash and the default 443 port. Nondefault ports are explicit.
+Proxy and signal purposes are independent even when they share an origin. Every
+route's grant is checked against the current revision before credentials, assets,
+workers or network clients are activated. Each runtime shares one bounded proxy
+client and one bounded signal client, with at most 64 origins per purpose.
+
+Signals emit when route execution and response policies produce a result,
+including guest middleware responses and returned error status codes. Thrown
+handler errors and host request-policy/plugin short circuits (including cache
+hits) do not emit. HEAD requests and generated readiness probes do not emit.
+The response never waits for webhook delivery. Counter events contain only
+accepted/delivered/failed/dropped outcomes and counts and are exposed through
+runtime metrics and the Prometheus `signals_total` series. A closed runtime stops
+new requests, aborts egress and drains bounded pending work. Client disconnects
+are not currently propagated into the runtime transport; the five-second deadline
+still applies. All non-self-hosted targets currently refuse proxy and signals.
+See the [executable example](../examples/egress/README.md).
+
+Revision hashes also include declared project policies, profiles and site
+configuration. Changing an inherited pre-egress restriction invalidates grants
+just like changing a route or function source. Projects with these declarations
+must regenerate and review their operator policy after upgrading to this hash
+coverage; an old grant is intentionally refused rather than silently retaining
+network authority under changed behavior.

package/docs/EXTENSIONS.md

@@ -0,0 +1,226 @@
+# Operator-installed extensions
+
+Extensions are trusted operator modules, separate from application WASM. Auth
+and admin implementations live in `urlcode-auth` and `urlcode-admin`; the runtime
+supplies only the generic integration contract. No project file can import a host
+extension or choose its npm package.
+
+A project declares versioned configuration and exclusive route mounts:
+
+```yaml
+version: "1"
+extensions:
+  auth:
+    version: "1"
+    config: {}
+routes:
+  /auth/*:
+    extension: auth
+    methods: [GET, HEAD, POST]
+  /private:
+    respond: {text: Private}
+    policies:
+      extensions:
+        auth: {signedIn: true}
+```
+
+## Protecting a route: the `auth` short form
+
+When the project declares `extensions.auth`, a route may say `auth` instead of
+spelling out `policies.extensions.auth`. This is the preferred way to protect a
+route:
+
+```yaml
+routes:
+  /account:
+    respond: {text: Account}
+    auth: {role: member}          # or `auth: true` for any signed-in principal
+  /docs:
+    respond: {text: Docs}
+    auth: {required: false}       # documents intent; emits no requirement
+```
+
+The compiler expands the short form before anything else reads the project:
+`auth: true` becomes `policies.extensions.auth: {}` and an object becomes the
+same object minus `required`. The long form stays the canonical representation,
+so `routes`, `audit` and `explain` show the expansion, the extension revision
+hash covers it, and the installed auth extension validates the expanded
+requirement with its own policy schema. The keys other than `required` are
+exactly that schema's keys (`role`, `permission`, `verified`,
+`freshWithinSeconds`, `onDeny`); the runtime adds nothing of its own. Loading
+fails, naming the route, when `auth` appears without an `extensions.auth`
+declaration, next to `policies.extensions.auth`, or next to
+`policies.extensions: false`.
+
+The same shape is reserved for the cache policy: a future `cache: {strategy,
+maxAge}` route key may expand to `policies.cache` in the same pass. It is not
+implemented; declare `policies.cache` today (see [policies](POLICIES.md)).
+
+The configuration and requirement objects above are validated by the installed
+extension's schemas. They are examples of extension-owned fields, not built-in
+authentication behavior. See the executable generic fixture in
+[examples/extensions](../examples/extensions). Included files can declare
+extensions; duplicate names fail rather than silently override one another.
+
+The operator passes `extensions: RuntimeExtension[]` to `createRuntime`,
+`startServer`, or the AWS/Vercel adapter. Types and
+`inspectExtensionRevision(project)` are exported from
+`@jimhoyd/urlcode/extensions`. Inspection does not grant access: review the
+project and place the exact returned SHA-256 in each registration's
+`projectSha256`. YAML extension configuration, policies and routes participate
+in the revision. Changing them requires an explicit operator reapproval.
+
+Registrations provide a name, contract version, target list, JSON configuration
+schema, optional policy schema and activation factory. Activation receives the
+canonical operator origin, target, revision and mount bases. Its instance handles
+bounded requests and, when used in policies, authorizes requests. Missing
+registrations, stale grants, invalid configuration and unsupported targets fail
+activation. Multiple mounts cannot overlap other declared routes.
+
+For extension-protected routes, agents/throttle run before authorization and
+cache access happens only after authorization. Extension routes and protected
+routes reject cache strategies other than no-store; every resulting response is
+forced to no-store after host response hooks. Compression is disabled on these
+responses.
+
+One exception exists for content-hashed assets. A registration may declare
+`immutableAssets: {prefix: '/static'}`, a normalized literal path under each
+of its mounts (no `.` or `..` segments, no trailing slash). The runtime then
+answers `Cache-Control: public, max-age=31536000, immutable` instead of
+no-store only when every condition holds: the request path lies under
+`<mount><prefix>/`, the method is GET or HEAD, the status is 200 or 304, the
+response carries exactly one strong ETag, sets no Set-Cookie, and does not
+vary on Cookie, Authorization or `*`. A stricter Cache-Control the extension
+set (no-store, no-cache, private or a shorter max-age) is preserved; other CDN
+cache headers are still stripped and compression stays disabled. Anything
+that fails a condition, including a cookie added by a later response hook,
+stays no-store. The extension owns the content-hashed filename: a file under
+the prefix must change its name when its bytes change, because clients never
+revalidate it. The prefix belongs to the operator registration, not to the
+pinned project revision. The runtime withholds Cookie and Authorization plus any declared
+credential headers from all application guest requests and mapped parameters.
+This does not isolate browser JavaScript running on the same origin: application
+HTML/JS on an authentication origin must be trusted by that site's operator.
+
+Cloudflare refuses extensions until its artifact format supports their execution.
+Node adapter conformance is not a live-provider deployment claim.
+
+## Discovering schemas
+
+Each registration carries the JSON Schemas that validate its `config` block and
+its per-route policy requirements. `urlcode extensions` prints them together with
+the project's own declarations so an author can see what a mount accepts:
+
+```sh
+urlcode extensions --project ./site --host-file /absolute/operator/host.mjs [--json]
+```
+
+For every registration in the host file it reports the name, contract version,
+targets, credential headers, configuration schema, policy schema (if any),
+whether the project declares it, whether its `projectSha256` matches the current
+revision, the routes that mount it and the routes whose policies require it.
+Declared names the host does not register are listed as unregistered. The command
+executes the trusted host module exactly as `validate` does, including its
+absolute-path and outside-project rules, and calls `close` afterwards; it never
+activates an extension and grants nothing. Without `--host-file` it lists only
+the names the project declares and notes that schemas need the host file.
+
+The same report is available as `inspectExtensions({project, hostFile?})` from
+the package root and, for assistants, as the MCP tool `get_extensions`, which the
+server advertises only when the operator started `urlcode mcp` with
+`--host-file`. No tool argument can name a host file. See [TOOLING.md](TOOLING.md).
+
+## CLI host binding
+
+Use an explicitly named operator ES module outside the application directory:
+
+```sh
+urlcode serve --project ./site --origin https://site.example \
+  --host-file /absolute/operator/host.mjs
+```
+
+The module default-exports `{extensions, plugins?, close?}`. It may import installed
+operator packages, open their stores and read operator secrets. `close` releases
+shared services when the CLI command finishes or the server shuts down. A runtime
+reload closes extension instances but does not close caller-owned services. Host
+modules are not watched or automatically rediscovered. Restart to update them.
+
+The same explicit option is supported by dev, validate, test, routes, audit,
+benchmark, extensions and mcp. These commands execute trusted host activation and may access its
+store; read-only project inspection commands never implicitly load a host file.
+Host-file paths must be absolute `.mjs`/`.js` files whose real path lies outside
+the project, including after symlink resolution. This is an operator-code trust
+boundary, not a JavaScript sandbox or an independent security review.
+
+## Scaffolding with `init --with`
+
+`urlcode init <directory> --with auth,admin` produces the layered site the
+[framework page](FRAMEWORK.md#the-composition-contract) describes in one
+command: the starter under `<directory>/app/`, one `host.mjs`, one `README.md`,
+and each extension's own operator files. Core never bundles or imports the
+extension packages at build time; at run time it resolves
+`@jimhoyd/urlcode-<name>` for each name with Node's package resolution from
+the invoking directory (so `npm install @jimhoyd/urlcode-auth` in that
+directory, from npm where the packages are published as `0.1.0-alpha.1`
+prereleases, is the normal path and what makes `--with auth` work), imports
+the package and calls its
+`scaffold` export with this request:
+
+```ts
+interface ScaffoldRequest {
+  directory: string;        // absolute site directory; result file paths are relative to it
+  project: string;          // absolute route project, <directory>/app (holds urlcode.yaml)
+  hostFile: string;         // absolute combined host module, <directory>/host.mjs
+  names: readonly string[]; // every name in --with order, including this one
+}
+interface ScaffoldFile { path: string; content: string | Uint8Array; mode?: number }
+interface ScaffoldResult {
+  name: string;                            // must equal the requested name
+  extensions: Record<string, unknown>;     // merged into the project's top-level extensions
+  routes: Record<string, unknown>;         // merged into app/routes/extensions.yaml
+  hostImports: string[]; hostSetup: string[]; hostEntries: string[]; hostClose?: string[];
+  files: ScaffoldFile[];                   // written relative to directory with their modes
+  readme: string; nextSteps: string[];     // README section and numbered steps
+  env?: Record<string, string>;            // environment variables the host reads
+}
+```
+
+`scaffold` writes nothing; it returns fragments and may generate key material
+in memory (core zeroes `Uint8Array` contents after writing or on failure). The
+types are exported from `@jimhoyd/urlcode` for packages that want to typecheck
+against them.
+
+Assembly rules, in `--with` order:
+
+- Every package is resolved and every `scaffold` is called before anything is
+  written. A name that is not installed refuses with the `npm install` command;
+  a package without a `scaffold` export refuses and names the package; an error
+  thrown by a `scaffold` (for example admin without auth in the same `--with`)
+  is reported as that package's refusal. No directory is left behind.
+- `extensions` fragments are declared in `app/urlcode.yaml`; `routes`
+  fragments are written to `app/routes/extensions.yaml`, appended to the
+  starter's `includes`, so the starter's own routes load first. A route or
+  extension key produced twice, or one the starter already declares, is refused
+  naming both sources.
+- `host.mjs` is all `hostImports`, then all `hostSetup` lines, then an
+  `extensions` array of every `hostEntries` item, then `close()` running the
+  `hostClose` statements in reverse `--with` order so later entries release
+  before what they built on. Setup lines share one module scope: admin's entry
+  references the `service`, `csrfKey` and `projectSha256` identifiers that
+  auth's setup defines, which is why `names` carries the full list.
+- `files` are created exclusively (`wx`) with their `mode` (default `0644`),
+  must stay inside the site directory and outside `app/`, and never pass
+  through a symlink. Nothing generated is ever overwritten; an existing
+  destination refuses like plain `init`.
+- `README.md` holds the starter's README as a section, then each result's
+  `readme` under `## Extension: <name>`, the merged numbered `nextSteps`, the
+  merged `env` table and the project revision. The command prints that
+  revision (`inspectExtensionRevision` of `app/`) with the instruction to
+  review the project and pin it explicitly; the host is generated to require
+  the pin, never to compute it.
+
+Serving the result is the usual explicit host binding:
+
+```sh
+urlcode validate --project app --host-file "$PWD/host.mjs" --origin https://site.example
+```

package/docs/FRAMEWORK.md

@@ -0,0 +1,182 @@
+# The URLCode framework
+
+One page for people and AI agents. It says what the four packages are, how a
+project grows from a handful of redirects into an application with accounts
+and an administration console, and which facts an agent must not guess. Every
+claim here is implemented in the linked repository; nothing is roadmap.
+
+## Four packages, one project shape
+
+| Package | Repository | What it adds | How a project declares it |
+|---|---|---|---|
+| `@jimhoyd/urlcode` | [urlcode](https://github.com/jimhoyd-com/urlcode) | The runtime: YAML routes, isolated functions and middleware, pages and assets, live short links, policies, site conventions, CLI, provider adapters, the extension contract | `urlcode.yaml` with `version: "1"` |
+| `@jimhoyd/urlcode-ui` | [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui) | Shared presentation: escaped templates, shadcn/ui partials, one stylesheet with light and dark, themes, translations, the `ui` extension that serves the kit's assets | `extensions.ui` plus an asset mount route |
+| `@jimhoyd/urlcode-auth` | [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth) | Accounts: password, passkeys, OpenID Connect, email codes, TOTP, recovery, sessions, roles, registration modes, account page, operator CLI | `extensions.auth` plus an `/account/*` mount and `policies.extensions.auth` on protected routes |
+| `@jimhoyd/urlcode-admin` | [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin) | Administration: users, sessions, roles, audit, registration approval, two-person cases, support impersonation, health | `extensions.admin` plus an `/admin/*` mount |
+
+The core is Apache-2.0 and released. The three extension packages are
+Apache-2.0 and published to npm as alphas (`@jimhoyd/urlcode-ui@0.1.0-alpha.1`,
+`@jimhoyd/urlcode-auth@0.1.0-alpha.1`, `@jimhoyd/urlcode-admin@0.1.0-alpha.1`,
+on core `0.4.0-alpha.1`). An alpha on npm is a distribution channel, not an
+endorsement: the source is complete, but independent review, deployment
+evidence and an accessibility assessment are still pending
+([issue 58](https://github.com/jimhoyd-com/urlcode/issues/58)). Their status
+files say exactly what is built: [auth](https://github.com/jimhoyd-com/urlcode-auth/blob/main/IMPLEMENTATION-STATUS.md),
+[admin](https://github.com/jimhoyd-com/urlcode-admin/blob/main/IMPLEMENTATION-STATUS.md),
+[ui](https://github.com/jimhoyd-com/urlcode-ui/blob/main/IMPLEMENTATION-STATUS.md).
+
+## The ladder
+
+A project climbs these rungs by adding YAML, never by rewriting what it has.
+Each rung's YAML is valid on every rung above it.
+
+1. **Redirects.** A `urlcode.yaml` with `redirect` routes. No code, no database,
+   runs anywhere, including Vercel, AWS Lambda and Cloudflare Workers.
+   Thousands of rows import from CSV or provider files with `bulk-import`.
+2. **Responses, pages and files.** `respond`, `page`, `static` and `download`
+   handlers, `site` conventions (robots, sitemap, favicon, security.txt,
+   llms.txt) and `policies` (throttle, agents, security headers, compression,
+   cache). Still no code.
+3. **Functions and middleware.** `function` routes and ordered `middleware`
+   in isolated JavaScript (QuickJS inside WebAssembly, fresh heap per call, no
+   Node, filesystem or network). Secrets reach a function only through an
+   operator grant pinned to the project revision.
+4. **Live short links.** A `link` route backed by an optional SQLite store,
+   with CLI and a private management API. Records change without reloads.
+5. **Accounts.** The `auth` extension: sign-in, registration, MFA, account
+   page and protected routes. The operator installs it in a host file outside
+   the project; YAML only declares the mount and configuration.
+6. **Administration.** The `admin` extension on the same service: manage the
+   people who signed up, their sessions and roles, review the audit trail.
+7. **Your own look.** A shared `presentation` (catalogue and theme variables)
+   restyles auth and admin together; the `ui` extension adds the template kit,
+   project copy, template and stylesheet overrides for kit-rendered pages.
+
+Rungs 1 to 4 need only the core package. Rungs 5 to 7 need the extension
+packages, installed from npm as `0.1.0-alpha.1` prereleases, and a Node host
+with a patched SQLite build; see each repository's README for the exact
+requirement.
+
+## The composition contract
+
+An extended project starts with the packages and one command:
+
+```sh
+npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin
+urlcode init my-site --with auth,admin
+```
+
+Installing from npm is the normal path; the extension repositories'
+`pack-sources.mjs` still builds local tarballs from a reviewed checkout for
+operators who install only source they have read. Three files make an extended
+project. Nothing else is discovered by convention.
+
+```
+site/
+  urlcode.yaml           the project: routes, extensions, policies (Git-owned, untrusted content)
+  functions/, public/    guest code and assets referenced from the YAML
+operator/
+  host.mjs               trusted operator code: default-exports { extensions, plugins?, close? }
+  operator-service.mjs   opens the auth store, keys and senders; imported by host.mjs
+  data/                  private: auth.sqlite, encryption key, CSRF key
+```
+
+The project declares logical extensions and exclusive mounts:
+
+```yaml
+version: "1"
+extensions:
+  ui:    { version: "1", config: { theme: { name: Acme, colors: { primary: "24 95% 53%" } } } }
+  auth:  { version: "1", config: { registration: "off" } }
+  admin: { version: "1", config: {} }
+routes:
+  /assets/ui/*: { extension: ui,    methods: [GET, HEAD] }
+  /account/*:   { extension: auth,  methods: [GET, HEAD, POST] }
+  /admin/*:     { extension: admin, methods: [GET, HEAD, POST] }
+  /private:
+    respond: { text: Signed in }
+    policies:
+      extensions:
+        auth: {}
+```
+
+The operator host wires the packages, once, in code the project cannot reach:
+
+```js
+import { createUiExtension } from '@jimhoyd/urlcode-ui/host';
+import { authExtension, createPresentation, englishCatalogue } from '@jimhoyd/urlcode-auth';
+import { adminExtension } from '@jimhoyd/urlcode-admin';
+import { service, csrfKey, projectSha256 } from './operator-service.mjs';
+
+const ui = createUiExtension({ projectSha256, projectRoot: '/absolute/site', sources: [englishCatalogue] });
+const presentation = createPresentation({ theme: { '--ui-accent': '#0645ad' } });
+export default {
+  extensions: [
+    ui.registration,
+    authExtension({ service, csrfKey, projectSha256, presentation }),
+    adminExtension({ service, csrfKey, projectSha256, authMount: '/account', presentation }),
+  ],
+  async close() { await service.close(); },
+};
+```
+
+Auth and admin pages currently render through the shared primitives and a
+`presentation` (catalogue and `--ui-*` theme variables). The `ui` extension
+serves the template kit and its assets for pages an extension renders through
+`ui.kit`; moving the auth and admin screens onto the kit is a listed remaining
+item in the ui repository, so today one `presentation` restyles them and the
+`ui` block is optional.
+
+```sh
+urlcode serve --project /absolute/site --host-file /absolute/operator/host.mjs --origin https://site.example
+```
+
+`urlcode init <dir> --with auth,admin` writes this layout in one step: it
+resolves each installed `@jimhoyd/urlcode-<name>` from the current directory,
+calls its `scaffold` export and merges the fragments into `app/urlcode.yaml`,
+one `host.mjs` and one `README.md`, refusing before writing anything when a
+package is missing or two fragments collide (the contract is documented under
+[scaffolding](EXTENSIONS.md#scaffolding-with-init---with)). `urlcode-auth init`
+and `urlcode-admin init` write the same layout for a single package; `urlcode-auth bootstrap` creates the first
+administrator from JSON on stdin. `inspectExtensionRevision(project)` prints
+the SHA-256 that `projectSha256` must carry; changing extension YAML, policies
+or mounts changes the revision and needs an explicit operator reapproval.
+
+## Rules an agent must follow
+
+These are the facts that keep generated projects valid. The full matrix is in
+[AI authoring](AI-AUTHORING.md); this is the short list.
+
+- **YAML never names code, packages, databases or credentials.** Extensions are
+  logical names; the host file chooses the implementation. There is no
+  `--extension` flag, no `import` in YAML, no interpolation.
+- **One handler per route.** `redirect`, `respond`, `page`, `static`, `download`,
+  `function`, `link`, `proxy`, `conditional` or `extension`, plus optional
+  `middleware`. Paths are exact or single-segment `{param}`; `/*` only on
+  `static` and `extension` mounts. No regex.
+- **Guest code is sandboxed.** Functions see a text/JSON `Request`/`Response`
+  subset, validated `args` and granted `env`. No `fetch`, Node, filesystem or
+  timers. Do not write code that needs them; declare a `proxy` or a binding.
+- **Authentication is host processing.** Do not build login forms, session
+  cookies or password checks in functions. Declare `policies.extensions.auth`
+  on the route; the runtime withholds `Cookie` and `Authorization` from guests.
+- **Everything is validated before it runs.** `urlcode validate --local`,
+  `urlcode test`, `urlcode audit --expect-routes N`. Unsupported features fail
+  with the route named; nothing degrades silently.
+- **Provider targets refuse what they cannot enforce.** Cloudflare runs
+  redirects and declared responses only. Serverless adapters refuse functions,
+  links, proxy, signals and extensions. Check
+  `urlcode capabilities --target NAME` before promising a deployment.
+- **Report evidence, not hope.** The commands above are the evidence. Local
+  tests are not deployment, soak or independent security review.
+
+## Where to read next
+
+| Need | Read |
+|---|---|
+| Write or change routes | [YAML guide](YAML-GUIDE.md), [field reference](YAML-REFERENCE.md), [cookbook](../examples/cookbook/README.md) |
+| Add accounts | [auth README](https://github.com/jimhoyd-com/urlcode-auth#readme), [auth security](https://github.com/jimhoyd-com/urlcode-auth/blob/main/SECURITY.md) |
+| Add administration | [admin README](https://github.com/jimhoyd-com/urlcode-admin#readme) |
+| Restyle every page | [ui README](https://github.com/jimhoyd-com/urlcode-ui#readme), [ui contract](https://github.com/jimhoyd-com/urlcode-ui/blob/main/CONTRACT.md) |
+| Write an extension | [extensions](EXTENSIONS.md), [extension model review](SPIKE-EXTENSION-MODEL.md) |
+| Run it | [operations](OPERATIONS.md), [install](INSTALL.md), [deployment checks](DEPLOYMENT-CHECKS.md) |

package/docs/INSTALL.md

@@ -14,26 +14,51 @@ everything except live links works on any supported build. See
 ## npm
 
 ```sh
-npm install --global urlcode
+npm install --global @jimhoyd/urlcode
 urlcode --help
 ```
 
-Project-local, which is what an application repository should normally pin:
+Project-local, which is what an application repository should normally pin.
+Which dependency list it belongs in depends on how the project uses URLCode:
 
 ```sh
-npm install --save-dev urlcode
+# Using URLCode as a tool: validate, test and build in CI, never imported by
+# the code that serves requests.
+npm install --save-dev @jimhoyd/urlcode
 npx urlcode validate
+
+# Embedding the runtime (see TYPESCRIPT.md): the application imports
+# @jimhoyd/urlcode at startup, so it must survive `npm ci --omit=dev`.
+npm install --save @jimhoyd/urlcode
 ```
 
+A devDependency is absent from a production install, so an application that
+imports `createRuntime`, `startServer`, `prerenderPages` or any other
+[embedding entry point](TYPESCRIPT.md) fails at startup on a missing module if it
+is installed with `--save-dev`. An application should also pin an **exact**
+version rather than a range: the compiled Cloudflare artifact format is tied to
+the runtime version that reads it.
+
 ## Homebrew
 
 ```sh
 brew tap jimhoyd-com/urlcode
+brew trust jimhoyd-com/urlcode
 brew install urlcode
 ```
 
+Homebrew refuses to load a formula from a third-party tap until you trust it,
+so without the middle line the install stops with `Refusing to load formula …
+from untrusted tap`. Trusting a tap means agreeing to run code from this
+repository, the same as with the install script; `brew trust --formula
+jimhoyd-com/urlcode/urlcode` limits it to this one formula.
+
 The tap's formula is generated from the published tarball for each release and
-attached to the GitHub release as `urlcode.rb`.
+attached to the GitHub release as `urlcode.rb`. Homebrew verifies the tarball's
+SHA-256 against the formula before installing.
+
+Verified on macOS (arm64) against the 0.3.0 tap: fetch verified, installed into
+`/opt/homebrew/Cellar/urlcode/0.3.0`.
 
 ## Install script
 
@@ -45,7 +70,7 @@ It downloads the release tarball, verifies its SHA-256 against the release's
 `SHA256SUMS`, and installs with npm. Options:
 
 ```sh
-curl -fsSL .../install.sh | sh -s -- --version 0.2.0 --prefix "$HOME/.local"
+curl -fsSL .../install.sh | sh -s -- --version 0.3.0 --prefix "$HOME/.local"
 ```
 
 `--prefix` avoids needing privileges for a global npm directory; add
@@ -54,8 +79,14 @@ for that moment: to inspect first, download it, read it, then run it.
 
 ## Container
 
+No image is published yet: the release job's GHCR step is gated behind the
+`PUBLISH_CONTAINER` repository variable and has not run, so there is nothing at
+`ghcr.io/jimhoyd-com/urlcode` to pull. Build it from a release checkout:
+
 ```sh
-docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD:/project:ro" ghcr.io/jimhoyd-com/urlcode:0.2.0 \
+git clone --branch v0.3.0 https://github.com/jimhoyd-com/urlcode.git
+docker build -t urlcode:0.3.0 urlcode
+docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD:/project:ro" urlcode:0.3.0 \
   serve --project /project --host 0.0.0.0
 ```
 
@@ -74,13 +105,20 @@ make dev
 A clone runs the TypeScript source directly (`node src/cli.ts`, Node 22.18+),
 with no build step; see [local development](LOCAL-DEVELOPMENT.md).
 
+Three Node versions appear around the project, and they are not a contradiction:
+the installed package runs on Node 22.13 or newer (`engines`), running the
+TypeScript source from a clone needs 22.18 or newer because it relies on Node's
+built-in type stripping, the release workflow's npm trusted publishing needs
+22.14 or newer, and the container image pins Node 26. Only the first number
+constrains a deployment of the published tarball.
+
 ## Verify what you installed
 
 Releases carry Sigstore provenance signed by the release workflow. Before
 trusting a downloaded artifact:
 
 ```sh
-gh attestation verify urlcode-0.2.0.tgz --repo jimhoyd-com/urlcode \
+gh attestation verify jimhoyd-urlcode-0.3.0.tgz --repo jimhoyd-com/urlcode \
   --signer-workflow jimhoyd-com/urlcode/.github/workflows/release.yml
 ```