@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/docs/STARTERS.md

@@ -30,7 +30,9 @@ Neither path forks the runtime or needs a hosting account or database.
 ## Files and growth
 
 `urlcode.yaml` includes a function route file and a redirect file in a nested
-folder. A JavaScript function, HTTP assertions and optional Makefile are included.
+folder. A JavaScript function, HTTP assertions and optional Makefile are included,
+plus `.github/workflows/urlcode.yml`, which runs the [project checks action](CI.md)
+on every push and pull request once the project is on GitHub.
 See [organization](ORGANIZATION.md) for choosing your own layout. Defaults allow
 GET/HEAD and use redirect 302; add configuration only when changing behavior.
 
@@ -40,6 +42,24 @@ application files. Add pages, downloads, more functions and business-specific
 features to this same project. Update tests and the expected route count as it grows.
 See [readiness](READINESS.md) and [security](FUNCTION-SECURITY.md).
 
+To start an extended site instead, install the extension packages from npm
+(`npm install @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin`, published as
+`0.1.0-alpha.1` prereleases) in the directory you run from and pass their names: `urlcode init ../my-site --with
+auth,admin` writes the same starter under `my-site/app/`, merges each package's
+routes and declarations into it, and generates one `host.mjs` and README beside
+it. The contract each package fulfils is in [extensions](EXTENSIONS.md#scaffolding-with-init---with).
+
+Both paths carry an `AGENTS.md` for repository-aware assistants. `urlcode init`
+generates it from the installed runtime's capability catalog (the same source as
+`urlcode capabilities`), so it names only the handlers, policies and site keys
+that version implements, plus the exact `validate`, `test` and `audit` commands
+with the starter's route count. The committed copy in `starters/default` is
+regenerated from the same function and a test keeps the two identical. The file
+points at the agent skill the package ships at `skills/urlcode/SKILL.md`.
+Both paths also write `.mcp.json`, which registers the read-only `urlcode mcp`
+server for Claude Code and Codex (`--project app` for an extended site); it is
+never overwritten and carries no `--allow-authoring` ([tooling](TOOLING.md#registering-the-server)).
+
 `examples/assets` contains a larger runnable file/page/download demonstration:
 `make dev PROJECT=examples/assets`. It is an example, not a separate init choice.
 

package/docs/TOOLING.md

@@ -0,0 +1,291 @@
+# Tooling SDK and local MCP
+
+The tooling API consolidates authoring operations without starting a runtime:
+
+- `inspectProject(project, {origin?, target?, offset?, limit?})` loads and
+  semantically compiles the project and returns route metadata, revision hash and
+  target compatibility. Route pages default to 100 entries, maximum 1,000.
+  Compatibility contains global `compatible`, `requirementCount` and `issueCount`
+  plus a separate `issues` page. Both arrays use the same zero-based `offset`
+  and `limit`, independently: an issue page is indexed over all compatibility
+  issues, not filtered to the route page. Compatibility includes `hasMore` for
+  its issue page. Empty pages never imply compatibility; the verdict and counts
+  always cover the entire project. Full requirement arrays are omitted because
+  route entries already contain their capability names.
+- `validateProject(project, options)` returns the same compilation verdict and
+  compatibility verdict and global counts without route or issue pages.
+  `firstIssue` is the first issue across the whole project, or null; supplied
+  pagination settings do not change it. The low-level
+  `analyzeCompiledCapabilities` API still returns the complete report.
+  For unusually long route paths, request smaller pages to fit the MCP output
+  byte limit; page entry bounds do not override that transport limit.
+- `explainRoute(project, path, options)` selects the route for a path and
+  describes its effective behavior from the compiled IR: methods, handler (with
+  its destination, module and export, file, extension or link collection),
+  the middleware chain in order, validated inputs (parameters and the request
+  body policy), the policies in effect with each compiled policy's inventory,
+  extension requirements, the cache outcome (the policy strategy, an explicit
+  header, an asset declaration, or the `no-store` the runtime forces on
+  extension, proxy and conditional routes), binding names (never values),
+  egress origins, response headers, capabilities and per-target support. A miss
+  returns `matched: false` with the nearest route patterns. With `extensions`
+  (a host file's registrations) each extension requirement also reports whether
+  a provider is registered, whether its revision pin matches and whether the
+  requirement satisfies the provider's policy schema; nothing is activated.
+  `explainProject(project, options)` returns every route the same way.
+- `buildManifest(project, options)` returns the generated semantic manifest
+  described under [`urlcode manifest`](#explain-and-manifest).
+- `getCapabilities(target?)` describes local implementation support and separate
+  deployment evidence.
+- `getCapability(name)` returns one catalog entry: kind, summary, resolved schema
+  fragments, constraints, required operator grants, per-target support, refused
+  targets and the bundled recipes and cookbook routes that use it. Unknown names
+  throw a `ConfigError` listing the valid names.
+- `getSchemaFragment(path)` returns only the fragment of
+  `schemas/urlcode.schema.json` for a dotted path (`route`, `redirect`,
+  `policies.cache`, `site.sitemap`) with local `$ref`s inlined; `schemaPathNames()`
+  lists the accepted top-level names. Both read bundled package data only.
+- `previewImport(options)` and `previewExport(project, format, acknowledgment?)`
+  return conversion reports and candidate text, never writing files. Provider
+  semantic differences require the existing explicit acknowledgment and remain
+  non-lossless.
+- `listRecipes()` and `showRecipe(name)` expose the fixed bundled recipe catalog.
+- `inspectExtensions({project, hostFile?})` reports each operator-registered
+  extension's name, contract version, targets, credential headers, configuration
+  and policy JSON Schemas, whether the project declares it, whether its revision
+  pin matches and where routes mount or require it, plus the project's declared
+  names. With `hostFile` it executes that trusted operator module under the
+  `--host-file` rules (absolute path, outside the project) and releases it
+  afterwards; without one it lists declarations only. `describeExtensions(project,
+  registrations?)` produces the same report from registrations already in hand.
+  Neither activates an extension. See [EXTENSIONS.md](EXTENSIONS.md).
+- `buildContext(project, {target?, hostFile?, budget?})` returns the compact
+  project context an authoring agent needs before it writes anything (see
+  below); `renderContext` produces the YAML rendering and `estimateTokens`
+  the characters-per-token estimate the budget uses.
+
+## Project context
+
+`urlcode context [--project DIR] [--target T] [--host-file F] [--budget N]
+[--json] [--stats]` emits one deterministic YAML document (JSON with
+`--json`) derived only from the compiled project and the capability catalog,
+never from prose. It uses the same loader and semantic compiler as
+`inspectProject`: no binding values, guest execution, environment reads or
+network. Keys always appear in this order:
+
+- `urlcode` (package version) and `schema` (`"1"`).
+- `project`: entry file, route count, handlers used with counts, extensions
+  declared, policies in effect at the top level and the number of routes each
+  policy applies to, requested env and secret binding names, `dynamicLinks`,
+  `site` keys, and `files` (include, function and middleware paths). With
+  `--host-file`, `host` counts the operator module's extensions and plugins
+  without activating them.
+- `routes`: path, methods and handler per route, sorted by path.
+- `constraints`: a fixed list that holds for every project (no guest network,
+  no Node APIs, no regex routes, one handler per route, exact or `{param}`
+  path segments, subtree mounts only for static and extension routes, no YAML
+  interpolation, secrets by operator grant only), each with a value and a note.
+- `targets`: for each capability target (or the one `--target`), which of this
+  project's used features are supported, conditional, refused or unknown.
+- `commands`: the exact `validate`, `test`, `audit --expect-routes N` (N is
+  the compiled route count), `routes` and `capabilities` invocations.
+
+`--budget N` drops sections in a fixed order until the YAML rendering fits
+the estimate: per-route detail, then `targets`, then the constraint notes
+(keys and values stay), then `project.files`, then `commands`. The dropped
+sections are listed under `omitted`. The estimate is `ceil(characters / 4)`;
+there is no tokenizer dependency, so treat both numbers as approximate. A
+budget the smallest rendering cannot meet is an error rather than an
+overrun. `--stats` writes a JSON line to stderr comparing the estimated size
+of the shipped documentation (`docs/*.md` and `llms.txt`) with the emitted
+context, labeled `estimate: characters/4`. The MCP tool `get_context` takes
+`target` and `budget` and returns the same object with `--project .` in the
+commands; it never takes a host file or any other path.
+
+Inspection reads declared configuration and function source graphs to validate
+references and compute revision hashes. It compiles route and policy semantics
+using dummy binding values. It never reads environment or dotenv credentials,
+starts guest execution, follows network destinations, or opens operator link
+stores. The result contains no raw compiled route, binding values or source text.
+Inspection is not deployment readiness: missing operator grants, live service
+availability, asset snapshot activation and provider behavior require their own
+checks. Build output remains an explicit separate build API/CLI operation.
+
+The package root also exports existing operator-invoked workflow APIs:
+`buildCloudflare(project, options)` compiles and writes a Cloudflare artifact;
+`runProjectTests(project, options)` starts the local runtime, executes request
+fixtures and closes it; `scaffoldProject(project, {dryRun})` creates missing
+placeholders while preserving existing files; `initProject(destination)` creates
+the standard starter; and `addRedirect(project, destination, alias?)` updates
+project YAML under the authoring lock. `CloudflareBuildOptions`,
+`CloudflareBuildReport`, `ProjectTestOptions`, `ProjectTestResult`, `ScaffoldReport`
+and `ScaffoldUnresolved` describe these existing operations.
+
+These SDK functions have explicit write or execution effects and are available
+to trusted callers only. Project tests use normal runtime activation, grants and
+sandboxing; granted proxy/signal fixtures can perform real outbound operations.
+Compilation and authoring write caller-selected destinations under each existing
+helper's documented rules. They are **not** MCP tools. MCP remains limited to
+the read-only operations below; adding a package-root export does not grant an
+assistant file-write, guest-execution, deployment or network authority.
+
+## Explain and manifest
+
+`urlcode explain [/route] [--project DIR] [--target T] [--host-file F] [--json]`
+prints what `explainRoute` returns: one route in detail, or without a path a
+one-line-per-route table (methods, handler, state, middleware count, policies,
+cache outcome and target support). `--target` narrows the support columns to
+one deployment target; `--host-file` supplies the operator registry so
+extension requirements show their provider. An unknown route exits 1 and names
+the nearest patterns. Everything comes from the compiled configuration: no
+request is evaluated, no function runs and no binding is read.
+
+`urlcode manifest [--project DIR] [--json]` emits the semantic manifest:
+`schemaVersion`, the `urlcode` version, the entry file and its includes, the
+`revision` (the same digest `inspectExtensionRevision` returns, so an operator
+pin can be checked against it), the config `configVersion`, every route (path,
+methods, handler, state, middleware, inputs, policy names, extension
+requirements, cache outcome, binding names, egress origins, capabilities and
+per-target support), the union of capabilities used, extension declarations
+(version, configuration keys, mounts and protected routes), recipe provenance
+(from a `recipe.yaml` beside the entry file when one exists), external
+requirements (environment and secret names, proxy and signal origins,
+extensions, link-store collections, dynamic links), the function and middleware
+modules with the routes that use them, and per-target compatibility. Without
+`--json` a short summary prints. The manifest is deterministic: the same
+project produces the same bytes. `urlcode build` writes the same document as
+`manifest.json` beside its output, and `buildManifest` returns it from the SDK.
+It is generated output, never a checked-in source of truth; regenerate it
+rather than editing it.
+
+`serveMcp({project, input?, output?, origin?, allowAuthoring?, hostFile?})` serves one
+operator-selected root on stdio. Its tools are `inspect`, `validate`,
+`capabilities`, `get_capability`, `get_schema`, `explain`, `get_manifest`,
+`import_preview`, `export_preview`, `recipes_list`, `recipes_show`,
+`search_recipes`, `search_examples` and `get_context`. When the operator starts
+the server with `--host-file`, it loads that trusted module once for the session
+and additionally advertises `get_extensions`, which returns the
+`inspectExtensions` report; without the option the tool is absent and calls to
+it are rejected. Tools accept no project/file/output path argument; recipe names
+come from the fixed catalog, `get_capability` names from the capability catalog,
+`get_schema` paths from the bundled schema, and the two searches match bundled
+metadata locally (see [recipes](RECIPES.md)).
+There is no shell, arbitrary file read, remote fetch, binding access, write or
+route-execution tool without the explicit [authoring mode](#authoring-mode) flag. Configuration includes and module references retain the
+runtime's existing root containment checks. Returned project and recipe content
+is data, not trusted instructions for the consuming agent.
+
+The server implements the MCP **2025-11-25** lifecycle and stdio framing. Clients
+initialize, verify the returned protocol version, then send
+`notifications/initialized` before tool operations. Other requested revisions
+negotiate to this explicit supported version; a client that cannot support it
+must disconnect. Newer lifecycle revisions are not claimed. Requests use UTF-8
+newline-delimited JSON-RPC 2.0, with one request at a time and stream backpressure.
+There is a 1 MiB input-frame and output-message limit; oversized input terminates
+the session after a fixed error, and truncated/invalid frames return protocol
+errors. Import text is additionally capped at 512 KiB. Tool schemas reject
+unknown arguments. Tool operation errors are generic to avoid exposing local
+source paths, credentials or configuration excerpts; inspect locally for details.
+
+## Registering the server
+
+`urlcode init` (and `init --with`) writes `.mcp.json` at the project root, the
+shape Claude Code and Codex read:
+
+```json
+{ "mcpServers": { "urlcode": { "command": "urlcode", "args": ["mcp", "--project", "."] } } }
+```
+
+For an `init --with` site the file sits beside `host.mjs` and passes
+`--project app`. An existing `.mcp.json` is never overwritten. The file registers
+the read-only server only: `--allow-authoring` (and `--host-file`) are operator
+choices added by hand, never by `init` or by an agent.
+
+- **Claude Code** reads `.mcp.json` in the project directory as a project-scoped
+  server and asks for approval on first use. Without a global install, replace
+  `"command": "urlcode"` with `"node"` and prefix the arguments with
+  `node_modules/@jimhoyd/urlcode/dist/cli.js`.
+- **Codex** reads the same `mcpServers` shape; alternatively register it in
+  `~/.codex/config.toml`:
+
+  ```toml
+  [mcp_servers.urlcode]
+  command = "urlcode"
+  args = ["mcp", "--project", "."]
+  ```
+- **Any stdio client** spawns `urlcode mcp --project DIR` with the project as the
+  working directory, speaks newline-delimited JSON-RPC 2.0 over stdin/stdout,
+  and follows the 2025-11-25 lifecycle described above. Nothing listens on a
+  port; closing stdin ends the session.
+
+The generated `AGENTS.md` and the packaged skill tell agents to prefer
+`get_context`, `get_capability`, `get_schema`, `search_recipes`, `explain` and
+`get_manifest` when the server is registered and to fall back to the matching
+CLI commands otherwise.
+
+## Authoring mode
+
+`urlcode mcp --allow-authoring --project DIR` adds six tools to the fourteen read
+tools above. The flag is honored from the operator's command line only: no
+tool argument, environment variable or client capability enables it, and
+without it the server is exactly the read-only server described above.
+
+What it can do, all inside the selected project root (resolved with realpath):
+
+- `create_route {path, handler, middleware?, file?}` adds one route to
+  `urlcode.yaml` or to an include listed in it. `handler` is a route object
+  (`{redirect: {...}}`, `{function: {...}}`, `{page: {...}}`, ...) or a short
+  form: an `http(s)://` URL becomes a redirect, a `.js`/`.mjs` path becomes a
+  function whose `{param}` path segments expand to required bounded string
+  parameters and matching `args`. `middleware` entries are sources or objects.
+  The merged project is checked before the write (schema, duplicate routes,
+  the `auth` short form, and the same reference compilation `urlcode add`
+  performs when every referenced source exists). The edit runs under the
+  authoring lock and replaces the file atomically. Missing sources are listed
+  in `missingSources` for `scaffold_feature`.
+- `add_recipe {name, destination, dryRun?}` runs `recipes add` into a new
+  directory under the project. The parent must exist; an existing destination
+  is refused, never merged. `dryRun` reports the destination and writes nothing.
+- `scaffold_feature {dryRun?}` runs `urlcode scaffold`: placeholder modules,
+  pages and directories for references the YAML makes and the disk lacks.
+  Existing files are preserved, never overwritten.
+- `run_validate`, `run_test`, `run_audit` spawn `urlcode validate --local`,
+  `urlcode test` and `urlcode audit` against the project with a minimal
+  environment (`PATH` only), a two-minute deadline and stdout/stderr each capped
+  at 32 KiB. The result carries `exitCode`, `signal`, `stdout`, `stderr` and
+  `truncated`. `run_test` activates the local runtime and executes fixtures,
+  under the same rules as the CLI.
+
+Every tool returns `validation`, the `validateProject` verdict of the project
+after the operation (or `valid: false` with a generic note; use `run_validate`
+for the CLI report).
+
+What it cannot do:
+
+- Write outside the project root. Paths are project-relative; absolute paths,
+  `..`, backslashes, drive letters, and any symlink on the walk are refused
+  before the write, and the recipe, scaffold and `urlcode add` paths keep their
+  own containment checks.
+- Touch `.env*`, anything under `.git`, `node_modules`, `package.json`,
+  credential files (`.pem`, `.key`, `.p12`, `.pfx`), the authoring lock, or
+  operator files by name: `*policy*.json`, `*compliance*`, `host.mjs` /
+  `host-file.mjs` and link stores (`.sqlite`, `.db` and their WAL/SHM files).
+  Operator files belong outside the checkout in the first place.
+- Create or change grants, read bindings or secret values, deploy, build, run
+  arbitrary commands, delete or edit existing files (except the one YAML file a
+  `create_route` targets), or serve a project other than the one the operator
+  selected.
+
+Authoring mode is a local, unauthenticated stdio process for an operator who
+already trusts the assistant to edit this checkout. Review the resulting diff
+as you would any contributor's before running `serve` or deploying.
+
+Only tools are advertised. Resources, prompts, subscriptions, sampling,
+elicitation, HTTP transport, cancellation and durable tasks are not implemented.
+Closing stdin ends the session after the current bounded operation. Existing
+configuration-loader and semantic-compiler deadlines still apply. This local
+process is not an authenticated remote service or an independent security review.
+
+Protocol references: [MCP stdio transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports),
+[MCP lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle),
+and [MCP tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).

package/docs/TYPESCRIPT-AUTHORING.md

@@ -0,0 +1,67 @@
+# Build-time TypeScript guests
+
+TypeScript guest authoring is a separate build step. Serving still accepts only
+JavaScript ES modules and executes them exclusively in QuickJS/WebAssembly.
+The build never imports application modules into Node or runs application code.
+
+```sh
+urlcode recipes add typescript --out ./hello-source
+urlcode build-typescript --project ./hello-source --out ./hello-built --dry-run
+urlcode build-typescript --project ./hello-source --out ./hello-built
+urlcode validate --local --project ./hello-built
+urlcode serve --project ./hello-built
+```
+
+The SDK equivalent is
+`await buildTypeScriptProject(source, output, {dryRun: false})`. The report lists
+emitted modules and files and explicitly returns `typeChecked: false`.
+
+Point `function.source` or `middleware[].source` at a `.ts`, `.js` or `.mjs`
+module. Use explicit relative extensions in imports, such as
+`import {message} from './message.ts'`. The build emits `.ts` as `.js` and
+rewrites the runtime imports and YAML source references. Existing JavaScript
+modules are preserved. Output name collisions, including case-only collisions,
+are refused for portability. Source `.d.ts` entries are not executable modules.
+The runtime's existing handling of relative imports/re-exports applies to the
+emitted graph; unsupported re-export forms remain refused.
+
+The trusted pinned TypeScript compiler transpiles ES2022/ES modules with fixed
+settings. It does not read `tsconfig.json`, package scripts, plugins, compiler
+transformers, dependency packages, Node declarations or ambient environment
+files. It diagnoses syntax errors, but does **not** perform semantic type
+checking. Type-only relative imports are erased without reading their targets.
+Bare/npm imports (including static type-only imports), CommonJS import/export
+syntax, dynamic runtime imports, `import.meta`, import attributes and imports
+outside the project are refused. No import extension inference occurs.
+
+The source graph is limited to 128 modules, 1 MiB per source and 4 MiB aggregate.
+The emitted graph must pass the runtime's own source parser and byte limits
+before publication. This does not execute the modules or replace normal route,
+policy, binding or sandbox validation at activation. Unsupported host/browser
+APIs remain unavailable in QuickJS, even if TypeScript accepts their names.
+Run `urlcode validate --local` and project tests on the output.
+
+Includes are flattened into a duplicate-checked entry document. Only referenced
+modules, page/download assets, static trees, site favicon/llms files and the
+`tests/requests.json` fixtures (when present) are snapshotted. Unreferenced files, dotenv, hidden files, package manifests and
+credential extensions are not copied. An explicit reference to a forbidden file
+fails rather than silently excluding it. Asset limits are 16 MiB per file,
+64 MiB aggregate and 10,000 output files. Empty static directories are refused;
+add an asset before building. Paths have at most 32 segments and 1,024 characters;
+symlinked source files/directories and multiply linked files are refused.
+The input project and output parent must be stable and controlled by the caller
+while building; this is not a hardened service for concurrent hostile writers.
+
+Output must be a new directory whose parent already exists. Dependencies are
+written before an atomic rename publishes the complete entry YAML; existing
+outputs are never overwritten. Failed builds remove their newly created output.
+Dry-run still transpiles and validates an isolated temporary snapshot, then
+removes it; it never writes the requested output. Configuration parsing keeps
+the loader's worker limits; transpilation runs in the authoring process and is
+not a sandboxed multi-tenant compilation service.
+
+Create operator grants against the **built** configuration/code revision.
+Transpilation and flattened includes change the snapshot digest, so source
+project grants must not be reused. External capabilities remain denied without
+an exact revision-pinned operator policy. The build never resolves bindings or
+copies credentials; it preserves logical binding declarations only.

package/docs/TYPESCRIPT.md

@@ -16,7 +16,7 @@ beside them, and `dist/BUILD-MANIFEST.json` with a SHA-256 per emitted file.
 | Import | Runtime | Declarations |
 |---|---|---|
 | `urlcode` | `dist/index.js` | `dist/types/index.d.ts` |
-| `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
+| `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender`, `@jimhoyd/urlcode/extensions` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
 | `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
 | `@jimhoyd/urlcode/schema` | `schemas/urlcode.schema.json` | — |
 

package/docs/USABILITY-REVIEW.md

@@ -0,0 +1,123 @@
+# Usability review: URLCode against the tools people reach for instead
+
+Status: an honest assessment written 2026-09-18 against the source in the four
+repositories at that date. It is opinion grounded in the code and docs, not a
+benchmark. Its purpose is to name the friction a first-time user or an AI
+agent meets, compare it with what competing tools do, and rank the changes
+that would matter most. It does not change any contract by itself.
+
+## 1. Who the competitors are, by rung
+
+URLCode is not one product; it competes with a different tool on each rung
+of [the ladder](FRAMEWORK.md#the-ladder).
+
+| Rung | What people use today | Where URLCode is better | Where it is worse today |
+|---|---|---|---|
+| Redirects, responses | Netlify `_redirects`, Cloudflare `_redirects`/Rules, Vercel `vercel.json`, nginx | One portable file that validates before deploy, tests with fixtures, counts routes, converts from those formats and refuses lossy conversions | Those files are two columns; `urlcode.yaml` needs `version`, a route key and a handler object. Nobody needs a validator for ten redirects |
+| Pages, files | Any static host, Astro, Hugo | Same file, no build step, native ranges/ETags, `site` conventions | No content pipeline, no templating for pages outside the extension kit |
+| Functions, middleware | Cloudflare Workers, Vercel Functions, Hono, Express | Real isolation with a fresh heap per call; typed args from YAML; secrets only by revision-pinned grant; runs the same on a laptop | No `fetch`, no timers, no streaming, no npm packages in guests. Every framework above lets you call an API from a function; here you declare a `proxy` or stop |
+| Live links | Bitly, Dub, Short.io, a Postgres table | Records without reloads, versioned writes, private management API, no account system to run | Single host SQLite that needs a patched Node build; no dashboard until you install admin |
+| Accounts | Clerk, Auth0, Auth.js, Better Auth, Lucia, Supabase Auth, Devise | Everything is operator-owned and reviewable: no vendor, no callback URLs on someone else's dashboard, no per-MAU bill; passkeys, OIDC, TOTP, recovery and an account page in one package | Install is a reviewed-tarball ritual, a host file, a SHA-256 pin and a JSON-on-stdin bootstrap. Clerk is `npm i` and one env var. Better Auth is a config object and a CLI migration |
+| Administration | Django admin, Rails Administrate, Retool, Forest Admin, Supabase Studio | Built on the same service with two-person cases and audited reveal, which none of the generic admins give you | Only manages auth's entities; there is no way to expose the project's own data. Django admin is one line per model |
+| Full app in one place | Rails, Django, Laravel, Next.js + Clerk + Prisma, Supabase | The whole thing is declarative and portable; an agent can generate and validate it without a build; the trust boundary between generated code and the operator is explicit | Everything that is not a route, a function or an account is out of scope: no data model, no ORM, no forms for your own tables, no client bundle, no email templates for your app |
+
+The honest summary: URLCode wins on portability, validation, isolation and
+operator ownership, and loses on the first fifteen minutes and on anything
+that needs application data.
+
+## 2. The first fifteen minutes
+
+What a new person does today, compared with the fastest competitor at each
+step. Times are what the docs imply, not measurements.
+
+| Step | URLCode today | Fastest competitor | Gap |
+|---|---|---|---|
+| Install | `npm i -g @jimhoyd/urlcode` or brew or a checksum script; three channels documented at equal weight | `npx create-next-app` | Too many equal choices on the first screen. Pick one, put the rest in the install guide |
+| First project | `urlcode init` writes a function route, a redirect and fixtures | `wrangler init` | Equal |
+| First redirect | 5 lines of YAML for one redirect | 1 line in `_redirects` | Acceptable once, heavy for 200. `bulk-import` exists but a person starting small never learns it |
+| First function | Must know: `parameters` with `schema`, `args` with `from: path`, the Request/Response subset, that `fetch` is absent | Hono: `app.get('/x', c => c.json(...))` | The typed-args design is right but needs a two-line minimal form. Today the smallest function route is 10 lines |
+| Add accounts | Clone two private repos, build tarballs with `pack-sources.mjs --core --auth --ui --admin --core-revision SHA`, install four tarballs, `urlcode-auth init`, compute `inspectExtensionRevision`, paste the SHA into an env var, `bootstrap` with JSON on stdin, `serve --host-file --origin` | Clerk: `npm i @clerk/nextjs`, one env var, wrap the app | This is the largest gap in the framework. Most of it is a consequence of the packages being unpublished and of the revision pin, and it is the step the README leads with |
+| Add admin | `urlcode-admin init` writes everything | Django `admin.site.register(Model)` | Comparable once installed |
+| Deploy | Container, Node process, or an adapter that refuses functions, links and extensions | `vercel deploy` | The refusals are correct but the person learns them at deploy time. `urlcode capabilities` exists and is not in the quick start |
+
+## 3. What an AI agent meets
+
+The framework's claim is that an agent should build from a handful of
+redirects to a full application without rebuilding the core. Measured
+against that claim:
+
+- **Strong:** one JSON Schema, a generated field reference, fixtures the agent
+  must write, `validate`, `test` and `audit` that give exact failures with the
+  route named, an MCP server for read-only inspection, and a capability
+  matrix that lists what does not exist. Few frameworks tell an agent what it
+  cannot do. This is the right foundation.
+- **Weak:** the documentation was organized by feature history rather than by
+  task. Before this review, `llms.txt` listed 40 documents at equal weight,
+  three of them status logs, and the README opened with release history and
+  "unreleased source" caveats. An agent reading it spent its context on
+  provenance rather than on the shape of a project. The framework page and the
+  reorganized index in this change address that; the remaining cost is the
+  size of the reference documents themselves (the YAML guide, policies and
+  dynamic links are each over 400 lines).
+- **Missing:** an agent cannot yet discover the extension packages' YAML from
+  the core schema. `extensions.auth.config` is validated by auth's schema at
+  activation, but there is no way to ask the installed runtime "what config
+  does `auth` accept" without the host file. A `urlcode extensions --schema`
+  command that reads the host file and prints each extension's configuration
+  and policy schemas would close this, and would let `urlcode mcp` serve them.
+- **Missing:** no single command creates the whole layered project. Today it
+  is `urlcode init`, then `urlcode-auth init`, then `urlcode-admin init`, each
+  with its own directory conventions. One `urlcode init --with auth,admin`
+  that delegates to the installed extension packages' scaffolds would make
+  the ladder real for an agent.
+
+## 4. Ranked recommendations
+
+Ordered by how much each would change the experience per unit of work, and
+whether it touches a contract.
+
+1. **Publish the three extension packages** (even as `0.1.0-alpha` with the
+   caveats their status files carry). Every install step in section 2's
+   "add accounts" row except the revision pin existed because they were
+   unpublished. This was a decision, not code; the repositories already had
+   the release checks. No contract change. Done 2026-09-18: all three are on
+   npm as `0.1.0-alpha.1` (review still pending, issue 58).
+2. **`urlcode init --with auth,admin,ui`.** Delegate to each installed
+   package's existing scaffold; write one host file and one README. No contract
+   change; a CLI addition in core that calls into optional peers.
+3. **Print extension schemas.** `urlcode extensions --host-file … --json`
+   listing each registered extension's name, version, configuration schema and
+   policy schema, and expose it through `urlcode mcp`. No contract change.
+4. **A short form for the common function route.** Allow `function:
+   functions/hello.mjs` as a string with path parameters inferred as required
+   strings of bounded length, expanding to today's long form. This is a schema
+   addition (`version: "1"` stays valid) and the single largest cut in YAML
+   for first-time users and agents. Needs the usual generated-reference and
+   cookbook updates.
+5. **Lead the README with the ladder, not the release history.** Done in this
+   change; keep it that way. Move status caveats to the readiness register.
+6. **One install channel on the first screen.** npm first; brew, script and
+   container in the install guide.
+7. **Fold the `presentation`/`ui` split.** Auth and admin still render through
+   the primitives while the kit is the documented way to restyle. Finishing
+   kit adoption (already listed in the ui status file) removes the one place
+   where the framework's story and its code differ.
+8. **Later, and a real contract question:** application data. The thing every
+   competitor on the last rung has and URLCode does not is a place for the
+   project's own records with an admin view. The runtime already has one
+   bounded store (links) and one admin surface (auth's entities). Whether a
+   declared `collection` handler with operator-owned SQLite and an admin
+   registration belongs in the framework is the next spike worth writing.
+   Without it, "full-fledged application" means "site with accounts".
+
+## 5. What is fine and should stay
+
+- The operator host file. It is the reason the project can be untrusted and
+  portable at the same time; Clerk's convenience is bought with a vendor in
+  the loop. Keep the boundary, make the file generated.
+- The revision pin. It is unusual and it is what makes "an agent changed the
+  YAML" a reviewable event rather than a silent grant. Keep it, print it
+  loudly, and make `init` write it.
+- Refusing instead of degrading on every target. The failure names the route.
+- The capability matrix in the AI guide. Extend it to the extension packages
+  rather than softening it.