# Project Setup

This setup contract is completed before phase implementation. It turns short human alignment and mapped product obligations into concrete project architecture, team operating rules, quality gates, and the future project `AGENTS.md` plan.

## Setup defaults

- Human answers come from `01-questions.md`.
- Blank answers are not blockers. The implementation agent chooses best-fit, high-quality defaults from mapped product obligations and product goals.
- Ask the human only for irreversible, expensive, credentialed, destructive, or product-defining forks.

## Product / capability shape

- Blueprint mode:
  - Primary: framework
  - Secondary: sdk, cli, api
  - Phase style: primitive_composition_map
  - Why this mode fits: fixture maps a reusable record-ingest primitive and its composition rules; the packet must not collapse the framework into one downstream app flow.
- Product / capability: record-ingest framework fixture
- Frontend/UI surfaces: none required; consumer experience is SDK/API/CLI proof, not UI proof.
- Backend/API surfaces: exported ingest primitive, validation API, storage adapter contract, and CLI/demo callable.
- State/runtime surfaces: storage adapter state, restart/readback proof, migration and lifecycle hooks.
- Tests/evaluation: derive from `04-evaluation.md` and phase proof gates.

## Architecture decisions

Record decisions with short evidence, not bureaucracy:

- Framework/runtime:
  - Decision: AI best-fit unless human constrained it.
  - Evidence: mapping, product requirements, and phase proof gates.
- Package manager:
  - Decision: choose product-faithful or ecosystem-standard default.
  - Evidence: lockfiles/workspace evidence if available.
- Data/storage:
  - Decision: real persistence where the product requires durable state.
  - Evidence: state/runtime requirements in phases.
- Auth/providers/deployment:
  - Decision: production-grade architecture is the default for full-suite mapped packets. Missing credentials, paid-service approval, or deployment authorization may block live proof, but they do not remove auth/session/tenant design, provider adapters, config contracts, tests, deployment shape, or runtime wiring from scope.

## Production readiness contract

Complete these decisions before phase work. Do not downgrade to a local MVP unless the selected scope explicitly says prototype-only.

- Auth/session/tenant boundary: define users/sessions, roles or ownership, tenant/privacy isolation, audit-relevant actions, and access-control behavior. If the mapped product has no auth, define the minimum product-appropriate local/session boundary and the migration path to real auth.
- Provider integration contract: define live provider adapters, env/config names, request/response/error contracts, deterministic test doubles, sandbox/live mode disclosure, and tests. Missing credentials block only live proof, not adapter/config/test implementation.
- Durable persistence contract: define database or storage choice, schema ownership, migrations, restart/readback proof, backup/export/delete semantics, retention, quotas, and sensitive data handling.
- Worker/runtime contract: define queue or job ownership, retries, cancellation, timeout behavior, failure recovery, progress persistence, idempotency, and dead-letter or repair handling for async/runtime work.
- Deployment and operations contract: define local dev, production build/run command, container or hosting shape, health/readiness checks, structured logging, metrics/tracing, rate/request-size limits, and CI gates.
- Browser/e2e contract: define repeatable Playwright or equivalent browser flows for major UI paths and states. Screenshots support evidence but do not replace automated e2e coverage for UI-bearing phases.
- Screenshot critique: browser proof must inspect screenshots as product artifacts, not only as assertion attachments.

## Experience quality contract

Framework work must define product-grade developer experience before phase work; UI is not required unless the selected framework includes a UI demo.

- UI architecture: not UI-bearing; define import, API, CLI/demo, examples, errors, and trace output instead of fake browser pages.
- Product composition: expose primitives, composition rules, extension points, and invalid states as a coherent developer surface.
- Domain-specific affordances: represent records, validators, storage adapters, and readback patterns with typed examples and reference composition.
- Visual system: define documentation/readability, API ergonomics, command output stability, logging, and discoverability.
- State quality: empty input, validation error, storage blocked, success/readback, retry, and recovery states must be intentional and stable.
- Screenshot critique: if screenshots are used for optional docs/demo UI, critique them; otherwise prove consumer experience through import/API/CLI traces and example output.

