# Feature Manifests

This directory is the machine-readable contract for boilerplate core pruning. It complements `docs/feature-inventory.md`, which remains the human-readable inventory.

## Manifest-Decision: Pruned Core statt Full-Boilerplate

Feature Manifest chooses Pruned Core over a permanent Full-Boilerplate retention promise. `core` manifests define what remains in the default boilerplate; `plugin-candidate` manifests are extraction contracts for optional product surfaces; and `remove-candidate` manifests are deletion or review contracts for surfaces that should not become indefinitely supported legacy behavior. These manifests operationalize the inventory decision as planning/runtime guardrails and do not claim that every extraction or deletion has already happened in the current root runtime.

Architecture Closure closure aligns three canonical sources for future feature work: `docs/architecture-migration-status.md` records the current API, worker, package, pruning, and bundle handoff status; `docs/feature-inventory.md` records the human-readable Core/Plugin/Removal inventory; and `docs/feature-manifests/*.json` records the machine-readable Core/Plugin/Removal contract. Treat the manifest set as the executor-facing source of truth for ownership, dependencies, configuration, provider, worker, UAT, and pruning boundaries. Any future feature addition, migration, extraction, or removal must update the relevant manifest before implementation so code changes satisfy the declared contract instead of relying on stale roadmap assumptions.

Feature-specific decision reports may live under `docs/feature-decisions/`; canonical examples are the CRM decision report at `docs/feature-decisions/crm-decision-report.md` and the Email Marketing decision report at `docs/feature-decisions/email-marketing-decision-report.md`.

## Contract

Each `*.json` manifest follows `schema.json` and uses:

- `id`: stable feature identifier for cross-references.
- `classification`: `core`, `plugin-candidate`, `remove-candidate`, or `mixed`.
- `codeAreas`: likely source locations. These are planning hints, not ownership grants.
- `dependencies`: other manifest IDs this feature needs.
- `consumers`: features or surfaces that rely on this feature.
- `integration.ownership`: `tenant-owned`, `admin-managed`, `hybrid`, or `system-only`.
- `integration.surfaces`: admin, tenant, public, and API route contracts.
- `integration.configuration`: admin settings, tenant settings, environment variables, and secret ownership.
- `integration.workers`: queue/job requirements for async, browser-backed, or long-running work.
- `integration.externalProviders`: provider dependencies such as billing vendors, AI providers, mail vendors, or browser runtimes.
- `integration.permissions`, `auditEvents`, `billingImpacts`, and `uat`: implementation guardrails and operator checks.
- `boundaries.mustKeep`: behavior that should remain in the boilerplate.
- `boundaries.mayMoveToPlugin`: behavior safe to extract after dependency review.
- `boundaries.mustNotTouch`: areas excluded from the current phase or owned by parallel work.
- `pruning.action`: current intended action: `keep`, `extract-plugin`, `remove`, or `review`.

Route entries are source ownership hints unless they explicitly start with a runtime path such as `/v1/...`. Runtime URLs must follow the host split: admin routes live at the admin host root, tenant routes live under `/:tenant` on the app host, and API routes live under `/v1` on the API host. Implementation work must use host-aware helpers rather than reintroducing `/admin/...`, `/app/...`, or `/api/v1/...` links.

When a manifest change affects UI text, tenant data, or deploy behavior, include the matching verification in the plan: `pnpm run verify:i18n`, tenant-scope negative tests, `pnpm run verify:deploy-workflow`, Docker smoke checks, and production seed artifact verification as applicable.

## Current Manifests

- `core.json`: umbrella contract for the boilerplate core.
- `product-core.json`: versioned CRM SaaS Product Core blueprint and access-gating contract.
- `auth-tenancy.json`: authentication, accounts, tenants, roles, invitations.
- `rows-entities-runtime.json`: Prisma/DB, rows, entity runtime foundations.
- `billing.json`: Stripe-backed subscription and pricing foundation.
- `transactional-mail.json`: password reset, invitation, and system mail.
- `admin-app-shell.json`: admin and tenant app shells, dashboards, settings.
- `plugin-candidates.json`: feature groups to package or make optional.
- `remove-candidates.json`: feature groups to remove or aggressively review.
- `ai-chatbot-admin-managed.json`: reference pattern for admin-managed, tenant-consumed, worker/browser-backed AI features.

## Proprietary Feature Template

When importing or building a proprietary feature, create or update a manifest before code changes and fill these fields:

- Feature ownership: `tenant-owned`, `admin-managed`, `hybrid`, or `system-only`.
- Admin, tenant, public and API surfaces.
- Config ownership: admin settings, tenant settings, environment variables.
- Secrets policy: owner, storage, and client exposure rules.
- Worker/queue jobs: queue names and job names from `packages/queue`.
- Permissions: admin configuration and tenant usage capabilities.
- Audit events: configuration, enablement, job lifecycle and failure events.
- Billing impact: plan gates, metering, provider cost exposure.
- UAT checklist: positive, negative and secret-exposure checks.

To create a valid scaffold:

```sh
pnpm run manifest:new -- --id my-feature --title "My Feature" --classification plugin-candidate --ownership hybrid
```

The generator writes `docs/feature-manifests/my-feature.json` and refuses to overwrite unless `--force` is passed. Replace scaffold placeholders before implementation.

## Validation

Cheap syntax validation:

```sh
find docs/feature-manifests -name '*.json' -print0 | xargs -0 -n1 node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))'
```

The app test suite validates the manifest structure, required integration fields, dependency references, admin-managed secret ownership, and worker queue/job declarations.