---
name: project-docs
description: The single self-contained master skill for initiating or updating all project documentation across Gitea, Obsidian, Mermaid/Archify, Vikunja, and Outline. Handles technical READMEs, human portfolio notes, architecture diagrams & Archify maps, task tracking, and AI context catalogs using Simplified Technical English (ste-writing).
version: 2.0.0
---

# project-docs (Unified Project Lifecycle & Documentation Master Skill)

`project-docs` is the **single entry point** for all project documentation across your stack. You do not need to load separate diagramming or documentation skills — `project-docs` handles everything natively.

To enable on any project:
```bash
/config-add skill project-docs
/reload
```

---

## 🎯 Platform Roles & Output Matrix

When invoked, `project-docs` coordinates five documentation layers:

| Platform | Target Audience | Purpose & Tone | Generated / Updated Artifacts |
| :--- | :--- | :--- | :--- |
| **Gitea** | Developers / Resume | Technical documentation & repository README. **Standard concise markdown**. Highlights tech stack, usage, and key tools/skills demonstrated for employment. | `<project>/README.md` (embedded Mermaid diagram, Archify links, setup/usage guide). |
| **Obsidian** | Humans / Hiring Managers | **Human understanding**. Simple, clear, layperson-friendly language, brief. Highlights skills, tools, and concepts that showcase for employment while forming a usable tool for understanding things. | A note written into `010 inbox/` on host **`.27`** (simple overview, employment highlights, embedded Mermaid). The **`obsidian-sorter`** skill files it into `200 projects/<category>/` and updates the Table of Contents. |
| **Mermaid + Archify** | Architectural Visualization | High-level system architecture and interactive HTML maps. | 1. `<project>/docs/<topic>.mmd`<br>2. `<project>/docs/diagrams/<topic>.png` (rendered via `mmdc`)<br>3. `<project>/docs/<topic>-map.html` (rendered via Archify)<br>4. Published to `https://maps.lab.audasmedia.com.au/<project>/docs/`. |
| **Vikunja** | Humans | **High-level task tracking**. Simple, brief, actionable human steps (milestones, key deliverables). | Vikunja project board or `<project>/docs/vikunja-tasks.json`. |
| **Outline** | AI Agents | **Deep AI context & document index**. Itemizes what is in each document in the collection so AI agents can inject specific files directly without searching. **Strictly uses `ste-writing` skill rules** (Simplified Technical English). | `<project>/docs/outline/` collection (`00-index.md`, `01-system-overview.md`, `02-config-and-env.md`, `03-code-map.md`, `04-agent-runbook.md`). |

---

## 🔄 Modes of Operation

### Mode 1: Initiate (New Project Bootstrap)
Audits the current workspace and interactively prompts the user for each platform before generating clean initial docs from bundled templates.

### Mode 2: Update (Keep Docs in Sync)
Scans git commits, file edits, or structural changes, then updates affected documentation across Gitea, Obsidian, Mermaid/Archify, Vikunja, and Outline.

---

## 📋 Interactive Discovery & Confirmation Protocol

For every project, step through the 5 platforms and **ask/confirm** before writing:

1. **Gitea**: *"Does a Gitea repository exist for this project, or should it be created? [Repo Name]"*
2. **Obsidian**: *"Should an Obsidian project note be created for human understanding and portfolio showcase? [Confirm / Note Name]"*
   - Write it to `~/obsidian/010 inbox/` **on `.27`** using the note template.
   - **Do not choose a folder or a type.** The `obsidian-sorter` skill proposes the
     destination and the vault owner approves it. See the `obsidian-sorter` skill.
3. **Mermaid & Archify**: *"Do you want a Mermaid architecture diagram and Archify interactive map for this project? [Confirm / Topic Name]"*
4. **Vikunja**: *"Should a Vikunja project/board be created for human task tracking? [Confirm / Board Name]"*
5. **Outline**: *"Should an Outline document collection be created for AI agents to resume context across restarts? [Confirm / Collection Name]"*

---

## 📐 Native Diagramming & Archify Execution Workflow

`project-docs` handles diagram generation and rendering natively using system tools:

### Step 1: Write Mermaid Source
Write source to `<project>/docs/<topic>.mmd`. Include click links to the published Archify map:
```mermaid
flowchart LR
    U[User / Client] --> UI[Web Interface]
    UI --> API[API Gateway]
    API --> DB[(Database)]

    click API "https://maps.lab.audasmedia.com.au/{{PROJECT_NAME}}/docs/" "View Archify Map"
    click DB "https://maps.lab.audasmedia.com.au/{{PROJECT_NAME}}/docs/" "View Archify Map"
```

### Step 2: Render Image Files via mmdc
```bash
mkdir -p <project>/docs/diagrams
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.png --scale 2 -b white
```

### Step 3: Render Interactive Archify HTML Map
Use the bundled Archify engine (`~/.agents/skills/archify/`):
```bash
# 1. Author JSON IR at <project>/docs/archify/<topic>.architecture.json
# 2. Validate IR
node ~/.agents/skills/archify/bin/archify.mjs validate architecture <project>/docs/archify/<topic>.architecture.json --quality showcase --json

# 3. Deliver HTML Map
node ~/.agents/skills/archify/bin/archify.mjs deliver architecture <project>/docs/archify/<topic>.architecture.json <project>/docs/<topic>-map.html --quality showcase --json
```

### Step 4: Publish to LAN Maps Site
```bash
~/.agents/skills/project-docs/scripts/publish-maps.sh [<project-dir>]
```
Uploads `<project>/docs/` to `https://maps.lab.audasmedia.com.au/<project>/docs/`.

---

## ✍️ Outline & `ste-writing` Rules

Outline documentation **MUST** enforce ASD-STE100 Simplified Technical English (`ste-writing` rules):

1. **Terse & Concise**: Maximum 20-25 words per sentence. No filler words or AI slop ("utilize", "robust", "seamless", "ensure").
2. **Active Voice**: "The server reads the file" (not "The file is read by the server").
3. **Itemized Document Catalog**: The index document (`00-index.md`) MUST itemize every document in the collection with its file path and 1-sentence scope so AI agents can inject exact files without searching.

### Example Outline Document Catalog (`00-index.md`)

```markdown
# {{PROJECT_NAME}} — AI Document Index

> **Target**: AI Agents  
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).

## 📚 Document Catalog (Inject Specific Document)
Read this index to inject the exact file you need. Do not search all files.

| Document Title | Path | Scope / Description |
| :--- | :--- | :--- |
| **System Overview** | `docs/outline/01-system-overview.md` | Explains project purpose, main architecture, and active services. |
| **Configuration & Env** | `docs/outline/02-config-and-env.md` | Lists environment variables, config paths, network ports, and secrets. |
| **Code Structure Map** | `docs/outline/03-code-map.md` | Shows folder structure, core entry points, and primary dependencies. |
| **AI Agent Runbook** | `docs/outline/04-agent-runbook.md` | Gives step-by-step commands to build, test, and restart agent work. |
```

---

## 🛠 Script & Template References

Templates live in `~/.agents/skills/project-docs/templates/`:
- `templates/gitea-readme.md.tpl`
- `templates/obsidian-note.md.tpl`
- `templates/outline-ai-context.md.tpl`
- `templates/vikunja-tasks.json.tpl`
- `templates/mermaid-archify.mmd.tpl`

---

## 🚀 Activation & Usage Summary

```bash
# Enable in project
/config-add skill project-docs
/reload

# Initiate or Update
"Initiate documentation for this project"
"Update project documentation across Gitea, Obsidian, Vikunja, and Outline"
```