Contributing to Kody

Documentation for people and agents developing this repository: setup, code style, tests, MCP capabilities, and runtime architecture.

Setup and workflow

• Getting started, project intent
• Decision records (steering veto list: product-shaped nos and durable constraints — not an ADR-per-PR log)
• 0033 memory auto-surface lab (policy-grid evidence; re-run node tools/memory-auto-surface-lab/run.mjs)
• Inbound contributions (CLA for patches to this repository)
• Setup, environment variables, setup manifest
• Manual PR preview testing
• control-kody (Feature Map + CLI; daily @kentcdodds/verification-skill-maintain)
• Optional Cloudflare offerings
• Cursor Cloud Agent notes
• Nx remote cache (self-hosted HTTP cache shared by agents and CI)
• Harness engineering (agent-first loop, promoting lessons into checkers before should-lists)
• Code health receipts (measured quality numbers and the oversized-file cleanup record)
• Cleanup after migrations (drop leftovers in the same change, or open a GitHub issue)
• Planned breaking changes (leftovers that still work and will be removed later, including kody_id / kody.id)
• Friction log (file through kody:@kentcdodds/friction-log/create; daily Cursor agent investigates)

Code and tooling

• Code style, TypeScript setup
• Import boundaries (enforced app / MCP / worker / universal layering)
• Oxlint JS plugins, dependency overrides (typescript/no-explicit-any, TODO/FIXME/HACK, file-size ratchet, vanished-copy kody-custom/no-tautological-absence, knip)
• Remix skills and page checklist, frames
• No-flash navigation (load-before-commit router, createRouteData keeps the previous page until the next one is ready)
• Cloudflare Agents SDK usage

Testing

• Testing principles
• End-to-end testing
• Weekly site performance
• Mock API servers
• Package discovery routing evaluation

Packages and MCP

• Packages and manifests
• Package sharing (person-to-person use grants; not platform scope grants — 0050)
• packageStorage() grants and stamp-aligned secrets (stamp/grant model under fork-only official packages and no author-facing invoke)
• Package codemods
• packages.invoke prefix migration (soak telemetry for the quarantined helper leftover)
• Public packages
• External package invocation API (unadvertised drain; first-party HTTP is inbound webhooks)
• Invocation-token retirement runbook
• Adding capabilities
• Search entity plugins (plugin module + registry, result/detail unions, list markdown, detail routing, public type lists)
• MCP server patterns (reference for server design)
• AI chat package guide
• Execute patterns: Cloudflare API v4, Cloudflare developer docs

Security and operations

• Security, 2026-09-16 codebase audit, secret host approval, secret providers, secret rotation, social login
• Operator accounts (third-party services, secret names, recovery)
• Production backup and disaster recovery
• Production rollback
• Ops runbook: account write-lease repair

Architecture

• Architecture — production worker fleet, request lifecycle, authorization (RBAC)

Documentation for using Kody as an MCP server (not building the repo) lives under docs/use/. How we write and maintain those pages (and contributing docs) is covered in Documentation principles (prefer a checker over a should-list).