@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.1

package/.claude/skills/urlcode-authoring/SKILL.md

@@ -26,17 +26,12 @@ Documentation, schema and runtime must come from the **same revision**. Read fro
 the project's installed runtime (`node_modules/@jimhoyd/urlcode/`) or the
 checkout you are working in — never from memory of another version.
 
-1. `docs/AI-AUTHORING.md` — the authoring contract and the **capability matrix**
-   of what is available versus unavailable. Read this first and in full.
-2. `schemas/urlcode.schema.json` — the exact accepted structure.
-3. `docs/YAML-REFERENCE.md` and `docs/SPECIFICATION.md` — every field, and the
-   implemented semantics, defaults and sandbox API.
-4. `docs/YAML-GUIDE.md` and `examples/cookbook/` — recipes and runnable files.
-5. `docs/ROUTING.md`, `docs/HTTP.md`, `docs/MIDDLEWARE.md`, `docs/ASSETS.md` —
-   matching precedence, methods, composition, MIME and ranges.
-6. `docs/FUNCTION-SECURITY.md` — the sandbox and operator binding policy.
-
-`llms.txt` at the repository root is a compact index of all of the above.
+Start with `urlcode context --project <dir> --budget 4000`, then retrieve the
+capability, schema fragment, recipe or example relevant to the change. Use the
+read-only MCP equivalents when available. `llms.txt` is the index; read the
+matching task guide from `docs/` when a query needs more explanation.
+`docs/SPECIFICATION.md` and `schemas/urlcode.schema.json` resolve contract
+questions. Archived plans are historical, not valid YAML guidance.
 
 ## Workflow
 
@@ -52,8 +47,8 @@ checkout you are working in — never from memory of another version.
 - Bind typed inputs through `args` or context. There is no `${...}`
   interpolation anywhere in the format.
 - Create every referenced module, page and asset **before** validating. All
-  paths resolve from the project root; functions and middleware use relative
-  ES-module imports only.
+  source paths resolve from the project root. Trusted modules can import Node built-ins and npm packages;
+  only `sandbox: true` modules are restricted to the relative snapshotted graph.
 - Write exact response fixtures for success and failure, covering every active
   method, middleware behavior, HEAD, and any range or cache semantics.
 - Follow `docs/BEST-PRACTICES.md` for layout and readability as the project grows.
@@ -69,14 +64,17 @@ mistakes that recur:
 - `function`/`middleware` routes run trusted and unsandboxed by default: full
   Node, npm, filesystem and `fetch` access, in-process, like any other project
   code. `sandbox: true` opts a route into isolation — reach for it when that
-  route's own code warrants it (untrusted input, an unreviewed contribution, a
-  particularly sensitive secret), not reflexively on every route. A
+  route's own code warrants it (unreviewed or third-party code, a secret whose
+  blast radius matters, complex logic), not reflexively on every route and
+  never merely because it handles request data -- that is untrusted in both
+  modes and must be validated either way. A
   `sandbox: true` route gets a text/JSON `Request`/`Response` sandbox only:
   **no** `fetch`, Node or npm APIs, filesystem, WebSocket, streaming or crypto
   API.
 - No global middleware, Express compatibility or automatic auth.
 - `policies` accepts only `throttle`, `agents`, `security`, `compression` and
-  `cache`, every key off unless declared; `hardened` is the only built-in
+  `cache`, plus registered extension requirements under `extensions`;
+  the built-in policies are off unless declared; `hardened` is the only built-in
   profile. Check the per-target table in `docs/POLICIES.md` before declaring
   one for a serverless or Cloudflare deployment — an unsupported policy refuses
   activation rather than degrading.
@@ -84,9 +82,9 @@ mistakes that recur:
   only and off unless declared; a declared route at the same path wins. Its
   generated routes count toward `--expect-routes`, and `site.sitemap` needs
   `--origin` on every command that activates the project.
