org-documentation

What this skill does

# LimaCharlie Organization Documentation Generator

Generate complete, wiki-ready architecture and operations guides for one or more LimaCharlie organizations. Supports single org, multiple orgs by name or OID, or all accessible orgs.

***

## LimaCharlie Integration

> **Prerequisites**: Run `/init-lc` to initialize LimaCharlie context.

### LimaCharlie CLI Access

All LimaCharlie operations use the `limacharlie` CLI directly:

```bash
limacharlie <noun> <verb> --oid <oid> --output yaml [flags]
```

For command help and discovery: `limacharlie <command> --ai-help`

### Critical Rules

| Rule | Wrong | Right |
|------|-------|-------|
| **CLI Access** | Call MCP tools or spawn api-executor | Use `Bash("limacharlie ...")` directly |
| **Output Format** | `--output json` | `--output yaml` (more token-efficient) |
| **Filter Output** | Pipe to jq/yq | Use `--filter JMESPATH` to select fields |
| **Timestamps** | Calculate epoch values | Use `date +%s` or `date -d '7 days ago' +%s` |
| **OID** | Use org name | Use UUID (call `limacharlie org list` if needed) |
| **Secrets** | Include values in docs | Only document secret **names**, NEVER values |

***

## Overview

This skill generates a complete set of markdown documentation files for a LimaCharlie organization, suitable for upload to a GitHub wiki, MkDocs site, or Confluence. The output covers:

- System architecture and data flow diagrams (Mermaid)
- Sensor inventory (EDR, extensions, cloud adapters)
- D&R rule catalog organized by category
- AI agent teams, workflows, and inter-agent communication
- Extension subscriptions and data pipeline
- Access control (API keys, secrets, installation keys, SOPs)
- Operational runbooks for day-to-day administration
- Automation scripts for keeping documentation current

## When to Use

- **"Document this org"** / **"Create architecture docs for white-sands"**
- **"Generate a wiki for all my orgs"** / **"Document all organizations"**
- **"Create docs for white-sands and red-rock"** (multiple by name)
- **"Document orgs b85fd2bd-... and c1ffedc0-..."** (multiple by OID)
- **"Create onboarding documentation for a new SOC engineer"**
- **"Audit the org configuration and produce a report"**
- **"Export org architecture to markdown"**

## Workflow

### Phase 1: Gather Requirements

1. **Identify the target organization(s)**. The user may specify:
   - A single org by name or OID
   - Multiple orgs by name or OID (comma-separated or listed)
   - "all" / "all orgs" / "every org" to document all accessible organizations

   First, list all accessible orgs to resolve names to OIDs:
   ```bash
   limacharlie org list --output yaml
   ```

   **Resolving org identifiers:**
   - If the user provides a UUID (matches `[0-9a-f-]{36}`), use it directly as the OID
   - If the user provides a name, match it against the `name` field from `org list`
   - If the user says "all", use every org returned by `org list`
   - If an org name doesn't match, ask the user to clarify — never guess

2. **Ask where to write the output**:
   - Single org: default `./docs/<org-name>/`
   - Multiple orgs: default `./docs/` with subdirectories per org: `./docs/<org-name>/`
   Confirm with the user.

3. **Check for optional GitHub repo creation**: Ask if they want the docs pushed to a new GitHub repo.

### Phase 2: Collect Organization Data

Spawn one `org-doc-collector` sub-agent **per organization** to gather the full configuration inventory. For multiple orgs, spawn ALL agents in a **SINGLE message** for parallel execution.

**Single org:**
```
Task(
  subagent_type="lc-advanced-skills:org-doc-collector",
  prompt="Collect full configuration inventory for organization '<org-name>' (OID: <oid>)."
)
```

**Multiple orgs (spawn ALL in parallel in one message):**
```
Task(
  subagent_type="lc-advanced-skills:org-doc-collector",
  prompt="Collect full configuration inventory for organization '<org-1-name>' (OID: <oid-1>)."
)
Task(
  subagent_type="lc-advanced-skills:org-doc-collector",
  prompt="Collect full configuration inventory for organization '<org-2-name>' (OID: <oid-2>)."
)
// ... one per org, all in the same message
```

