Project-Template/project-readme-template.md

# <Project Name>

```text
Status: <Current | Draft | Superseded | Archived>
Owner: <person or role>
Last reviewed: <YYYY-MM-DD>
Governs: README.md as the project-facing overview for <project or repo>
Review trigger: <event that should make an agent update this README>
```

<One clear sentence that says what the project is and who it is for.>

[Screenshots](#screenshots) | [What makes it different](#what-makes-it-different) |
[Product surface](#product-surface) | [Run locally](#run-locally) |
[QA and release](#qa-and-release) | [Project docs](#project-docs)

_{ <Platform or public surface> | <Admin or app surface> | <Backend> |
<Most important feature> | <Second important feature> | <Privacy/security posture> }_

![<Primary screenshot or feature graphic alt text>](<path/to/primary-image.webp>)

<Short product overview. Write for somebody evaluating the project, not for the
person who already knows the code. Explain the problem it solves, the shape of
the product, and the reason it exists.>

The core loop is:

```text
<first user action> -> <second user action> -> <valuable outcome>
```

## Screenshots

<Use real current screenshots. Prefer the actual product surface over diagrams
or mood images.>

<Screenshot A> | <Screenshot B> | <Screenshot C>
--- | --- | ---
![<alt text>](<path>) | ![<alt text>](<path>) | ![<alt text>](<path>)

## What Makes It Different

<Do not make this a feature dump. Name the product decisions that make the
project worth caring about.>

| Principle | What it means |
| --- | --- |
| <Differentiator> | <Specific, evidence-backed explanation.> |
| <Differentiator> | <Specific, evidence-backed explanation.> |
| <Differentiator> | <Specific, evidence-backed explanation.> |

## Product Surface

| Area | What it does | Why it matters |
| --- | --- | --- |
| <Feature area> | <User-visible behavior.> | <Outcome or reason.> |
| <Feature area> | <User-visible behavior.> | <Outcome or reason.> |
| <Feature area> | <User-visible behavior.> | <Outcome or reason.> |

## Spotlight

### <Primary Feature>

<Explain the most important product surface in plain language. Name what is
built and what the user can do with it.>

![<Primary feature screenshot alt text>](<path>)

### <Second Feature>

<Explain the next most important product surface.>

![<Second feature screenshot alt text>](<path>)

### <Third Feature>

<Explain the third most important product surface.>

![<Third feature screenshot alt text>](<path>)

## Platform Status

| Surface | Status | Notes |
| --- | --- | --- |
| <Surface> | <Built | Active | Work in progress | Planned | Deprecated> | <Evidence or limitation.> |
| <Surface> | <Built | Active | Work in progress | Planned | Deprecated> | <Evidence or limitation.> |

## Architecture

```text
<client or public surface>
  |
  v
<app/runtime>
  |
  +--> <database or storage>
  +--> <external service>
  +--> <worker or queue>
```

Core stack:

- <Framework/runtime>
- <Database/storage>
- <Authentication>
- <Deployment target>
- <Important integrations>

## Run Locally

Prerequisites:

- <Tool or service>
- <Tool or service>

Start the project:

```bash
<install command>
<development command>
```

Open `<local URL>`.

## Configuration

| Variable | Purpose |
| --- | --- |
| `<ENV_VAR>` | <What it controls.> |
| `<ENV_VAR>` | <What it controls.> |

Keep secrets out of screenshots, README prose, and tracked sample files.

## QA And Release

Run checks:

```bash
<typecheck command>
<test command>
```

Release or deploy:

```bash
<release command>
```

<State whether release and deployment are the same action. If they are
separate, say which tool owns each step.>

## Repository Map

```text
<path>/        <purpose>
<path>/        <purpose>
<path>/        <purpose>
docs/          product, architecture, QA, security, and history docs
```

## Project Docs

`README.md` is the landing page for someone evaluating the project. Detailed
procedures belong in docs, and open work belongs in the tracker.

| Doc | Purpose |
| --- | --- |
| [docs/DOC_TRUST_MAP.md](docs/DOC_TRUST_MAP.md) | Which document owns which answer, and which source wins when records disagree. |
| [docs/WORK_CYCLE.md](docs/WORK_CYCLE.md) | What happens at the end of a piece of work: closing issues and milestones, recording next action and blockers, and what privacyllc.dev will and will not update on its own. |
| [docs/architecture/README.md](docs/architecture/README.md) | Architecture, data model, and engineering rules. Name a reference manual beside it once the project has one. |
| [docs/security/SECURITY.md](docs/security/SECURITY.md) | Threat model and security posture. |

## Agent Notes

- Product truth comes from the code and the tracker before prose.
- Do not keep a work list in this README.
- Finish with `docs/WORK_CYCLE.md`, every time: close the issues you finished
  with the evidence that proves it, close the milestone if the batch landed,
  update the documents the change triggered **in the same commit**, then record
  the next action and any blockers before you stop.
- Nothing on privacyllc.dev writes itself except the tracker counts and the
  pushed docs. The summary and next action change only when they are sent; the
  milestone and blocker tables there change only when a human edits them.
- Do not claim a feature is built unless you can cite the route, file,
  migration, release, or screenshot that proves it.
- Keep screenshots current when the UI changes meaningfully.
- Keep the first screen product-facing. Put deep operations lower down or in
  docs.