@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/README.md

@@ -1,30 +1,89 @@
 # URLCode
 
-**A portable runtime for programmable URL behavior.** Define an application's
-public URL surface in YAML, add isolated JavaScript only where declarative
-handlers are not enough, and run the same project locally or on your own
-infrastructure. Your routes, source and data remain yours.
+**A portable runtime for programmable URL behavior, and the framework that grows
+from it.** Declare an application's public URL surface in YAML, add isolated
+JavaScript only where declarative handlers are not enough, and run the same
+project locally, in a container, on your own infrastructure or on a provider
+adapter. When the project gets serious, add accounts and an administration
+console as operator-installed extensions instead of building them again.
+**URL behavior as code.**
 
 [![Verify](https://github.com/jimhoyd-com/urlcode/actions/workflows/ci.yml/badge.svg)](https://github.com/jimhoyd-com/urlcode/actions/workflows/ci.yml)
 
-[Documentation](docs/README.md) · [Starter](https://github.com/jimhoyd-com/urlcode-template) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
+[Documentation](docs/README.md) · [The framework](docs/FRAMEWORK.md) · [For AI agents](llms.txt) · [Starter](https://github.com/jimhoyd-com/urlcode-template) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
+
+**Your AI should build your application, not your framework.** Coding agents
+rebuild the same routing, validation, middleware, policies and authentication
+plumbing on every project, and the person ends up owning the plumbing. URLCode
+represents those behaviors as a strict, portable YAML contract that both people
+and agents can read: the agent describes what, the runtime owns how, and
+generated code goes to the part that is actually the application. It is
+infrastructure for AI-built software, not a framework for building AI models.
+[Why](docs/PROJECT-DIRECTION.md#why-your-ai-should-build-your-application-not-your-framework) ·
+[next steps](docs/NEXT-STEPS.md).
+
+## What it is
+
+A project is a `urlcode.yaml` with `version: "1"`. Each route has exactly one
+handler: `redirect`, `respond`, `page`, `static`, `download`, `function`,
+`link`, `proxy`, `conditional` or an `extension` mount, with optional ordered
+`middleware`. The runtime validates the whole project before serving it,
+compiles it once, and refuses anything a target cannot enforce with the route
+named. Functions run in a QuickJS/WebAssembly sandbox with a fresh heap per
+call and no Node, filesystem or network; secrets reach them only through
+operator grants pinned to the project revision.
+
+URLCode is not a URL shortener: short links are one handler. It is not a
+general Node web framework: guest code cannot reach the host. It is not a
+provider configuration format: infrastructure settings stay out of route YAML.
+See [project direction](docs/PROJECT-DIRECTION.md).
+
+## The framework
+
+Four packages, one project shape. A project climbs from redirects to a full
+application by adding YAML; the operator wires trusted packages in one host
+file outside the project. The full map, the composition contract and the rules
+an AI agent must follow are in [the framework](docs/FRAMEWORK.md).
+
+| Package | Adds | Status |
+|---|---|---|
+| [urlcode](https://github.com/jimhoyd-com/urlcode) (this repository) | Runtime, CLI, policies, live links, provider adapters, extension contract | `0.4.0-alpha.1` (alpha) on top of the `0.3.0` release, Apache-2.0 |
+| [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui) | Shared presentation: escaped templates, shadcn/ui partials, themes, translations | `0.1.0-alpha.1` on npm, alpha: review pending |
+| [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth) | Accounts: password, passkeys, OIDC, email codes, TOTP, sessions, roles, account page | `0.1.0-alpha.1` on npm, alpha: review pending |
+| [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin) | Administration: users, sessions, roles, audit, approvals, cases, impersonation | `0.1.0-alpha.1` on npm, alpha: review pending |
 
-URLCode is not a URL shortener. Short links are one supported route type beside
-redirects, validated HTTP responses, isolated request functions, middleware,
-pages, static assets and downloads. It is also not a general Node web framework:
-the project format intentionally describes bounded behavior that a runtime can
-validate, inspect and eventually carry across hosting providers.
+```yaml
+version: "1"
+extensions:
+  auth:  { version: "1", config: { registration: "off" } }
+  admin: { version: "1", config: {} }
+routes:
+  /go:          { redirect: { url: https://example.com, status: 302 } }
+  /account/*:   { extension: auth,  methods: [GET, HEAD, POST] }
+  /admin/*:     { extension: admin, methods: [GET, HEAD, POST] }
+  /private:
+    respond: { text: Signed in }
+    policies: { extensions: { auth: {} } }
+```
 
-See [project direction](docs/PROJECT-DIRECTION.md) for the product boundary,
-the relationship to application projects and the license.
+The YAML names logical extensions; it never names packages, code, databases
+or credentials. `urlcode-auth init` writes the operator host, keys and a
+private data directory beside the project; `urlcode serve --host-file` loads
+it. Cross-repository acceptance is tracked in
+[issue 58](https://github.com/jimhoyd-com/urlcode/issues/58).
 
 ## Status
 
-`0.2.0` is the current local/self-hosted release of the implemented
-contract, following `0.1.0`, the first stable one. It includes redirects, parameters, JavaScript
-functions, middleware, live short-link storage, pages, static assets, downloads, starters, tests and process/container packaging. See the
-[implemented contract](docs/SPECIFICATION.md), [operations guide](docs/OPERATIONS.md)
-and [roadmap](ROADMAP.md) for limits and unfinished work.
+`0.4.0-alpha.1` is the current release of the extension contract and the
+agent tooling, on top of the `0.3.0` self-hosted release. It adds the
+extension contract, capabilities and provider conformance, strict redirect
+interchange, bulk import, recipes and search, TypeScript guest authoring,
+conditions, bounded proxy and signals, and the MCP read and authoring modes;
+use the schema and docs from the runtime revision you run.
+The [roadmap](ROADMAP.md) separates implemented from planned, and
+[release readiness](docs/RELEASE-READINESS.md) records what is proven and
+what is not: provider deployments, soak and independent security review
+remain open.
 
 Live-link storage uses separate bounded reader/writer pools. It requires a Node
 build containing a patched SQLite version — 3.51.3 or newer, 3.50.7, or 3.44.6 —
@@ -42,7 +101,9 @@ self-hosting are permitted under its terms.
 Start with the [YAML guide and recipe book](docs/YAML-GUIDE.md),
 [complete field reference](docs/YAML-REFERENCE.md), and
 [runnable 25-route cookbook](examples/cookbook/README.md). For AI-assisted
-authoring, use [the AI guide](docs/AI-AUTHORING.md) and [llms.txt](llms.txt).
+authoring, use [the AI guide](docs/AI-AUTHORING.md), the bundled agent skills
+([authoring](.claude/skills/urlcode-authoring/SKILL.md),
+[operations](.claude/skills/urlcode-operations/SKILL.md)) and [llms.txt](llms.txt).
 Follow [organization and readability practices](docs/BEST-PRACTICES.md) as your
 project grows. Operators should read [capacity/concurrency](docs/CAPACITY.md) and the
 [DDoS and recovery playbook](docs/RESILIENCE.md). Embedding the runtime from
@@ -94,249 +155,115 @@ Already wrote `urlcode.yaml`? Run `urlcode scaffold --project ./my-links --dry-r
 then remove `--dry-run` to create missing modules, pages and directories. Existing
 files are preserved; code placeholders return 501 until implemented.
 [Scaffolding guide](docs/SCAFFOLDING.md).
+Live-link storage and the auth extension need a Node build whose SQLite is
+3.51.3 or newer, 3.50.7 or 3.44.6. `urlcode doctor` reports `liveLinks`;
+everything else runs on any supported Node (22.13+ installed, 22.18+ to run
+the TypeScript source).
 
 ## Try it
 
-Requires Node.js 22.13+ and npm; CI targets Node 22, 24 and 26 on macOS, Linux and
-Windows.
-
 ```sh
-npm install --global urlcode        # or: brew tap jimhoyd-com/urlcode && brew install urlcode
+npm install --global @jimhoyd/urlcode     # or: brew tap jimhoyd-com/urlcode && brew install urlcode
 urlcode init my-urls && cd my-urls
 urlcode dev
 ```
 
-See [installation](docs/INSTALL.md) for the install script, the container image
-and verifying a release's signed provenance. To work from a clone instead:
-
-```sh
-git clone https://github.com/jimhoyd-com/urlcode.git
-cd urlcode
-make dev
-```
-
-`make dev` installs dependencies if needed and starts the included function/redirect demo.
-No global install, account, database, Docker or configuration step is required.
-A clone runs the TypeScript source directly (`node src/cli.ts`, which needs
-Node 22.18+); the installed package runs the built `dist/cli.js`.
-Without Make (including Windows), use:
-
-```sh
-npm ci
-npm run dev
-```
-
-Open `http://127.0.0.1:3000/hello/Ada` to run your custom function,
-`/go` for a regular redirect.
-Edit `starters/default/routes/` or `functions/hello.mjs` under
-that starter; valid changes reload automatically. Press Ctrl+C to stop.
-In another terminal, run `make test-project` or `npm run test:project`.
-
-To create your own independent project:
-
-```sh
-make init DEST=../my-links
-make dev PROJECT=../my-links PORT=3001
-# Without Make:
-npm run init -- ../my-links
-npm run dev -- --project ../my-links --port 3001
-```
-
-Choose either command pair; initialization refuses to overwrite existing work.
-[Starters](docs/STARTERS.md) are ordinary application files, independent of the
-runtime checkout. Own them in your own Git repository. Global `npm link` remains
-optional if you want the `urlcode` command everywhere. See
-[local development](docs/LOCAL-DEVELOPMENT.md) for commands and troubleshooting.
+Open `http://127.0.0.1:3000/hello/Ada` for the function route and `/go` for
+the redirect. Edit the YAML; valid changes reload. `urlcode test` runs the
+project's HTTP fixtures. The [install guide](docs/INSTALL.md) covers the
+checksum-verified script, project-local installs, the container image and
+signed provenance. To work from a clone: `git clone … && make dev`.
 
 ## A URL that runs your function
 
-A request to `/hello/Ada` runs your JavaScript and returns
-`{"message":"Hello, Ada!"}`. Put this in `urlcode.yaml`:
-
 ```yaml
 version: "1"
 routes:
   /hello/{name}:
     parameters:
-      - name: name
-        in: path
-        required: true
-        schema: {type: string, minLength: 1, maxLength: 80}
+      - { name: name, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 80 } }
     function:
       source: functions/hello.mjs
-      args:
-        name: {from: path, name: name}
+      args: { name: { from: path, name: name } }
     env:
-      GREETING: {value: Hello}
+      GREETING: { value: Hello }
 ```
 
-And in `functions/hello.mjs`:
-
 ```js
 export default function hello(request, { args, env }) {
   return Response.json({ message: `${env.GREETING}, ${args.name}!` });
 }
 ```
 
-Your function chooses the response: JSON, text, HTML, or a redirect via
-`Response.redirect("https://example.com", 302)`. The starter includes
-this runnable example. Functions run in an isolated sandbox; see its supported
-[API and security boundaries](docs/FUNCTION-SECURITY.md).
-
-## Reusable middleware
+Add `middleware: [{ source: middleware/headers.mjs }]` to wrap any handler with
+`await next()`. Fourteen ready-made middleware patterns ship in the cookbook
+and as `urlcode recipes add middleware`. See [functions and the sandbox](docs/FUNCTION-SECURITY.md)
+and [middleware](docs/MIDDLEWARE.md).
+
+## Everything else in YAML
+
+- **Pages, files, downloads:** `page`, `static`, `download` with MIME detection,
+  ETags, ranges and safety limits. [Assets](docs/ASSETS.md).
+- **Live short links:** a `link` route on an optional SQLite store; create,
+  update and delete without reloads through the CLI or the private management
+  API. [Dynamic links](docs/DYNAMIC-LINKS.md).
+- **HTTP:** methods, validated path/query/header inputs, body limits, response
+  headers and cookies. [HTTP](docs/HTTP.md).
+- **Policies and site conventions:** throttle, agents, security headers,
+  compression, cache; robots, sitemap, favicon, security.txt, llms.txt.
+  [Policies](docs/POLICIES.md), [site](docs/SITE.md).
+- **Conditions, proxy, signals:** exact predicates with disjoint cases; a bounded
+  HTTPS proxy and best-effort webhooks behind operator grants.
+  [Conditions](docs/CONDITIONS.md), [egress](docs/EGRESS.md).
+- **Organization:** `includes` across folders; strict CSV/JSON/YAML and
+  provider-file import; searchable recipes and examples. [Organization](docs/ORGANIZATION.md),
+  [interchange](docs/INTERCHANGE.md), [bulk](docs/BULK.md), [recipes](docs/RECIPES.md).
+- **Checks:** `validate`, `test`, `routes`, `audit --expect-routes`, `benchmark`,
+  `capabilities`, deployment verification and a GitHub Action.
+  [Readiness](docs/READINESS.md), [CI](docs/CI.md).
+
+## Deploy
+
+Self-hosted Node process or container first. `@jimhoyd/urlcode/vercel` and
+`@jimhoyd/urlcode/aws` serve declarative projects as native handlers;
+`urlcode build --target cloudflare` compiles redirects and declared responses
+into a Worker. Each target refuses at activation or build time what it cannot
+run, with the route named. None has been exercised on its provider yet; the
+adapters have local conformance tests only. [Operations](docs/OPERATIONS.md),
+[capabilities](docs/CAPABILITIES.md), [Vercel](docs/VERCEL.md), [AWS](docs/AWS.md),
+[Cloudflare](docs/CLOUDFLARE.md).
+
+## For AI agents
+
+[llms.txt](llms.txt) is the compact index; [the framework](docs/FRAMEWORK.md)
+is the map; [AI authoring](docs/AI-AUTHORING.md) is the contract with the
+capability matrix and a copyable task prompt. `urlcode mcp` exposes read-only
+inspection, validation and conversion previews over stdio, and
+`--allow-authoring` adds project-confined authoring tools
+([tooling](docs/TOOLING.md)).
 
-Add an ordered `middleware` list alongside any route handler:
-
-```yaml
-    middleware:
-      - source: middleware/headers.mjs
-```
-
-```js
-export default async function headers(request, context, next) {
-  const response = await next();
-  response.headers.set('x-example-middleware', 'active');
-  return response;
-}
-```
-
-Middleware can return a response early, share request-local `context.state`, or
-wrap the handler with `await next()`. It runs in the same isolated sandbox and
-under one deadline for the whole chain. The starter's function route includes
-this example. See [middleware semantics and limits](docs/MIDDLEWARE.md).
-
-## A URL that redirects
-
-```yaml
-version: "1"
-routes:
-  /go:
-    redirect:
-      url: https://example.com
-      status: 302
-```
-
-Ordinary redirects use an indexed lookup: no database, Lambda or per-route
-user function. Configuration is compiled at startup, not parsed per request.
-Literal paths win over parameterized routes; conflicting definitions fail validation.
-
-Custom functions are ES modules using a documented text/JSON `Request`/`Response`
-subset and validated context. See the
-[starter](starters/default/urlcode.yaml) and [function](starters/default/functions/hello.mjs).
-Functions are treated as untrusted and run inside a QuickJS/WebAssembly sandbox,
-with a fresh heap per invocation. No Node APIs, filesystem, shell, network or
-ambient environment is exposed. Independent worker deadlines bound execution.
-External env/secret bindings require route-scoped operator grants pinned to the
-project revision. See the [security model](docs/FUNCTION-SECURITY.md).
-
-## Pages, files and downloads
-
-Add these routes alongside your functions and redirects:
-
-```yaml
-  /about:
-    page:
-      file: public/about.html
-  /assets/*:
-    static:
-      directory: public/assets
-  /download:
-    download:
-      file: public/guide.txt
-      filename: urlcode-guide.txt
-```
-
-Create the referenced files first. MIME types are detected from file extensions;
-unknown types use `application/octet-stream`. Downloads set attachment headers.
-Optional `contentType` overrides detection. HEAD, ETags, conditional requests and
-single byte ranges are supported. Files are served natively without executing a
-function. See [asset configuration and safety limits](docs/ASSETS.md).
-
-## Organize routes across files
+## Documentation
 
-Keep everything in `urlcode.yaml`, or use its `includes` list to load files from
-folders you choose. The [public template](https://github.com/jimhoyd-com/urlcode-template)
-demonstrates a function file and a redirect file in a nested folder. All commands
-see one combined project. See [organization examples](docs/ORGANIZATION.md).
+Full documentation lives in
+[urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs). It is authored
+there directly, not generated from this repository, and it is where new guides,
+references and recipes belong.
 
-## Route matching and adding links
+`docs/` in this repository is contributor and maintainer material — local
+development, CI, the release process, reviews and the generated field
+reference. Reader-facing pages still under `docs/` are being migrated.
 
-Routes support exact paths and non-greedy single-segment parameters such as
-`/r/{code}`. Only static-file mounts support a trailing `/*`; regex routing is
-not supported. `dev` swaps validated configuration snapshots when YAML changes;
-`serve` requires restart/redeployment for YAML changes. Stored short links can
-now be created/updated/deleted live without reloads through the optional
-[dynamic-link handler and management API](docs/DYNAMIC-LINKS.md). See [matching, precedence and dynamic-link behavior](docs/ROUTING.md).
+## Built with URLCode
 
-## Create short links without restarting
+[urlcode-short](https://github.com/jimhoyd-com/urlcode-short), an
+account-free short-link demo with a shadcn/ui front end, and
+[urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs), a static
+documentation site rendered through sandboxed middleware at build time. Both are
+ordinary consumers of the public runtime; their retrospectives list what the
+runtime supplied and what they still had to build.
 
-```yaml
-  /r/{code}:
-    parameters:
-      - name: code
-        in: path
-        required: true
-        schema: {type: string, minLength: 1, maxLength: 128}
-    link:
-      collection: links
-      code: {from: path, name: code}
-```
+## License and contributing
 
-Keep this route in YAML; store individual codes outside Git. Bind an optional
-local SQLite store with `--link-store links=/absolute/links.sqlite`, then use
-`urlcode links create` or the separate authenticated management API. Successful
-record changes are visible without rewriting YAML or rebuilding the route table.
-Ordinary YAML routes still need no database. See [setup, API and limitations](docs/DYNAMIC-LINKS.md).
-
-## HTTP in YAML
-
-Configure methods and validated path/query/header inputs, request body size and
-media types, response headers, cookies, and declared text/JSON responses.
-See the [HTTP configuration reference](docs/HTTP.md) for supported fields and
-examples. Runtime framing and asset validators stay protected.
-
-## Check your links before release
-
-`urlcode routes` lists the configured routes. `urlcode audit --expect-routes 2`
-checks the count, generates native response checks and reports missing route/method
-coverage in your request fixtures. `urlcode benchmark --requests 1000 --concurrency 2`
-measures your local project without following external redirects. Each command
-accepts `--project`. See [readiness and release checks](docs/READINESS.md).
-
-## Commands available
-
-| Command | Purpose |
-|---|---|
-| `init <directory>` | Create an independent starter; refuse existing destinations |
-| `add <url> --alias <code>` | Validate and atomically add a redirect; generate a code if omitted |
-| `validate --local` | Validate config, references, bindings and function initialization; read `.env.local` |
-| `dev` | Local server, watched reload and `.env.local` |
-| `serve` | Fixed production process snapshot; environment injection, no dotenv loading |
-| `test` | Local HTTP assertions from `tests/requests.json`; never follow redirects |
-| `permissions` | Inspect requested bindings and project digest without executing code; grants nothing |
-| `doctor` | Report runtime/platform details and implemented provider scope |
-
-Use `--project <directory>` to select an app. Servers accept `--host`, `--port`
-and `--origin` (public URL origin for functions). Bind defaults to `127.0.0.1`.
-
-## Production direction
-
-The free runtime is meant to be useful and production-capable for people who
-operate it themselves. Current hardening includes strict YAML/schema checks,
-request/response limits, worker deadlines, bounded function concurrency, safe
-configuration replacement, graceful shutdown, health/readiness and structured
-logs without request content. It still needs broader deployment/soak validation
-and the remaining release features. Read [operations](docs/OPERATIONS.md) before
-exposing a server. [Benchmark instructions and measurements](docs/PERFORMANCE.md)
-are available; measurements are not capacity guarantees.
-
-Git owns definitions and code. Secrets stay in ignored `.env.local` for development
-or injected environment values for serving, accessible to functions only through
-an explicit operator policy. Vercel, AWS Lambda and Cloudflare Workers each have a
-target guide in [docs](docs/README.md); none has been deployed to its platform
-yet. Provider secret-store integration, CSV tools, templates/signals,
-Homebrew and richer monitoring are future work. Unsupported config fails rather
-than silently losing behavior. There is no required admin UI or database.
-
-See [contributing](CONTRIBUTING.md), [security](SECURITY.md), and the
-[roadmap](ROADMAP.md).
+Apache-2.0. Commercial use, modification, redistribution and self-hosting are
+permitted. See [contributing](CONTRIBUTING.md), [security](SECURITY.md),
+[governance](GOVERNANCE.md) and the [roadmap](ROADMAP.md).

package/ROADMAP.md

@@ -11,6 +11,89 @@ separate late phase. The stable 0.1 self-hosted release covers much of M0/M1 plu
 process/container packaging and benchmarks. Provider adapters and the remaining
 production-readiness gates remain open.
 
+## 0.4.0-alpha.1 — current alpha
+
+`0.4.0-alpha.1` is the first alpha of the extension contract and the agent
+tooling on top of the `0.3.0` self-hosted release. It carries: the
+revision-pinned extension contract, capabilities and provider conformance,
+strict redirect interchange, bulk import, recipes and search, TypeScript
+guests, conditions, bounded proxy and signals, MCP read and authoring modes,
+the `context`, `explain`, `manifest` and `schema` queries, short forms,
+route-level auth, `init --with`, the agent benchmark harness, `llms-full`,
+and the generated `AGENTS.md` and skill. It is an alpha: provider
+deployments, soak and independent security review remain open. The
+extension packages declare `@jimhoyd/urlcode >=0.4.0-alpha.1 <0.5.0` and
+are published after core.
+
+## Extensions: accounts, administration and presentation — implemented, unreleased
+
+The runtime now carries a generic, revision-pinned extension contract
+(`@jimhoyd/urlcode/extensions`, [extensions](docs/EXTENSIONS.md)): a project
+declares versioned `extensions.<name>` blocks, exclusive `extension` mounts and
+`policies.extensions` requirements; the operator supplies the implementations
+in a host file loaded with `--host-file`, outside the project. Guest requests
+never see `Cookie`, `Authorization` or declared credential headers. Cloudflare
+refuses extensions until its artifact format can run them.
+
+The implementations live in their own repositories, each with an
+implementation-status file that is the authoritative feature list:
+[urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth) (accounts, sessions,
+MFA, roles, account page, operator CLI), [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin)
+(users, sessions, roles, audit, approvals, cases, impersonation) and
+[urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui) (escaped templates,
+partials, themes, translations). All three are Apache-2.0 and published to
+npm as `0.1.0-alpha.1` while first-release acceptance is reviewed; see
+[issue 58](https://github.com/jimhoyd-com/urlcode/issues/58) for what remains:
+browser and device WebAuthn coverage, accessibility assessment, soak, backup
+and recovery drills on a deployment, live provider senders and independent
+security review. [The framework](docs/FRAMEWORK.md) describes how the four
+packages compose, and [next steps](docs/NEXT-STEPS.md) is the phased plan to
+close the remaining gaps.
+
+## Capability foundation — implemented, unreleased
+
+`urlcode capabilities [--target self-hosted|cloudflare|aws|vercel] [--json]`
+and the public capability API centralize target support for handlers, bindings
+and effective policies. Runtime activation and Cloudflare builds use the shared
+preflight; unknown targets fail closed and unsupported requirements identify the
+route and capability before resources or artifacts are created. The existing
+compiled route IR is documented, not replaced. Configuration-dependent and
+delegated behavior remain explicit; all provider deployments remain unverified.
+See [capabilities](docs/CAPABILITIES.md) and the
+[next-phase review and implementation status](docs/NEXT-PHASE-PLAN.md).
+
+## Portability and URL behavior — implemented, unreleased
+
+Strict redirect interchange supports CSV/JSON/YAML, Netlify and Cloudflare
+`_redirects`, a bounded Netlify TOML subset and Vercel redirects. Conversion
+reports refuse unsupported semantics; provider differences require explicit
+acknowledgment and are never called lossless. A synthetic conformance fixture
+and bounded HTTPS runner distinguish local adapter tests from observed
+provider deployments. Actual Cloudflare/AWS/Vercel deployment evidence remains
+pending; this does not complete M4.
+
+Exact query/header/cookie/origin/method conditions and disjoint conditional
+redirect/response cases run in the self-hosted, AWS and Vercel runtimes.
+Cloudflare refuses these until its compiler can preserve their semantics.
+Self-hosted proxy and webhook signals use explicit revision-pinned operator
+origin grants, connection-pinned public DNS and bounded transport. Signals
+have no durable delivery or retry guarantee. Other targets refuse proxy and
+signals. See [conditions](docs/CONDITIONS.md), [egress](docs/EGRESS.md),
+[interchange](docs/INTERCHANGE.md) and
+[provider verification](docs/PROVIDER-VERIFICATION.md).
+
+## Developer ecosystem — implemented, unreleased
+
+Bundled Git-owned recipes, safe bulk imports into route includes, build-time
+TypeScript guest transpilation, read-only inspection APIs and optional stdio
+MCP tooling are available. The runtime still executes only JavaScript inside
+QuickJS/WASM; TypeScript authoring does not add host execution. Bulk benchmarks
+successfully cover 1,000, 10,000 and 100,000 routes without relaxing parser
+limits. See [recipes](docs/RECIPES.md), [bulk evidence](docs/BULK.md),
+[TypeScript authoring](docs/TYPESCRIPT-AUTHORING.md) and
+[SDK/MCP](docs/TOOLING.md). These features do not supply durable signals,
+protected downloads, a remote marketplace or provider deployment proof.
+
 ## TypeScript source and shipped declarations — implemented, unreleased
 
 The runtime, scripts, tests and benchmarks are TypeScript under a strict
@@ -167,7 +250,7 @@ Implemented the page/static/download portion of M2: project-contained asset
 snapshots, automatic MIME types, attachment names, HEAD, cache validators and
 single byte ranges. Dedicated public directories, symlink/hardlink rejection and
 bounded memory are part of the contract. [Asset guide](docs/ASSETS.md).
-Bulk tools, templates and signals remain open; M2 is not complete.
+Bulk tools, recipes and best-effort signals were added in the unreleased next-phase work above; they were not part of alpha.3.
 
 ## Security correction — 0.1.0-alpha.2
 
@@ -190,7 +273,7 @@ CI and a non-root container build are included. See the [contract](docs/SPECIFIC
 and [operations guide](docs/OPERATIONS.md) for exact support and evidence limits.
 
 Still open in the early contract: host namespaces, stable identity beyond paths,
-TypeScript support, fuller parameter vocabulary and capability/artifact planning.
+fuller parameter vocabulary. Build-time TypeScript authoring and capability planning are now implemented in the unreleased work above.
 No claims of complete M0/M1 or stable production readiness. M2–M4 work continues
 in the order below; a few independently useful operational foundations shipped early.
 

package/SECURITY.md

@@ -16,6 +16,13 @@ execution platform. Authorized inputs/secrets can be exposed
 by code receiving them; grant the minimum required authority. Do not deploy
 older snapshots for untrusted functions; review and upgrade to the current revision.
 
+Declarative proxy and signal handlers run in a separate bounded host transport;
+they do not grant guest networking. They require per-route, per-purpose HTTPS
+origin grants pinned to the project revision. Every connection checks public
+addresses and pins DNS, refuses redirects, filters headers and limits resources.
+See [egress semantics and limitations](docs/EGRESS.md). Build-time TypeScript
+transpilation and read-only MCP do not execute project code in the host.
+
 ## Report a vulnerability privately
 
 Use [GitHub private vulnerability reporting](https://github.com/jimhoyd-com/urlcode/security/advisories/new).
@@ -36,5 +43,5 @@ Bind loopback by default; protect public deployments with HTTPS, rate limits,
 network controls and restricted operational endpoints. See [operations](docs/OPERATIONS.md).
 
 See the [internal security reviews](docs/SECURITY-AUDIT.md) — most recently
-2026-09-17 — for fixed findings and remaining gates. Use a current reviewed commit: the shared 0.2.0
+2026-09-17 — for fixed findings and remaining gates. Use a current reviewed commit: the shared 0.3.0
 version label alone does not identify which hardening patches are present.