# Working on URLCode - Read CONTRIBUTING.md, SECURITY.md and the implemented specification before changes. - The project is Apache-2.0 licensed. Do not change licensing, add a CLA/DCO or publish packages without an explicit decision. The self-hosted release does not imply independent security assessment or hostile multi-tenant readiness. - Design principle: declarative-first (docs/PROJECT-DIRECTION.md). Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement. - Implementation-portability directive: implement the behavioral contract, not a TypeScript translation. When changing a major core semantic seam, update its card in docs/RUNTIME-IMPLEMENTATION.md, the authoritative semantic page and focused fixture. Keep implementation-agent instructions and source maps outside `src/`: type stripping preserves source comments in `dist/`. A runtime/target that cannot enforce a capability must refuse it before serving; trusted Node functions and `sandbox: true` are separate execution modes, not a cross-language guest-code promise. - Keep the free runtime useful and portable. Do not add provider infrastructure settings to route behavior YAML. - `function`/`middleware` routes are trusted and run unsandboxed (in-process, full Node access) by default; `sandbox: true` opts a route into the isolated QuickJS/WASM worker pool (docs/SPIKE-DEFAULT-TRUST-MODEL.md, docs/FUNCTION-SECURITY.md). Preserve that sandboxed path's isolation exactly as-is for any route that declares it, preserve explicit project capabilities and external revision-pinned grants, and never commit credentials/customer data. - Work on a branch and use a pull request. Main is protected: do not direct-push, force-push, weaken rules, bypass required checks or auto-approve reviews. Merge only within user authorization and after required checks pass. - The runtime source is TypeScript run through Node's type stripping; keep npm run typecheck green and never commit dist (npm run build emits it). - Run relevant regression tests and npm run verify for code changes. Run npm run test:package for packaging/CLI/starter changes. Schema edits require npm run docs:reference and executable examples. Let container changes pass CI. - Preserve unrelated work. Keep the standalone starter aligned when runtime behavior or onboarding changes. - Report actual evidence and remaining limitations. CI passing is not an independent security review or deployment/soak/recovery proof. - The auth, store and mcp extensions are workspace packages in this repository (packages/auth, packages/store, packages/mcp) and consume the generic contract in packages/core/src/extensions.ts. The audit log is the store's own, and its event contract and tap live in core, so a sink needs no package of ours. Core still never imports them: consolidating the packages into one repository did not make the dependency two-way, and a core change must not reach for a package. The packages that depend on core resolve it to this checkout rather than the registry, which scripts/check-workspace-links.ts asserts. Their prose links locally too: the former ui, auth and admin repositories are retired, so Markdown pointing at one of them, or at a relative path that does not exist, fails scripts/check-local-links.ts — label genuinely historical release evidence with `` rather than rewriting it. docs/FRAMEWORK.md describes how the four packages compose; keep it and llms.txt accurate when the contract or the CLI changes. Current version numbers live in the manifests and docs/VERSION-ALIGNMENT.md; do not copy them into other prose, which is how they went stale before. ## Public documentation belongs in this repository `docs/` here is the public documentation home. Write reader-facing guides, references, recipes, provider and operations material, contributor instructions and the generated `YAML-REFERENCE.md` here. Keep private strategy, internal research and detailed dated maintainer reviews in the private maintainer repository; those notes never replace an implemented public contract. - Follow [the documentation maintenance rules](CONTRIBUTING.md#maintain-existing-pages-first): search for an existing home before creating a page, link to authoritative facts rather than copying them, and put routine task reports in the PR. - A code change that alters behavior a reader depends on is not finished until the matching page in `docs/` is updated. Do it in the **same** pull request, so review sees both halves and neither can land alone. - Do not open a documentation pull request against another repository for content that belongs here. - `urlcode-docs` is **deleted** (2026-09-19). It held its own copy of most of these pages and had drifted from them; it was retired rather than reconciled page by page. Every `github.com/jimhoyd-com/urlcode-docs` URL now 404s, and there is nothing to open a pull request or issue against. Anything in it that was ahead of this repository was brought across before it went. ## File what you find GitHub Issues are the sole tracker for actionable defects, gaps, ideas and follow-up work. Do not create or retain repository-local issue files, backlogs, or duplicate issue bodies. Benchmark and other evidence may link to its GitHub issue, but must not copy the issue body into the repository. Do not silently drop a defect, a gap or an idea you could not act on. File it as an issue on the repository that owns the code, using that repository's issue templates: | What you touched | Where to file | |---|---| | Runtime, CLI, schema, core docs tooling | [urlcode](https://github.com/jimhoyd-com/urlcode/issues) | | The Better Auth adapter: its mount, `auth: true` and the user id capability (`packages/auth`) | [urlcode](https://github.com/jimhoyd-com/urlcode/issues) | | The store's audit log, its tap (`StoreExports.audit`) and core's audit event contract | [urlcode](https://github.com/jimhoyd-com/urlcode/issues) | | Per-route middleware (the native `middleware:` array) | [urlcode](https://github.com/jimhoyd-com/urlcode/issues) | Feature requests are wanted, not just bugs: if the vocabulary made you generate or hand-maintain application code that URLCode could have owned, that is the evidence the roadmap runs on — file it with the YAML you had to write. Search first and add to the existing issue rather than opening a duplicate. State what you observed, not what you assume; say plainly when something is unverified.