-- There is no native `link` handler or `dynamicLinks` project flag. Stored
-  short links are moving to a future `urlcode-dynamic-link` extension package,
-  not yet published; report that as a gap, never invent a `link` field.
+- There is no native `link` handler or `dynamicLinks` project flag, and no
+  supported extension package provides one; report stored short links as a gap,
+  never invent a `link` field.
 - Infrastructure (proxy ranges, storage URLs, vendor rule identifiers) is an
   operator flag, never route YAML.
 

package/.claude/skills/urlcode-operations/SKILL.md

@@ -74,20 +74,20 @@ by the operator.
 
 ## Hard limits — report these as gaps, never invent around them
 
-- No provider adapters, automatic TLS/DNS, distributed rate limiting, metrics
-  exporters or durable event delivery are included; these remain the
-  operator's own infrastructure.
+- Provider adapters exist with different capability limits; query
+  `urlcode capabilities --target NAME`. Automatic TLS/DNS, distributed rate
+  limiting, metrics exporters and durable delivery require operator infrastructure.
 - No orchestration, traffic switching or automated rollback; recovery is an
   explicit snapshot reload from a known-good artifact.
 - `verify-deployment` has no infrastructure access, uses no credential,
   follows no redirect and offers no `--insecure`. It cannot check anything a
   read-only HTTP probe cannot observe.
