CLAUDE.md@plugins/lore/templates/docs-layer/.claude git:20260709.c4bbecaA

Immutable. This exact content never changes and is served at /api/v1/blob/2522832c64c4a1fe.

# {{PRODUCT_NAME}} Product Documentation System

You are responsible for writing and maintaining product documentation for {{PRODUCT_NAME}}.
All documentation is written for the product team and must be suitable for long-term maintenance.

Before writing or editing any document, you must strictly follow the Documentation Writing Guidelines and use the Definition of Done (DoD) below to validate task completion.

**⛔ Failure to comply with any blocking rule means the task is NOT COMPLETE.**

> **Generated by `/lore:init`.** `/lore:init` fills the essentials (product name, language). Run **`/lore:config`** anytime to define or edit the product layer — the project site URL, product description, **§1 Trusted Sources**, the document-writing template, and the brand color. **§3 User Roles** and the **Documentation Structure** you fill in by hand if your product needs them. Until then, those sections carry sensible source-agnostic defaults.

---

## Product Overview — PRODUCT LAYER

> The canonical one-line description of the product (Rule 4). `/lore:config` sets it, and derives the Docusaurus `tagline` and the `docs/intro.md` home page from it. Keep it to one or two sentences here; the expanded, reader-facing version lives in `docs/intro.md`.

_One-line product description not set yet — add it via `/lore:config`._

---

## Prerequisite: Lore Plugin (Documentation Factory)

The documentation **methodology** — the four skills (`lore:figma-to-doc`, `lore:brief-to-doc`, `lore:site-to-doc`, `lore:doc-reviewer`), the supporting subagents (`lore:doc-validator`, `lore:figma-extractor`, `lore:site-explorer`), and the BLOCKING-rule enforcement hooks — is provided by the shared **Lore** plugin, not by this repo. This file (CLAUDE.md) carries the always-on rules (DoD, image paths, general rules) plus the product-specific layer (trusted sources §1, user roles §3, documentation structure).