Each agent returns a structured YAML document with all sensors, rules, agents, extensions, etc.

### Phase 3: Generate Documentation Files

For **each organization**, generate a complete set of documentation files under `<output-dir>/<org-name>/`. Use the templates below as the structure — populate them with the actual data from that org's collector agent.

If documenting multiple orgs, also generate a top-level `README.md` index at `<output-dir>/README.md` that links to each org's documentation:

```markdown
# LimaCharlie Organization Documentation

| Organization | OID | Docs |
|--------------|-----|------|
| <org-1-name> | `<oid-1>` | [View docs](<org-1-name>/README.md) |
| <org-2-name> | `<oid-2>` | [View docs](<org-2-name>/README.md) |
```

**Files to generate:**

| File | Content |
|------|---------|
| `README.md` | Main entry point with badges, Mermaid overview, navigation flowchart |
| `architecture.md` | System topology, data flow diagrams for each pipeline |
| `sensors.md` | EDR sensors, extension sensors, tags, health monitoring |
| `detection-rules.md` | D&R rules by category with chaining diagram and pie chart |
| `ai-agents.md` | Agent teams, pipeline flows, budgets, secrets mapping |
| `data-pipeline.md` | Extensions, cloud adapters, outputs, lookups, payloads |
| `access-control.md` | API keys, secrets, installation keys, SOPs, rotation checklist |
| `runbooks/common-admin-tasks.md` | Day-to-day CLI operations |
| `runbooks/incident-response.md` | How the SOC pipeline handles incidents |
| `runbooks/updating-docs.md` | Export script, CI workflow, review cadence |

### Phase 4: Optional GitHub Push

If the user requested GitHub repo creation:

1. Confirm the GitHub account and repo name
2. Create the repo: `gh repo create <account>/<repo-name> --private`
3. Initialize git in the output directory, commit all files, and push
4. Ensure no sensitive data (secret values, webhook URLs, IPs) is committed
5. For multi-org docs, push all org subdirectories + the top-level index as a single repo

### Error Handling (Multi-Org)

If one org's collector agent fails:
- Document the failure in the top-level README index
- Continue generating docs for all other orgs
- Report which orgs succeeded and which failed at the end

***

## Documentation Templates

### Template: README.md

```markdown
# <Org-Name> Organization — Architecture & Operations Guide

![Org: <org-name>](https://img.shields.io/badge/Org-<org-name-url-encoded>-blue)
![OID](https://img.shields.io/badge/OID-<oid-abbreviated>-lightgrey)
![Last Updated](https://img.shields.io/badge/Last_Updated-<YYYY--MM--DD>-green)
![Owner](https://img.shields.io/badge/Owner-SOC_Engineering-purple)

Complete operational reference for the **<org-name>** LimaCharlie organization.

> [!IMPORTANT]
> **OID**: Always use `<oid>` (never the org name) in all CLI commands.
> All commands require `--output yaml`. Timestamps in API params are epoch **seconds** (10 digits).

***

## Architecture at a Glance

<!-- Mermaid flowchart showing: Data Sources → D&R Engine → AI Agent Teams → Outputs -->
<!-- Adapt based on what actually exists in the org -->

***

## Where Do I Start?

> New to LimaCharlie? Start with the [Quickstart Guide](https://docs.limacharlie.io/1-getting-started/quickstart/) and [Core Concepts](https://docs.limacharlie.io/1-getting-started/core-concepts/).

<!-- Mermaid decision flowchart linking to each doc file -->

***

## Documentation Map

| | Document | Description |
|---|----------|-------------|
| **Core** | [Architecture Overview](architecture.md) | System topology and data flow |
| **Core** | [Sensors & Endpoints](sensors.md) | EDR, extensions, cloud adapters |
| **Core** | [Detection & Response Rules](detection-rules.md) | Rule catalog by category |
| **Core** | [AI Agents & Automation](ai-agents.md) | Agent teams