# Agent Entrypoints

Use this file as the first stop when a coding agent plans or implements feature work in this boilerplate.

## Start Here

- Interpreting old improvement-plan status, handoffs, or verification notes:
  read `docs/improvement-plan/CURRENT-STATUS.md` first, then follow the
  canonical docs it links.
- New or migrated feature: read `docs/agent-playbooks/feature-integration.md` and update the matching manifest before implementation.
- Existing MVP import: read `docs/agent-playbooks/mvp-intake.md` before proposing code changes.
- Admin-managed tenant feature: read `docs/agent-playbooks/admin-managed-features.md`.
- Foundation, billing usage, notifications, flags, permissions, audit, or idempotency changes: read `docs/agent-playbooks/foundation-boundaries.md`.
- Worker-backed or browser-backed feature: read `docs/agent-playbooks/worker-backed-features.md`, `docs/ops/worker-queues.md`, and `packages/queue/src/payloads.ts`.
- Plugin, WASM, lifecycle, or hook work: read `docs/features/plugins.md`, `docs/operations/plugin-lifecycle.md`, and `docs/security/plugin-runtime-signoff.md`.
- UI surface or component changes: start with `docs/ui-inventory/surface-map.md`, then read `docs/agent-playbooks/ui-changes.md`, `docs/ui-inventory/`, and `apps/web/app/application/ui/uiRegistry.ts`.
- Navigation, sidebar, or route-helper changes: read `docs/navigation-architecture.md`.
- UI adapter or hotswap work: read `docs/agent-playbooks/ui-adapter-migration.md` and `packages/ui/README.md`.
- Feature ownership, dependencies, configuration, provider, worker and UAT contracts: read `docs/feature-manifests/`.
- New manifest scaffold: run `pnpm run manifest:new -- --id my-feature --title "My Feature" --classification plugin-candidate --ownership hybrid`, then replace placeholders before coding.
- Architecture Closure closure/status contract: start from the aligned sources `docs/archive/architecture-handoff-summary.md`, `docs/architecture-migration-status.md`, `docs/feature-inventory.md`, and `docs/feature-manifests/*.json`; read them together before planning implementation, extraction, or removal work.

## Agent Rule

Do not jump from a user request directly into implementation when the request imports an existing product, adds a proprietary feature, adds provider credentials, changes admin-managed behavior, or introduces workers.

For those requests, produce or update a feature manifest first. The manifest is the contract the implementation must satisfy.

## Expected Planning Output

For a substantial feature, the planning output should identify:

- Existing user flows and target boilerplate flows.
- Feature ownership: `tenant-owned`, `admin-managed`, `hybrid`, or `system-only`.
- Admin, tenant, public and API surfaces.
- Runtime route ownership and helper choice: admin host paths use `adminPath`, tenant app paths use `appPath` or `UrlUtils.getModulePath(...)`, and API host paths use `apiPath`/`/v1`.
- Tenant-scope and negative access checks for every loader/action/API mutation that touches tenant data.
- i18n surfaces, including new locale keys and `pnpm run verify:i18n` when UI text changes.
- Deploy/static gates affected by the change, especially `pnpm run verify:deploy-workflow`, Docker baseline/static checks, and production seed artifact checks for deploy work. Run live Docker smokes only when the task explicitly requires them.
- Database models and migrations.
- Provider credentials and secret ownership.
- Worker queues and jobs.
- Permissions and audit events.
- Billing or usage-metering impact.
- UAT checks the operator can run.