# Feature Integration Playbook Use this playbook when adding a feature to the boilerplate or adapting a proprietary feature from another product. ## Goal Make the feature understandable before implementation. A human operator and a coding agent should be able to answer where the feature lives, who owns its configuration, which flows it exposes, and how to verify it. ## Required Steps 1. Read `docs/agent-entrypoints.md`. 2. Find or create a manifest in `docs/feature-manifests/`. 3. Classify ownership: - `tenant-owned`: tenant configures and uses it. - `admin-managed`: admin/platform configures it; tenant only uses approved surfaces. - `hybrid`: admin defines policy/defaults; tenant can configure local behavior. - `system-only`: internal platform feature with no tenant-owned controls. 4. Map surfaces: - Admin route source files and canonical admin-host runtime paths. - Tenant route source files and canonical tenant-host runtime paths. - Public route source files and root/web-host runtime paths. - API route source files and canonical API-host `/v1/...` runtime paths. - Link/form/action helpers: `adminPath`, `appPath`, `apiPath`, cross-host helpers, or `UrlUtils.getModulePath(...)` for tenant modules. 5. Map persistence: - Prisma models. - Existing tables reused. - Migrations required. - Tenant scoping fields. 6. Map configuration: - Admin settings. - Tenant settings. - Environment variables. - Secrets and their owner. 7. Map runtime: - Request/response only. - Queue-backed. - Worker-backed. - Browser-backed. 8. Map controls: - Permissions. - Audit events. - Billing or usage limits. 9. Define UAT: - Operator-visible checks. - Negative checks for forbidden access. - Secret exposure checks if providers are involved. ## Implementation Rules - Do not expose provider secrets through tenant loaders, API responses, client bundles or logs. - Do not add sidebar/nav entries without stable UI IDs. - Do not add new root UI primitives without updating `docs/ui-inventory/components.json`. - Do not add worker behavior without declaring queues and jobs in the manifest. - Do not add admin-managed tenant behavior without admin permissions and audit events. - Keep proprietary feature logic behind explicit module boundaries. - Do not hard-code legacy runtime paths such as `/admin/...`, `/app/...`, or `/api/v1/...` outside tests that explicitly cover legacy redirects. - Do not ship visible UI text without locale keys and `pnpm run verify:i18n`. ## Done Criteria - Manifest updated and valid. - Routes and surfaces match the manifest. - Permissions are enforced on admin/API/tenant surfaces. - Tenant-scope negative tests cover forbidden reads and mutations. - Route helpers and runtime host ownership are tested for new navigation. - i18n and deploy/static verifiers relevant to the change have run. - Required worker queues/jobs exist or are explicitly deferred. - UAT checks pass or are marked as deferred with a reason.