Project-Template/project-readme-template.md

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>

Screenshots | What makes it different | Product surface | Run locally | QA and release | Project docs

{ | | | | | <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:

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

Screenshots

What Makes It Different

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

Product Surface

Area	What it does	Why it matters

Spotlight

Platform Status

Surface	Status	Notes
	<Built	Active
	<Built	Active

Architecture

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

Core stack:

• <Framework/runtime>
• <Database/storage>

Run Locally

Prerequisites:

Start the project:

<install command>
<development command>

Open <local URL>.

Configuration

Variable	Purpose
<ENV_VAR>
<ENV_VAR>

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

QA And Release

Run checks:

<typecheck command>
<test command>

Release or deploy:

<release command>

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

Repository Map

<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	Which document owns which answer, and which source wins when records disagree.
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	Architecture, data model, and engineering rules.
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.