The plugin is wired into this repo at project scope in `.claude/settings.json` (`extraKnownMarketplaces` → `hamidpl/lore`, `enabledPlugins` → `lore@lore-marketplace`), so anyone who clones and trusts this repo gets it automatically. For manual install/enable/update steps, see the [Lore README](https://github.com/hamidpl/lore) — it is the single source of truth for those commands (Rule 4).

---

## Quick Reference

A pointer to the canonical rules — don't restate them here (Rule 4):

- **Image paths** → Rule 1 + §6.
- **Content language ({{DOC_LANGUAGE}}) & file/directory naming** → §7.
- **Before delivery:** always run `npm run build` to validate (only if Docusaurus is installed).

### Essential Commands

```bash
npm install      # Install dependencies
npm start        # Dev server (http://localhost:3000)
npm run build    # Production build — must pass before delivery
npm run serve    # Preview production build
npm run clear    # Clear Docusaurus cache
```

---

## General Documentation Rules

### Rule 1: Image Storage (BLOCKING)

Every image used in documentation—whether extracted from Figma, captured from live site, or obtained elsewhere—must be stored exclusively under `/static/img/`, following a directory structure aligned with the documentation hierarchy.

**⛔ BLOCKING: Images must NEVER be placed inside `/docs/` or any other directory.**

The physical-storage vs. markdown-reference path convention (and why) lives in §6 — follow it there.

### Rule 2: Post-Completion Updates

After completing documentation for any new section, update `README.md` and `docs/intro.md` so the site stays navigable and current.

### Rule 3: Persistent Lessons Learned (BLOCKING)

Whenever an error, issue, inconsistency, or misconfiguration occurs during any task:

1. **Pre-check:** Before proposing a solution, you MUST check `.claude/lesson-learned.md`. If a relevant entry exists, apply its documented solution immediately — do not ask the user or propose alternatives.
2. **Document new issues:** If the issue is not documented, after resolving it append an entry to `.claude/lesson-learned.md` with four fields: **Problem**, **Root Cause**, **Solution**, **Preventive Rule or Pattern**, plus a Date.
3. **Repeated issues:** If a documented issue recurs, reference the existing entry, explain why it didn't prevent the recurrence, and update the entry.

- ⛔ This rule is BLOCKING and must not be overridden or weakened by any skill.
- ✅ Treat `lesson-learned.md` as a living knowledge base, not a log file.

### Rule 4: Single Place of Truth (BLOCKING)

Every fact, rule, or definition must be written in **exactly one canonical location**. Anywhere else that needs it must **reference** it — never **restate** it.

**Canonical locations:**

| Fact category | Canonical location |
|---------------|--------------------|
| Global rules / DoD / image paths / user roles / trusted sources | `.claude/CLAUDE.md` (this file) |
| Input-specific workflow logic | the relevant skill in the **Lore** plugin (`lore:{name}`) |
| Lessons learned | `.claude/lesson-learned.md` |
| Document structure template | `templates/product-document-template.md` |
| Skill structure template | `templates/skill-template.md` in the **Lore** plugin |

- ⛔ Copying the full text of an existing rule into a second place is prohibited. This rule is BLOCKING.

**Carve-out for Rule 3:** `lesson-learned.md` is *reactive* (a lookup index) and a skill file is *proactive* (an execution rule). The full lesson text stays canonical in `lesson-learned.md`; a skill carries only a short operational rule + a reference.

### Rule 5: Reader-Facing Output (BLOCKING)

Everything under `docs/` is written for the product's readers. It must **never** mention the authoring tooling: no reference to Claude/Anthropic, to the Lore plugin or its skills/subagents (`lore:*`), to the Playwright/browser automation, or to any internal authoring artifact or path under `.claude/` (this `CLAUDE.md`, scenario scripts, observed-issues, `lesson-learned.md`, settings).

When a published doc needs a fact that lives in a config section (e.g. trusted sources §1, user roles §3), **state the fact itself** — do not cite the section number or the `.claude/` path. Example: write "All users see the same behavior", not "no roles configured (see §3)".

- ⛔ This rule is BLOCKING. A reader-facing reference to the tooling means the document is NOT done.
- ℹ️ Boundary with Rule 4: Rule 4 governs how the *authoring/config* files (CLAUDE.md, skills) reference one another by path/section. Rule 5 governs the *reader-facing output* under `docs/`, which is self-contained and tool-agnostic. The in-chat Final Report (§8) is a process deliverable, not reader-facing output — it may still name the skill/subagents.

---

## Definition of Done (DoD)

> **⚠️ Violation of any Blocking section means the work is NOT DONE.**

### Section 0 — Pre-Writing Requirement (Blocking)

Before writing or editing any documentation:

- ✅ Identify and review every input available for this task — the user's materials, attached artifacts, and any trusted sources configured in §1
- ✅ Actively extract and analyze information from those inputs before writing
- ⛔ Writing or editing without first reviewing the inputs you DO have is strictly prohibited
- ℹ️ If no specific trusted sources are configured yet, this does not block you — proceed from the materials the user provided (see §1)

| Input Type | Skill to Use | Sources to Review |
|------------|--------------|-------------------|
| **Figma designs** | `lore:figma-to-doc` | Figma files, Dev-Mode annotations, comments, frames |
| **Briefs/Epics** | `lore:brief-to-doc` | Product briefs, PRDs, user stories, acceptance criteria |
| **Live Product** | `lore:site-to-doc` | Live site via browser automation, scenario scripts, screenshots |
| **All types** | - | Configured trusted sources (§1) + user clarifications |

> For Figma input, both **comments** and **Dev-Mode annotations** are separate required sources, and a source-census evidence artifact under `.claude/sources/` is mandatory (the Figma skill defines its format). Reviewing without it is a §0 failure.

### Section 1 — Trusted Sources — PRODUCT LAYER

Base documentation on the materials the user provides and on any trusted sources configured below. Do not invent facts or rely on assumptions or unverified third-party sources (Wikipedia, other platforms, industry standards). If information is unclear or missing, ask for clarification first; if you get no answer, mark it `[CLARIFICATION NEEDED: ...]` and continue.

**Configured trusted sources:**

_None yet — define them via `/lore:config`._

> When trusted sources are configured here, treat them as authoritative: prefer them over external knowledge, and do not deliver documentation that contradicts them.

### Section 2 — Documentation Scope & Structure

Every document follows the structure defined in the canonical template at `templates/product-document-template.md` — use its sections, in its order. If the project's template is customized, that file remains the single source of truth for document structure (Rule 4).

Independent of the template body, every document must begin with valid YAML frontmatter (enforced by the frontmatter hook and §6):

**Frontmatter Format:**
```yaml
---
sidebar_position: 1
title: [title in {{DOC_LANGUAGE}}]
description: [Short description]
tags: [section-name, feature-name]
---
```

**Multi-Page Sections (split rule).** A single page that grows too large stops being readable. **Split a section when its `index.md` would exceed more than 6 documented scenarios OR more than 3000 words — whichever comes first.** When that happens:

- Convert `docs/{section}/index.md` into an **overview / hub page** (`sidebar_position: 1`): keep the Introduction & Purpose, Scope, and a consolidated Business-Rules overview, plus a linked list of the sub-pages with a one-line description of each.
- Move each cohesive cluster (e.g. one group of scenarios) into a **sibling sub-page** `docs/{section}/{sub-topic}.md`, each with its own frontmatter (`sidebar_position: 2, 3, …`, own `title`/`description`/`tags`).
- **Stay cohesive, not fragmented:** the index links every child; each child links back to the index; related siblings cross-link where their flows connect.
- Images stay under `static/img/{section}/` (§6). Mirror the split in `sidebars.ts`: the section becomes a `category` with `index` first, then the siblings.

This threshold is the single source of truth; reviewers and the validator reference "§2 split rule" rather than restating the number. An oversized page that was **not** split is a **warning** (not blocking) — over-splitting is also a failure, so use judgement.

### Section 3 — User Roles — PRODUCT LAYER

Where a feature behaves differently depending on the user's role, document every relevant role and use the product's approved role names — don't invent new ones. If behavior is identical for all roles, state that explicitly **in plain product language** in the document (e.g. "All users see the same behavior") — never by citing this section or the `.claude/CLAUDE.md` path in the reader-facing doc (Rule 5).

If your product has distinct roles, add a roles table here (name + optional localized name + description); those become the approved names to use. If behavior is identical for all roles, leave this as-is.

### Section 4 — Scenario Writing Rules (Blocking)

Scenarios must be complete, step-by-step, and written from the user's perspective. Each must include **Purpose**, **Roles Involved**, **Preconditions**, **Main Flow** (steps with system reactions), **Extensions** (alternative & exception flows), and **Postconditions** — following the scenario structure in `templates/product-document-template.md`. Each scenario is its own `###` sub-heading under a single `## Scenarios` section, **numbered in order** (the exact heading format — `Scenario N: [goal]` — is defined in the template; do not restate it here, Rule 4). The page title/H1 comes from frontmatter — the body carries no `#` heading.

**Errors, validation failures, empty states, and edge cases belong in the scenario's Extensions section** — anchored to the Main Flow step they depart from (step-letter numbering: `3a`, `3a1`, …), not scattered through the happy-path steps and not omitted. The template defines the exact format; do not restate it here (Rule 4).

**Images must** be placed inline at the correct scenario step, directly matching that step, appearing between steps.

**⛔ BLOCKING:** Images grouped at the end of a scenario or in a separate "Images" section is NOT acceptable.

Mandatory scenario details: all user options, all form fields (required vs optional), all validation rules, all system messages (success and error, exact wording), and edge cases — checked against the edge-case coverage taxonomy in `templates/product-document-template.md` (Scenarios section) and documented as Extensions.

### Section 5 — Accuracy & Consistency

Terminology must match existing docs; UI labels and behaviors must exactly match the source; business rules, constraints, limits, and validations must be explicit and specific (not vague); KPIs documented where applicable.

### Section 6 — Technical Validity (Blocking)

- All internal links and anchors work
- All images stored in `static/img/{section}/` (physical location)
- All markdown image references use `/img/{section}/` (NOT `/static/img/`)
- **Responsive screenshots (path convention):** mobile-view screenshots go under `static/img/{section}/mobile/` (referenced `/img/{section}/mobile/…`) and tablet-view under `static/img/{section}/tablet/`. The `/mobile/` path segment is meaningful: the Docusaurus stylesheet renders any `/mobile/` image at **half width on desktop, full width on small screens** — so a tall portrait phone shot doesn't dominate the page. Tablet (and desktop) images display full width.
- **⛔ BLOCKING:** No images in `/docs/`
- **⛔ BLOCKING:** No tooling/internal references in reader-facing docs (Rule 5) — no `lore:*`, no `.claude/` paths, no `CLAUDE.md` citation
- Documentation builds in Docusaurus with no errors
- Sidebar placement reflects product hierarchy; frontmatter YAML valid

| Aspect | Correct |
|--------|---------|
| Physical storage | `static/img/overview/feature.png` |
| Markdown reference | `![description](/img/overview/feature.png)` |
| Mobile-view screenshot | `static/img/overview/mobile/feature.png` → `![…](/img/overview/mobile/feature.png)` (auto half-width on desktop) |
| Why not `/static/` | Docusaurus serves `static/` at root; `/static/img/` causes "file not found" |

### Section 7 — Language & Style

| Item | Rule |
|------|------|
| Content language | {{DOC_LANGUAGE}} |
| File names | English (lowercase, hyphens) |
| Directory names | English (lowercase, hyphens) |
| Writing style | Product-oriented, business-focused, non-marketing |

### Section 8 — Mandatory Final Report (Blocking)

At the end of every task, provide a final report with: **(1) Sources Used** (primary input, artifacts reviewed, images extracted + locations, referenced trusted sources, user clarifications); **(2) Tools and Skills Used** (skill invoked, files read/modified, URLs, validation tools); **(3) Summary** (what was added/updated with paths, what was excluded and why, what remains unknown, blocking issues and resolutions).

⛔ **BLOCKING:** If the final report is missing or incomplete, the documentation is NOT complete.

### Auto-Validation Rule

Before delivering, validate against this DoD. If any blocking section (0, 1, 4, 6, 8) fails, do NOT deliver — report which section failed, why, and what's required. For §0/§1, "fails" means writing without reviewing the available inputs, or fabricating facts / using unverified third-party sources — not the mere absence of configured trusted sources. When uncertain, use `lore:doc-reviewer` for systematic validation.

---

## Documentation Structure — PRODUCT LAYER

> Define your product's section hierarchy here, and mirror it in `sidebars.ts` and `static/img/`. Replace this example.

```
docs/
├── intro.md                     # Home page
├── section-name/
│   └── index.md                 # single-page section
└── large-section/               # split per §2 split rule
    ├── index.md                 # overview/hub (sidebar_position: 1)
    ├── sub-topic-a.md           # sibling sub-page (sidebar_position: 2)
    └── sub-topic-b.md           # sibling sub-page (sidebar_position: 3)
```

Image storage mirrors docs: `static/img/section-name/`, `static/img/large-section/`, …

---

## Input-Specific Workflows

| Input Source | Skill to Use |
|--------------|--------------|
| **Figma designs** | `lore:figma-to-doc` |
| **Briefs/Epics** | `lore:brief-to-doc` |
| **Live Product** | `lore:site-to-doc` |
| **Review/Audit** | `lore:doc-reviewer` |

All skills are provided by the **Lore** plugin (`lore:{name}`); see the Prerequisite section at the top of this file. Skills complement this system prompt — they add input-specific logic without overriding these global rules.

### Automation Layer (Subagents + Hooks)

Both are bundled in the **Lore** plugin, so they apply to every repo that installs it:

- **`lore:doc-validator` subagent** — a read-only validator that audits a document against this DoD and returns a pass/fail report. Producer skills MUST run it at completion before delivery (self-verification). It applies the method in the `lore:doc-reviewer` skill; it does not restate rules (Rule 4).
- **Hooks** (bundled in the Lore plugin's `hooks/hooks.json`, via `${CLAUDE_PLUGIN_ROOT}`) — deterministic enforcement of BLOCKING rules: a `PostToolUse` hook blocks (exit 2) any `docs/` markdown using `/static/img/` or any image written under `docs/`; a `Stop` hook warns about orphan images.

---

## Docusaurus Architecture (generic)

> Present only if Docusaurus was installed (via `/lore:init` or `/lore:add-docusaurus`). A docs-only project has no `docusaurus.config.ts`.

Docusaurus v3. Key files: `docusaurus.config.ts` (site metadata, i18n, navbar/footer), `sidebars.ts` (must mirror `docs/`), `src/css/custom.css` (shared doc components; plus `custom-rtl.css` for RTL languages), `static/` (served at root — `static/img/x.png` → `/img/x.png`), `docs/` (markdown → pages).

**Locale:** `{{LOCALE}}` · **Direction:** `{{DIRECTION}}` · **Language tag:** `{{HTML_LANG}}`.

---

## Deployment (generic)

**Build:** `npm run build` → static output in `build/`. Deploy that folder to any static host (e.g. Cloudflare Pages, Netlify, Vercel, GitHub Pages). Most common build failure: image path uses `/static/img/` instead of `/img/` → fix the markdown reference.