189 lines
5.4 KiB
Markdown
189 lines
5.4 KiB
Markdown
# <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> }_
|
|
|
|
|
|
|
|
<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>
|
|
--- | --- | ---
|
|
 |  | 
|
|
|
|
## 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.>
|
|
|
|
|
|
|
|
### <Second Feature>
|
|
|
|
<Explain the next most important product surface.>
|
|
|
|
|
|
|
|
### <Third Feature>
|
|
|
|
<Explain the third most important product surface.>
|
|
|
|
|
|
|
|
## 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/Engineering_Reference_Manual.md](docs/architecture/Engineering_Reference_Manual.md) | Architecture, data model, and engineering rules. |
|
|
| [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.
|