README.md

# AI-Native Monorepo Bootstrap

This repository is a project-agnostic TypeScript monorepo optimized for AI-assisted development with explicit guardrails.

## Quickstart
```bash
pnpm install
cp .env.example .env
cp .env.agent.example .env.agent
pnpm regen:sdk
pnpm lint
pnpm typecheck
pnpm test
pnpm check:boundaries
pnpm verify:contracts
```

## Run Local Development
```bash
pnpm dev
```
This starts `@apps/web` and `@apps/api` through Turborepo.

## Run Tests
```bash
pnpm test
```

## Staging Deploy (After Merge)
- `ci` runs on pull requests and pushes to `main`.
- `cd-staging` runs automatically after a successful `ci` run on `main`.
- By default, it runs in local-only mode for backend (`api/workers`) and only triggers Vercel deploy hooks for web/admin.
- To enable backend self-host deploys, set repository variable `ENABLE_SELF_HOST_STAGING=true`.
- Configure these GitHub environment secrets in `staging`:
  - `STAGING_DEPLOY_HOOK_WEB`
  - `STAGING_DEPLOY_HOOK_ADMIN`
- Optional self-host secrets (only needed when `ENABLE_SELF_HOST_STAGING=true`):
  - `STAGING_SSH_HOST`
  - `STAGING_SSH_PORT`
  - `STAGING_SSH_USER`
  - `STAGING_SSH_PRIVATE_KEY`
  - `STAGING_SSH_KNOWN_HOSTS`
  - `STAGING_DEPLOY_PATH`
- Self-host setup runbook: `docs/runbooks/STAGING_SELF_HOST.md`

## Add A New Module
1. Create `apps/<name>` or `packages/<name>`.
2. Add `package.json`, `tsconfig.json`, `src/index.ts`.
3. Add scripts: `build`, `lint`, `typecheck`, `test`.
4. Update `docs/ARCHITECTURE_MAP.md` dependency rules.
5. Run boundary checks.

## Contracts Source Of Truth
- API and event contracts live in `packages/contracts/src/*`.
- SDK is generated into `packages/sdk/src/index.ts` using `pnpm regen:sdk`.

## Agent Mode
- Use `.env.agent` for restricted runs.
- Agents must not use `.env` unless a human approves.
- Entry rules: `AGENTS.md`
- Agent docs: `docs/agent/*`

## External Setup Checklist
1. Create a GitHub repository and push this code.
2. Enable branch protection on `main` with required checks:
   - `lint`
   - `typecheck`
   - `test`
   - `check-boundaries`
   - `verify-contracts`
3. In GitHub Actions settings, allow read access to contents and write access only where required.
4. Optional: add repository secrets (never commit real secrets).
5. Install local tooling: Node LTS, pnpm, Docker (optional for Postgres).

## Key Links
- Agent entrypoint: `AGENTS.md`
- Architecture map: `docs/ARCHITECTURE_MAP.md`
- Agent workflow: `docs/agent/WORKFLOW.md`
- Task templates: `docs/agent/TASK_TEMPLATES.md`