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
```

## 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`