# Prompt — Add or update a context document

Use this when adding a doc to `.meshkore/docs/`. Follow R1-R6 governance
strictly. Ask the user to clarify category and scope before writing.

---

## 1 · Ask the user

### Q1 — What is the document about?

Get a one-line topic in the user's words. Examples:
- "How our payments protocol works"
- "Why we chose DragonflyDB"
- "The schema of the agents table"

### Q2 — What category does it fit?

Show the seven options from R1:

```
1. architecture — how the system is built (technical)
2. product      — strategy, growth, vertical positioning
3. conventions  — namespaces, taxonomies, hard rules
4. modules      — one file per module of the codebase
5. deploy       — deploy procedures, runbooks
6. security     — threat model, audits, mitigations
7. ops          — day-to-day, issues, testing, runbooks
```

Suggest one based on Q1's topic. Confirm with the user.

### Q3 — Does anything similar already exist?

Run before writing:

```bash
grep -ril "<keywords-from-Q1>" .meshkore/docs/
```

If hits → ask the user: "There's already
`.meshkore/docs/<found>.md`. Edit that one (recommended, R3) or write a
new one (only if the new doc is genuinely different)?"

---

## 2 · Plan the file

- **Slug**: lowercase, hyphenated, ≤30 chars, descriptive.
- **Path**: `.meshkore/docs/<category>/<slug>.md`
- **Sub-subfolder?** Only if there's already a precedent
  (`architecture/protocols/` exists; new ones need user approval).

Show the user the planned path before writing.

---

## 3 · Frontmatter (R4 — always)

```yaml
---
title: "Human-readable title (matches the H1 below)"
category: <category-from-Q2>
tags: [tag1, tag2]
updated: <today-YYYY-MM-DD>
owner: <your-identity>
status: stable                # use 'draft' if you'll iterate
related: []                    # paths under docs/, fill if obvious
---
```

The body starts with `# <Title>` (matches the frontmatter title).

---

## 4 · Write the body

R2 — aim for 50-150 lines, **hard cap 200**.

Style:
- No emojis.
- No marketing fluff. Audience: internal devs and AI agents — both want
  signal density.
- Active voice, present tense.
- Code blocks with language tags.
- Cross-reference, don't restate (R5).

If the doc would exceed 200 lines:
1. Identify the natural split.
2. Either split into multiple files, or create a sub-subfolder.
3. Confirm the split plan with the user before writing.

---

## 5 · Cross-reference (R5)

After writing the body:

- For every external concept you mentioned: find the canonical doc and
  add it to your `related:` field.
- Update the `related:` field of those other docs to include yours
  (bidirectional).

---

## 6 · Validate

```bash
python3 .meshkore/scripts/roadmap-build.py --validate
```

Fix any warnings about your file. Then regenerate `state.json`:

```bash
python3 .meshkore/scripts/roadmap-build.py
```

The portal will pick up the new doc on next refresh.

---

## 7 · Things you must NEVER do

- Write a doc about a current task. Tasks live in
  `.meshkore/roadmap/tasks/`, not `docs/`. If you find yourself writing
  "what we're doing right now", you wanted a task, not a doc.
- Write a daily log here. Daily logs go in
  `.meshkore/roadmap/log/<YYYY-MM>/`.
- Duplicate content from `agent_docs.rs` (the live agent docs at
  `hub.meshkore.com/platform/docs/agent/*`). Link, don't copy.
- Commit credentials, tokens, or env vars.
- Skip the frontmatter. Even if it feels redundant for a small file.

---

## See also

- [`.meshkore/docs/governance.md`](../../.meshkore/docs/governance.md) — R1-R6 in detail
- [`.meshkore/docs/conventions/frontmatter.md`](../../.meshkore/docs/conventions/frontmatter.md) — frontmatter schema
- [`/standard.md`](https://meshkore.com/standard.md) — public copy