# Agent: Repository project overview (`project.md` in context)

| Field | Value |
| ----- | ----- |
| **AGENT_ID** | `ctx-md-docs-project` |
| **Display name** | Docs — project overview |
| **SRS-8** | Markdown detail under **`.easyspecs/context/`** (same folder as `architecture.md`); **R7** / **R21** apply. |
| **Output** | `<worktree>/.easyspecs/context/project.md` |
| **Pattern** | §3.5.1 — Markdown detail |

## Responsibility

**`.opencode/` and `.claude/` exclusion:** The worktree may contain **`.opencode/`** or **`.claude/`** (materialized coding agent definitions, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** or **`.claude/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.

Produce or refresh **`project.md`**: a **single entry-point document** for humans that explains **what this repository is for**, its **overall goal**, a **concise upfront summary**, **illustrative** capabilities and use cases (not exhaustive), how it behaves at a high level, how to run and build it, and where deeper docs live. It complements **`architecture.md`** in the same directory (architecture = structure and flows; **project** = product/repo handbook).

**Incremental delivery:** Treat **`{{OUTPUT_FILE_ABSOLUTE}}`** as a **living document**. **Survey the whole worktree** (top-level folders and important subtrees: `src/`, `resources/`, `test(s)/`, `docs/`, `.github/`, config roots, etc.) and **open representative files** until you have a grounded picture; on **each** pass that changes the file, **append** to **`## Revision`** (see template) **at least one** new line stating **what** you added or changed. Do not drop prior revision lines when you rewrite the file.

**Clarity over rigidity:** You **may** add **extra `##` or `###` chapters** anywhere in the body (before **`## Revision`**) when they help explain the repository—e.g. key workflows, CLI vs UI surfaces, analysis pipeline, deployment path, domain concepts. You **may** embed **Mermaid** diagrams in standard fenced **` ```mermaid `** blocks to illustrate flows, component relationships, or state; follow **[MERMAID.md](./MERMAID.md)** (**Mermaid 11.13**, **neutral** theme). Keep diagrams **grounded in the codebase**, **legible** (avoid huge graphs), and mention new diagrams or sections in **`## Revision`**.

Target audience: contributors, release engineers, and context consumers that read the analysis worktree.

## Implementation-only (SRS-114)

Document **only** what is **implemented in this repository today**. Do **not** add knowledge nodes for planned, missing, roadmap, or spec-only capabilities.

- **Include** a row or detail section **only** when you can cite **implementation evidence** (§3.1 in SRS-114): wired entrypoints, executable bodies, real UI artefacts, schemas in use, or behavioural tests (QA/TC).
- **Omit** the node entirely when you find only SRS, PLAN, README, comments, types without callers, empty stubs, or configs nothing reads.
- **`sourceReferences`** and **Evidence index** **must** include **at least one implementation anchor** (non-`.md` path per §5.6.2). **`.md`** files (SRS, README, plans) **may** be cited **in addition**, never as the **only** cites.
- **Review passes:** drop unimplemented rows like false rows; log **`droppedCodes`** / **`revisionLog`** (SRS-50).
- **Do not** fill coordination lists with placeholders for future work. An empty array is valid when nothing is implemented.


## Task (for `{{TASK_DESCRIPTION}}`)

Analyse **`{{WORKTREE_ROOT}}`** systematically: **map directories and files** (list roots, then drill into areas that define behaviour), and read **`README`**, **`package.json`** / manifests, **`src/`** entrypoints, **`docs/`**, SRS under **`.easyspecs/docs/`** when present, plus any other paths that clarify product intent. **If `project.md` already exists**, read it first; **preserve and extend** **`## Revision`** (append new entries; never delete history). Improve content **incrementally**—you may do multiple read→edit→write cycles in one run: after **each** write, the on-disk file must include **all** previous revision bullets **plus** new line(s) for that step.

Write **`{{OUTPUT_FILE_ABSOLUTE}}`** = `<worktree>/.easyspecs/context/project.md`.

**Required narrative shape (in order):**

1. **Summary** — Place **first** after the title: a short block (roughly **3–6 sentences** or a tight bullet list) answering: what this repo is, who it serves, and the main outcomes or problems it addresses. No deep implementation detail here.
2. **Overall goal** — A dedicated section stating the **north star**: why the repository exists, the problem space or product mission, and what “success” means at repo level (still high level; cite sources in the Evidence index).
3. **Illustrative capabilities and use cases** — A **non-exhaustive** section with two sub-parts:
   - **Capabilities / functionalities** — Bullet list of **representative** features or subsystems (from commands, UI, APIs, CLIs, pipelines—whatever the repo actually exposes). Label explicitly that the list is **illustrative, not complete**.
   - **Example use cases** — Short **user- or operator-oriented** scenarios (e.g. “As a developer, I …”) that **illustrate** how the product is used; these are **examples**, not a formal requirements catalogue.
4. Then cover **purpose** (product behaviour in slightly more detail), **repository role** (shipping/CI), **tech stack**, **scripts**, **source layout**, **configuration**, **related documentation**, **out of scope** as in the template below—**unless** you reorder slightly to group related ideas; the **Summary** must stay **first** after the title, and **`## Revision`** / **`## Evidence index`** stay **last** in that relative order.
5. **Optional sections** — Insert **additional chapters** (with clear headings) when needed for a faithful overview. Prefer handbook-level depth; defer deep system design to **`architecture.md`** unless a short diagram here prevents confusion.
6. **Mermaid** — Use **` ```mermaid `** … **` ``` `** blocks for flowcharts, sequence diagrams, or graphs when they clarify **how the product works** (activation, command routing, worktree/analysis flow, etc.); first line inside each fence **`%%{init: {'theme':'neutral'}}%%`** per **MERMAID.md**. Add a one-line caption before or after the block if helpful. Log “Added Mermaid …” (or similar) in **`## Revision`**.

Cross-link **`architecture.md`** in the same folder and repo **`README.md`** / **`docs/`** when they exist. Align filenames and claims with the actual tree.

## Non-empty chapters and Evidence index (mandatory)

- **`## Evidence index`** is the **references / code-grounding** chapter. It **must not** be empty, whitespace-only, or placeholder-only (no bare `-`, no section with zero bullets). A generated `.md` with **no** substantive grounding bullets there is **invalid** and is **rejected**—do not produce that outcome.
- **Preferred:** at least one concrete `path:line` or `path:start-end` cite from the worktree (implementation, config, tests, schemas—not README-style narrative files).
- **If grounding is impossible** after reasonable search: set **`Status: hallucination?`** on its **own line immediately under the top-level `#` title**, **and** still add **at least one** Evidence index bullet describing what was searched, partial findings, and that claims are not implementation-backed.
- **Other `##` sections:** do not leave them empty; if unknown, add a short note under that heading explaining why.
- **Banned:** never list any path whose **basename** is `readme.md` in **any** casing (`README.md`, `readme.md`, etc.) in the Evidence index. (You may still *mention* `README.md` in prose or **Related documentation**; do not use it as a code-grounding cite.) **Never** list paths under **`.opencode/`** either (tooling copy, not product source).

### Revision log (mandatory)

- Maintain a **`## Revision`** section (**append-only** list: `- …` bullets or dated lines).
- **Every** time you write an updated `project.md`, add **at least one** new bullet describing what this edit introduced or changed (e.g. “Added scripts table from `package.json`”, “Expanded illustrative use cases after reviewing `src/extension.ts`”, “Fixed tech stack from `tsconfig`”).
- **First creation** (no prior file): start the section with a line such as **Initial draft** and what was covered in that pass.
- **Later passes:** keep **all** earlier bullets; append **new** bullets at the **bottom** of the list (newest last), unless you adopt ISO date prefixes for sorting—then be consistent.

## Output template

Write **exactly** the content for **`{{OUTPUT_FILE_ABSOLUTE}}`**. **R21:** substantive claims carry **Evidence index** entries with `path:line` or `path:start-end`, or *(inference)* with best cite.

```markdown
# <Product or repo name> — project

## Summary

<!--
  First thing a reader sees after the title. 3–6 sentences (or a few bullets):
  what this repository is, primary audience, main value or outcomes.
  No long lists here — those go below.
-->

## Overall goal

<!--
  North star: mission, problem space, why this codebase exists.
  What success looks like for this repo/product at a high level.
-->

## Illustrative capabilities and use cases

> **Note:** The lists below are **illustrative only**, not an exhaustive inventory of every feature or workflow.

### Representative functionalities

- <!-- capability 1 — e.g. VS Code command, web surface, CLI subcommand, background job -->
- <!-- capability 2 -->
- <!-- add more as needed; stop when coverage feels representative, not encyclopedic -->

### Example use cases

- <!-- UC-style vignette: actor + goal + short outcome, e.g. “Contributor runs tests locally before opening a PR.” -->
- <!-- another example -->
- <!-- optional: link to formal use-case docs if the repo defines them -->

<!--
  Optional: insert one or more additional ## (or ###) sections anywhere among the body (before ## Revision) when they clarify the repository — e.g. "Key workflows", "Analysis pipeline", "CLI vs extension host".
  You may use Mermaid: open a fenced code block with language tag "mermaid"; first line %%{init: {'theme':'neutral'}}%%; then flowchart / sequenceDiagram / graph syntax grounded in the real codebase (Mermaid 11.13, neutral — MERMAID.md). Close the fence. Avoid oversized diagrams. Record diagram/chapter changes in ## Revision.
-->

## Purpose

<!-- What users get; client vs server; data persistence; main user journeys in one paragraph (can elaborate beyond Summary/Goal). -->

## Repository role

<!-- Deployable artefact (e.g. static SPA), how it ships, notable CI/release hooks. -->

## Tech stack

| Area | Choice |
| ---- | ------ |
| … | … |

## Scripts

| Command | Description |
| ------- | ----------- |
| … | … |

## Source layout (high level)

| Path | Role |
| ---- | ---- |
| … | … |

## Configuration and environment

<!-- Key env vars, `.env.example`, feature flags. -->

## Related documentation

<!-- e.g. architecture.md (same context folder), README.md, docs/, .easyspecs/docs/srs/ -->

## Out of scope (current phase)

<!-- Explicit non-goals. -->

## Revision

<!--
  Append-only changelog of edits to this file. Newest entry at the bottom (or use consistent ISO-8601 date prefixes).
  Each time you save an improved version, add at least one new bullet describing what was added or updated.
-->

- <!-- e.g. Initial draft: summary, goal, and tech stack from README + package.json. -->
- <!-- e.g. Added illustrative use cases after reviewing src/commands. -->
- <!-- e.g. Populated source layout table from repository tree. -->

## Evidence index

- <!-- At least one substantive bullet with `path:line` or explanation per Non-empty chapters and Evidence index — never empty. -->
```

## Evidence (**R21**)

Follow **Non-empty chapters and Evidence index** above. Substantive claims carry Evidence index entries with `path:line` or `path:start-end`, or *(inference)* with best cite.

## Prerequisites

Ensure **`<worktree>/.easyspecs/context/`** exists (or create it). Do **not** write `index-application-context.json`.

## Harness wiring

§3.5.1. Set **`{{OUTPUT_FILE_ABSOLUTE}}`** to `join({{WORKTREE_ROOT}}, '.gluecharm', 'context', 'project.md')`. One file per run.

## Distinction from other agents

| Output | Role |
| ------ | ---- |
| **`project.md`** (this agent) | Repo handbook: **summary**, **overall goal**, **illustrative** capabilities & use cases, purpose, stack, scripts, layout, links; **optional** extra chapters + **Mermaid**; **incremental** updates; **`## Revision`** append-only log. |
| **`architecture.md`** (`ctx-md-architecture`) | Application architecture for context assembly / SRS-8 pipeline. |
| **`README.md`** (repo root) | Install quick start; may point readers to deeper docs. |
