> ## Documentation Index
> Fetch the complete documentation index at: https://docs.younegotiate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation Style Guide

> How YouNegotiate product documentation should be written and maintained.

These docs are not only feature descriptions. They are product behavior contracts for non-technical readers, product owners, QA, and developers.

<Info>
  The goal is to explain the real user scenario, the expected flow, what must never happen, and what developers should protect when changing the feature.
</Info>

## Page Structure

Every portal feature page should use this order:

| Section                  | Use                                                               |
| ------------------------ | ----------------------------------------------------------------- |
| `Real-World Example`     | A practical story using a creditor, consumer, or admin situation. |
| `Visual Flow`            | Mermaid flow showing the expected path and key decisions.         |
| `How It Should Work`     | Plain-language rules for correct behavior.                        |
| `How It Should Not Work` | Guardrails, unsafe states, and regressions to avoid.              |
| `Developer Notes`        | Optional. Add when the feature has special implementation rules.  |
| `Related App Areas`      | Optional. Add source hints when developers need a starting point. |

## Real-World Examples

Good examples should feel like this:

> ABC Collections imports 1,000 consumer accounts. Jane accepts an offer and makes a payment. The dashboard count changes, payment metrics update, and Jane eventually moves from open activity to completed activity.

Avoid examples like this:

> The dashboard updates when data changes.

The second example is true, but it does not help a person understand the product.

## Visual Flow Colors

Use the same color meaning everywhere. Keep the legend compact so it supports the page instead of taking over the page.

| Label                                                                                                                                                               | Meaning                                                | Use it for                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------- |
| <span style={{ background: "#E0F2FE", border: "1px solid #0284C7", color: "#0C4A6E", borderRadius: "999px", padding: "2px 10px", fontWeight: 600 }}>Actor</span>    | A user, consumer, creditor, or admin starts an action. | The first human or portal actor in the flow.                      |
| <span style={{ background: "#F8FAFC", border: "1px solid #64748B", color: "#0F172A", borderRadius: "999px", padding: "2px 10px", fontWeight: 600 }}>System</span>   | Normal application processing.                         | Saved records, background work, routing, and updates.             |
| <span style={{ background: "#FEF3C7", border: "1px solid #D97706", color: "#78350F", borderRadius: "999px", padding: "2px 10px", fontWeight: 600 }}>Decision</span> | A rule check or branch.                                | Eligibility, setup completeness, payment success, opt-out checks. |
| <span style={{ background: "#FEE2E2", border: "1px solid #DC2626", color: "#7F1D1D", borderRadius: "999px", padding: "2px 10px", fontWeight: 600 }}>Risk</span>     | Blocked, failed, unsafe, or missing behavior.          | Anything the product must prevent or surface clearly.             |
| <span style={{ background: "#DCFCE7", border: "1px solid #16A34A", color: "#14532D", borderRadius: "999px", padding: "2px 10px", fontWeight: 600 }}>Outcome</span>  | A successful result or updated state.                  | What should be true after the flow completes.                     |

## Documentation Workflow

When product behavior changes, update the matching documentation page in the same work cycle.

```mermaid placement="top-right" actions={true} theme={"system"}
flowchart TD
    A["Product or code behavior changes"] --> B["Find matching sidebar docs page"]
    B --> C["Update real-world example if user behavior changed"]
    C --> D["Update visual flow if sequence changed"]
    D --> E["Update should/should-not rules"]
    E --> F["Add developer notes if implementation risk exists"]
    F --> G["Review page as a non-technical reader"]
    classDef default fill:#F8FAFC,stroke:#64748B,stroke-width:1.5px,color:#0F172A;
    classDef actor fill:#E0F2FE,stroke:#0284C7,stroke-width:2px,color:#0C4A6E;
    classDef system fill:#F8FAFC,stroke:#64748B,stroke-width:1.5px,color:#0F172A;
    classDef decision fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F;
    classDef risk fill:#FEE2E2,stroke:#DC2626,stroke-width:2px,color:#7F1D1D;
    classDef outcome fill:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#14532D;
    class A actor;
    class B,C,D,E,F system;
    class G outcome;
    linkStyle default stroke:#94A3B8,stroke-width:2px;
```

## Naming Rules

* Mirror the app sidebar as folders and files.
* Use lowercase kebab-case file names.
* Use the readable product label as the page title.
* Prefer one page per menu item.
* Keep `index.md` pages for navigation and portal summaries.

## Developer Notes

Add `Developer Notes` when a feature has hidden behavior, background jobs, payment effects, cache counts, access rules, or status transitions.

Examples:

* Sidebar badges depend on cached counts.
* Payment retries should not duplicate charges.
* Consumer data must stay scoped to the creditor and sub-account.
* A page appears only for parent accounts or only when setup is incomplete.

## Related App Areas

Add `Related App Areas` when developers need a source starting point, but keep it light.

Good:

```md theme={"system"}
## Related App Areas

- Routes: `routes/creditor/index.php`
- Background schedule: `app/Console/Kernel.php`
```

Avoid turning docs into technical implementation notes. The codebase remains the source of truth for exact implementation.

## Screenshots

Screenshots are useful only when a visual state helps developers, QA, or product understand behavior that is hard to explain with text and Mermaid alone.

Use screenshots for:

* Dense list or dashboard pages where tabs, filters, badges, and row actions matter.
* Multi-step flows where the UI state affects the next system action.
* Detail pages where several backend resources appear in one screen.

Avoid screenshots for simple forms, static copy, or pages that change often. If a screenshot is added, crop it to the relevant area, use demo data only, avoid PII and payment details, and include alt text that describes the state being shown.

## Definition Of Done

A docs page is ready when:

* A non-technical reader can understand the feature.
* A developer can understand the behavior they must preserve.
* The real-world example uses a concrete portal situation.
* The visual flow shows the main path and important risks.
* The should/should-not lists are specific enough to catch regressions.