-- Core has no durable store and no private management API of its own; stored
-  short links are moving to a future `urlcode-dynamic-link` extension
-  package, not yet published.
-- Sandbox concurrency, worker slots and execution deadlines are shared across
-  every programmable route in a snapshot; there is no per-route fairness or
-  reserved capacity, and awaiting a guest timer still occupies a slot.
+- Core has no durable store and no private management API of its own, and no
+  supported extension package provides stored short links.
+- Only `sandbox: true` routes share the sandbox worker slots and forced
+  execution deadlines. Trusted routes run in Node under HTTP admission limits;
+  their cooperative timeout cannot stop blocking JavaScript. A guest timer still
+  occupies a sandbox slot. Size both modes from `docs/CAPACITY.md`.
 - `throttle` and `agents` policy counters are per instance, not distributed;
   they are a second layer behind the edge, never a replacement for it.
 

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude plugins published from the URLCode repository.",
-    "version": "0.4.0-alpha.2"
+    "version": "0.4.1"
   },
   "plugins": [
     {

package/CONTRIBUTING.md

@@ -37,9 +37,11 @@ update docs when support changes. Do not claim a provider or OS is supported
 without a passing test run. Preserve portable behavior and useful self-hosting.
 
 Use synthetic data. Never commit secrets, customer URL collections or local
-environment files. Treat all application function code as untrusted. Never import it into Node or
-add an unsafe fallback. Capability grants must come from operator policy outside
-the project. Extend adversarial tests with every new guest/host bridge. See the
+environment files. Project function and middleware code runs trusted in Node by default. Preserve
+explicit `sandbox: true` isolation: never add a host-execution fallback for that
+mode. Binding grants come from operator policy outside the project and govern
+what URLCode injects, not ambient access by trusted code. Extend adversarial
+tests with every new sandbox guest/host bridge. See the
 [security model](docs/FUNCTION-SECURITY.md).
 
 ## Maintaining the starter
@@ -68,19 +70,19 @@ explicit in `docs/AI-AUTHORING.md`; never present future roadmap fields as valid
 
 ## Documentation
 
-Public documentation lives in
-[urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs) and is authored
-there. It is not generated from this repository and must not be mirrored into
-it. Write new guides, references and recipes as a pull request against
-urlcode-docs.
-
-`docs/` here is contributor and maintainer material: local development, CI,
-the release process, internal reviews, spikes, plans and the generated
-`YAML-REFERENCE.md`. Reader-facing pages still under `docs/` are being
-migrated to urlcode-docs; edit them in place and do not add new ones.
+Documentation lives in `docs/` in this repository. Write new guides,
+references and recipes here, alongside the contributor and maintainer material
+already there: local development, CI, the release process, internal reviews,
+spikes, plans and the generated `YAML-REFERENCE.md`.
 
 A behavior change that a reader depends on is not finished until the matching
-urlcode-docs pull request exists. Link the two so review can see both halves.
+page in `docs/` is updated. Put both in the **same** pull request so review can
+see both halves and neither can land alone.
+
+`urlcode-docs` was deleted on 2026-09-19. It held its own copy of most of these
+pages and had drifted from them; the content that was ahead has been brought
+across, and the repository was retired rather than reconciled page by page.
+Links to it no longer resolve.
 
 If you find a gap you cannot close, file it as an issue on the repository that
 owns the code rather than leaving it undocumented. Feature requests are wanted:
@@ -93,8 +95,10 @@ Work on a branch and open a focused pull request. Explain the problem, resulting
 behavior, validation and compatibility/security implications. Never include real
 credentials or customer data. Use the PR template and keep unrelated changes out.
 
-`main` requires a pull request, an up-to-date branch, the required Node/OS verification
-jobs, container verification, CodeQL results and resolved conversations. High/critical
+`main` requires a pull request, the `verify-complete` and `container` checks,
+CodeQL results and resolved conversations. The current ruleset does not require
+an up-to-date branch. The [development pipeline](docs/DEVELOPMENT-PIPELINE.md)
+describes the fast prose lane, full code lane and exact-commit release gate. High/critical
 security findings and error-level CodeQL alerts block merging. Force pushes and branch
 deletion are blocked; squash merging keeps a linear history. Administrators have
 no configured ruleset bypass. Automation cannot approve pull requests.

package/README.md

@@ -20,7 +20,7 @@ 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).
+[roadmap](ROADMAP.md).
 
 ## What it is
 
@@ -32,8 +32,10 @@ compiles it once, and refuses anything a target cannot enforce with the route
 named. Functions and middleware run trusted, in-process, with full Node
 access by default; a route opts into an isolated QuickJS/WebAssembly sandbox
 with a fresh heap per call and no Node, filesystem or network by declaring
-`sandbox: true`. Either way, secrets reach them only through operator grants
-pinned to the project revision.
+`sandbox: true`. Either way, the `env`/`secrets` the runtime *hands* a route
+come only from operator grants pinned to the project revision; grants govern
+that injected context, not the ambient Node environment a trusted, in-process
+module can reach on its own like any other code in the host.
 
 URLCode is not a URL shortener: stored short links are an operator-installed
 extension, not core's job. It is not a
@@ -53,20 +55,34 @@ 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, provider adapters, extension contract | `0.4.0-alpha.2` (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.5` 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.3` 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.3` on npm, alpha: review pending |
-| [urlcode-dynamic-link](https://github.com/jimhoyd-com/urlcode-dynamic-link) | Stored short links: the mount-based successor to core's removed `link` handler | `0.1.0-alpha.2` on npm, alpha: review pending |
-| [urlcode-middleware](https://github.com/jimhoyd-com/urlcode-middleware) | Per-route middleware through the extension seam, alongside core's native array | `0.1.0-alpha.2` on npm, alpha: review pending |
-| [urlcode-short](https://github.com/jimhoyd-com/urlcode-short) | A complete link shortener assembled from the packages above | `0.1.0-alpha.2` on npm, alpha: review pending |
-
-Every version in this table is the one published to npm under the `alpha`
-dist-tag, and they are released together in the order core → ui → auth →
-admin → dynamic-link/middleware → short. The authoritative cross-repository
-register, including each package's declared peer ranges and the rules that
-keep them consistent, is
-[docs/VERSION-ALIGNMENT.md](docs/VERSION-ALIGNMENT.md).
+| [urlcode](https://github.com/jimhoyd-com/urlcode) (this repository) | Runtime, CLI, policies, provider adapters, extension contract | `0.4.1` stable release target, Apache-2.0 |
+| [urlcode-ui](packages/ui) (in this repository) | Shared presentation: escaped templates, shadcn/ui partials, themes, translations | `0.4.1` stable release target; review pending |
+| [urlcode-auth](packages/auth) (in this repository) | Accounts: password, passkeys, OIDC, email codes, TOTP, sessions, roles, account page | `0.4.1` stable release target; review pending |
+| [urlcode-admin](packages/admin) (in this repository) | Administration: users, sessions, roles, audit, approvals, cases, impersonation | `0.4.1` stable release target; review pending |
+
+This release aligns all four packages at `0.4.1`, with publication to npm's
+`latest` channel in the order core → ui → auth → admin. The table describes
+the release target; confirm publication with `npm run release:status` before
+installing it. Matching numbers do not establish a permanent fixed-version
+policy. Peer ranges, channel rules and generated application pins are documented
+in [package and channel alignment](docs/VERSION-ALIGNMENT.md).
+
+`urlcode-dynamic-link` and `urlcode-short` were published once as
+`0.1.0-alpha.1` and have since been retired: both were unpublished from npm and
+their repositories deleted, and neither has a successor. Nothing supported
+provides stored short links today — a project that needs them owns that storage
+itself. Anything still pinned to `@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1`
+also has to deal with its exact declared peer `@jimhoyd/urlcode: 0.4.0-alpha.1`,
+which cannot be installed beside core `0.4.0-alpha.2` and never will be.
+
+`urlcode-middleware` was retired the same way on 2026-09-19 —
+`@jimhoyd/urlcode-middleware` was unpublished from npm at `0.1.0-alpha.2` and
+its repository deleted. Unlike the two above, its capability did not go away
+with it: **per-route middleware is native to core**, through the
+`middleware:` array documented in [docs/MIDDLEWARE.md](docs/MIDDLEWARE.md).
+The deleted package only ever offered the same behavior through the extension
+seam. A project using it moves its entries to the native array; there is no
+gap to report here.
 
 ```yaml
 version: "1"
@@ -90,8 +106,9 @@ it. Cross-repository acceptance is tracked in
 
 ## Status
 
-`0.4.0-alpha.2` is the current release of the extension contract and the
-agent tooling, on top of the `0.3.0` self-hosted release. `0.4.0-alpha.1`
+The `0.4.1` release line brings core, UI, auth and admin to matching stable
+versions. A stable version selects the npm `latest` channel; it does not close
+the review and deployment evidence gaps below. `0.4.0-alpha.1`
 added 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
@@ -106,10 +123,9 @@ The [roadmap](ROADMAP.md) separates implemented from planned, and
 what is not: provider deployments, soak and independent security review
 remain open.
 
-Stored short links have moved out of core into
-[urlcode-dynamic-link](https://github.com/jimhoyd-com/urlcode-dynamic-link)
-(mount-based, like `auth`/`admin`, published on npm); core no longer has a
-native `link` handler.
+Core has no native `link` handler. Stored short links moved out to a
+mount-based `urlcode-dynamic-link` extension, which has since been retired and
+unpublished; no supported package provides them.
 
 URLCode is free and open-source software licensed under the
 [Apache License 2.0](LICENSE). Commercial use, modification, redistribution and
@@ -128,6 +144,14 @@ project grows. Operators should read [capacity/concurrency](docs/CAPACITY.md) an
 [DDoS and recovery playbook](docs/RESILIENCE.md). Embedding the runtime from
 TypeScript is covered in [TypeScript](docs/TYPESCRIPT.md). [All documentation](docs/README.md).
 
+All of it lives in [`docs/`](docs/README.md) in this repository — guides,
+references and recipes alongside the contributor and maintainer material: local
+development, CI, the release process, reviews and the generated field
+reference. New pages belong here, in the same pull request as the change they
+describe. `urlcode-docs`, a private repository that served a documentation site
+from its own copy of these pages, is being retired; the content that was ahead
+of this repository has been brought across.
+
 ## Start your own project
 
 Use [urlcode-template](https://github.com/jimhoyd-com/urlcode-template) for a small
@@ -142,28 +166,6 @@ npm ci
 npm run dev
 ```
 
-## Built with URLCode
-
-[urlcode-short](https://github.com/jimhoyd-com/urlcode-short) is a
-standalone, account-free demo built on URLCode's public runtime. It predates
-this repository's removal of the native link-store API from core; its
-retrospective should be read alongside that change, not as current guidance.
-It combines short links that expire after one hour or less, QR downloads, and a
-shadcn/ui + Tailwind frontend. URLCode handles the page/assets and routing; the
-application adds anonymous creation, stored-link storage and its own limits.
-
-Read its [build retrospective](https://github.com/jimhoyd-com/urlcode-short/blob/main/docs/BUILD-RETROSPECTIVE.md)
-for what the runtime supplied, what the application still needed, and proposed
-improvements. The demo's license, hosting and production validation remain open;
-it does not change URLCode's Apache-2.0 license or guest isolation model.
-
-`urlcode-docs` demonstrates URLCode hosting a static documentation site with
-shadcn/ui and Tailwind: content authored directly in that repository, applying
-templates through its own sandbox-opted-in (`sandbox: true`) middleware during
-the build, served through native page/static/download routes. That repository
-is currently private, so it isn't publicly browsable yet. Hosting and a public
-domain are not yet selected; the original site-code license is pending.
-
 ## Start from YAML
 
 Already wrote `urlcode.yaml`? Run `urlcode scaffold --project ./my-links --dry-run`,
@@ -176,7 +178,8 @@ SQLite build requirement, unverified from this repository.
 ## Try it
 
 ```sh
-npm install --global @jimhoyd/urlcode     # or: brew tap jimhoyd-com/urlcode && brew install urlcode
+# After the 0.4.1 release has been published:
+npm install --global @jimhoyd/urlcode@0.4.1
 urlcode init my-urls && cd my-urls
 urlcode dev
 ```
@@ -254,26 +257,18 @@ inspection, validation and conversion previews over stdio, and
 `--allow-authoring` adds project-confined authoring tools
 ([tooling](docs/TOOLING.md)).
 
-## Documentation
-
-Full documentation is authored in a separate `urlcode-docs` repository, where
-new guides, references and recipes belong — but that repository is currently
-private, so its content isn't publicly browsable yet. Until it's made public,
-the practical reference is this README and [`docs/`](docs/README.md) in this
-repository.
-
-`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.
-
 ## Built with URLCode
 
-[urlcode-short](https://github.com/jimhoyd-com/urlcode-short), an
-account-free short-link demo with a shadcn/ui front end, and `urlcode-docs`, a
-static documentation site rendered through its own sandbox-opted-in middleware
-at build time (currently a private repository). Both are ordinary consumers of
-the public runtime; urlcode-short's retrospective lists what the runtime
-supplied and what it still had to build.
+Two applications were built on the public runtime as ordinary consumers, and
+both have since been retired: `urlcode-docs`, a static documentation site
+rendered through its own middleware at build time and served through native
+page/static/download routes, and `urlcode-short`, an account-free short-link
+demo combining expiring links, QR downloads and a shadcn/ui frontend — URLCode
+supplied the pages, assets and routing, the application supplied anonymous
+creation, link storage and its own limits. `urlcode-short`'s repository is
+deleted, so its build retrospective is no longer reachable; what it recorded
+about the gap between the runtime and a real application is carried in
+[principles and open decisions](docs/OPEN-DECISIONS.md) and [roadmap](ROADMAP.md).
 
 ## License and contributing