## Mapped contract anchors

Promote compiled product observations into implementation contracts before starting phases:

- Route/API/job prefixes and handlers: mapped note api/records.ts records ingest capability; target route may differ if equivalent behavior is preserved.
- Request/response payloads and validation errors: submitted record requires validation for missing required fields and returns stored/readback result.
- Provider/runtime boundaries and env var names only: none required for this fixture.
- Durable state, generated artifacts, retention, import/export, and delete/reset behavior: durable record storage and readback are required; optional exports must be labeled as runtime artifacts, e.g. runtime artifact `records.json`.
- UI flow/state anchors including empty/loading/error/blocked/success states: ingest form/list states are UI-bearing if implemented.

## Mapped obligation/surface matrix

- Surface id: SRC-INGEST-API
  - Source evidence: mapped note api/records.ts:1-20.
  - Mapping note: mapped note api/records.ts:1-20.
  - Mapped obligation: provide a reusable ingest primitive that accepts records, validates required fields, persists through an adapter, and exposes readback.
  - Target disposition: preserve | replace | merge | defer | drop | blocked. This fixture uses preserve.
  - Target contract: equivalent primitive, invariants, composition rules, adapter seam, invalid states, and readback behavior; route/function names may change.
  - Compatibility impact: mapped route name is an anchor only, not route/function parity.
  - Owning phase: `03-phases/01-ingest-record.md`.
  - Phase(s): `03-phases/01-ingest-record.md`.
  - Required proof: ingest primitive fixture validates required fields, persists through the adapter seam, and reads the same record back.

Rules:

- Every high-signal mapped surface must appear exactly once with one owning phase, or be marked dropped/blocked with rationale.
- If a surface is split, name one primary owning phase and supporting phases in the target contract; do not leave ambiguous shared ownership.
- Required proof must reference the owned surface specifically, not only “tests pass”, “app builds”, or “feature preserved”.
- This is not route/function parity. Prefer cleaner target architecture when it preserves or intentionally improves the capability.
- No mapped surface may disappear silently. If it is merged, replaced, deferred, dropped, or blocked, record why and where the equivalent obligation or blocker lives.
- Origin repository filenames such as package manifests, lockfiles, or route files are mapping notes, not packet file references. Label them as mapped notes instead of ambiguous packet links.
- Future files produced by the implementation/product are runtime artifacts or generated outputs, not packet files. Label them inline, e.g. `runtime artifact: <name>` or `generated output: <name>`.
- Unlabeled backticked `.md`, `.yaml`, `.json`, or `.jsonl` references are reserved for actual packet files that exist in `selected-buildprint/`.

## Implementation project setup

The Buildprint packet must not contain `AGENTS.md`. The implementation project should create root/local `AGENTS.md` and setup artifacts after this file is resolved.

- Root `AGENTS.md`: short scope governor with project shape, architecture boundaries, safety rules, local instruction map, and "do not broaden current phase" rule.
- Local `AGENTS.md`: create only at real architectural boundaries such as frontend/app, backend/API, provider adapters, workers, data/db, infra, or tests/e2e.
- Runtime setup artifact: before starting `03-phases/*`, write `.buildprint/setup.md` or files under `.buildprint/setup/` recording concrete auth, provider, persistence, worker, deployment, browser/e2e, visual QA, safety, and verification decisions.
- Creating only `AGENTS.md` is not enough to satisfy the setup gate.
- Phase entry remains governed by `03-phases/phase-flow.md` and role contracts under `06-contracts/`.

## Open assumptions

For each unresolved choice, record:

- Assumption:
- Evidence:
- Risk:
- Blocks phase work: yes/no

Unanswered ordinary engineering choices should become AI-owned assumptions, not blockers.

## Phase start gate

Do not start `03-phases/*` until this file is explicit enough to generate project root/local `AGENTS.md` without inventing architecture.

Initial phase set:

- `03-phases/01-ingest-record.md`