# OSS Documentation Cleanup Plan (MAESTRO)

Status: PLAN (audit + execution checklist). Branch: `docs/oss-cleanup`.
Author: docs audit pass, 2026-06-10.

This plan audits MAESTRO's documentation against GitHub/OSS publishing
conventions and the repo owner's HTML-staged-docs preference, and lays out a
concrete, ordered execution path. It does **not** change any shipping docs; the
only new files on this branch are this plan and two clearly-labeled DRAFT stubs
(`docs/README.en.draft.md`, `docs/SECURITY.draft.md`).

## How OSS publishing actually works (verified)

`scripts/oss-sync.sh` builds the public tree from `git archive HEAD`, then:

1. removes every path in `oss/exclude.txt` (CLAUDE.md, `docs/superpowers`,
   `docs/plans`, dated internal docs, `oss/` itself, sync tooling, editor configs);
2. scrubs internal hostnames/IPs via `oss/scrub.sed`;
3. strips dead links to excluded docs via `oss/scrub-deadlinks.py`;
4. overlays `oss/overlay/.` last (public-only files **win**);
5. runs a release gate (`oss/verify_release.py` + `oss/forbidden.txt`).

So the **public** doc set = (tracked docs that survive exclude) **+** the
overlay. The overlay is the source of truth for the public-facing files. The
tracked root `README.md` is the **private** README and is *replaced* by
`oss/overlay/README.md` (README is overlaid, not excluded). Anything authored
for the public must land in `oss/overlay/` or in a tracked `docs/` path that is
**not** excluded.

Implication for this cleanup: most "public-facing" doc work means editing files
under `oss/overlay/`, not the tracked root files.

---

## A. INVENTORY

Audience = who the doc is for. OSS-ships = `overlay` (public-only file),
`tracked` (survives exclude and ships as-is), or `excluded` (removed by
`oss/exclude.txt`). Language as of today.

### Top-level files

| Path | Audience | Lang | OSS-ships? | Verdict |
|------|----------|------|-----------|---------|
| `README.md` (tracked root) | internal | JA | replaced by overlay README | keep as private; **not** public |
| `oss/overlay/README.md` | public | **JA** | overlay (becomes public README) | **translate→EN-first** + add badges/screenshot |
| `oss/overlay/AGENTS.md` | public (contributors) | EN | overlay | keep |
| `oss/overlay/CONTRIBUTING.md` | public | EN | overlay | keep (add CoC + DCO/CLA note) |
| `oss/overlay/SECURITY.md` | public | EN | overlay | keep (good) |
| `oss/overlay/CHANGELOG.md` | public | EN | overlay | keep (date stale: dated 2026-06-02) |
| `oss/overlay/LICENSE` | public | EN | overlay | keep (Apache-2.0) |
| `oss/overlay/NOTICE` | public | EN | overlay | keep |
| `AGENTS.md` (tracked root) | internal | EN | tracked (not excluded) — **collides** w/ overlay | see note 1 |
| `GEMINI.md` (tracked root) | internal | — | tracked (not excluded!) | **add to exclude.txt** (internal editor config) |
| `CLAUDE.md` | internal | JA | excluded | keep excluded |

Note 1 — `AGENTS.md` exists both tracked-at-root and in the overlay. The overlay
copy wins (overlaid last), so the public ships the overlay version. Confirm the
tracked root `AGENTS.md` is acceptable to ship *if* the overlay ever stops
shipping it; today it is harmless but a maintenance trap (two AGENTS.md to keep
in sync). Recommend: keep only the overlay AGENTS.md public; the tracked root one
is internal — fine, but document the duplication.

### `docs/` overlay (public)

| Path | Audience | Lang | OSS-ships? | Verdict |
|------|----------|------|-----------|---------|
| `oss/overlay/docs/getting-started.md` | public | JA | overlay | translate→EN |
| `oss/overlay/docs/configuration.md` | public | JA | overlay | translate→EN |
| `oss/overlay/docs/architecture.md` | public | JA | overlay | translate→EN |

### `docs/` tracked (ship unless excluded)

| Path | Audience | Lang | OSS-ships? | Verdict |
|------|----------|------|-----------|---------|
| `docs/architecture.md` | mixed | JA | tracked | reconcile vs overlay arch (see note 2) |
| `docs/tools/*.md` (34) | public | JA | tracked | keep; translate top-N later |
| `docs/operations/bash-sandbox-provisioning.md` | public | JA | tracked | keep |
| `docs/operations/index.html` + `initial-setup.html` + `guide.css` | public | JA | tracked (HTML) | see RECONCILIATION |
| `docs/design/**` (ui_kits_reference jsx/html/css) | internal | mixed | tracked | **exclude** (dev design refs, not user docs) |
| `docs/aao-gateway-overview.md` | public | JA | tracked | keep |
| `docs/mcp.md`, `docs/skills.md`, `docs/ssh.md`, `docs/bench.md` | public | JA | tracked | keep |
| `docs/context-flow.md`, `docs/user-folder-layout.md` | public | JA | tracked | keep |
| `docs/maintenance-checklist.md` | internal (contributors) | JA | tracked | keep (referenced by CONTRIBUTING) |

Note 2 — duplicate architecture docs: `docs/architecture.md` (tracked) AND
`oss/overlay/docs/architecture.md` (overlay). The overlay wins for the public.
Decide which is canonical and have the other redirect/stub, or exclude the
tracked one to avoid drift.

### docs-wip branch (in-progress reorg — NOT yet on main)

`docs-wip` does two things:

2. **Adds** a consolidated, curated doc set: `docs/reference/*.md` (18 files,
   Japanese — feature reference: scheduler, config, mcp, ssh, memory, gateway,
   pieces, skills, notifications, media-tools, etc.), plus an HTML build system:
   `docs/build_html.py` (Markdown→staged HTML), generated `docs/html/**`, and
   manifest JSON (`.investigate-status.json`, `.consolidate-manifest.json`).

`docs/build_html.py` reads each doc's implementation status from
`.investigate-status.json` and renders staged HTML (design=blue /
implementation=amber / completed=green) with an `index.html` nav — exactly the
owner's HTML-staged convention. The `docs/reference/*.md` consolidation is the
single most valuable doc asset for OSS: a clean, deduplicated feature reference
replacing scattered dated design specs.

**Recommendation:** land `docs-wip`'s `docs/reference/*.md` consolidation
(highest-value, low-risk) ahead of the OSS push, but treat the *generated*
`docs/html/**` output and the `*.json` manifests as build artifacts (see
RECONCILIATION — keep the generator, gitignore/exclude the output).

---

## B. GAP ANALYSIS — GitHub OSS readiness

Verified-present: `LICENSE` (Apache-2.0), `NOTICE`, `CONTRIBUTING.md`,
`SECURITY.md`, `CHANGELOG.md`, `AGENTS.md`, `Dockerfile`, `docker-compose.yml`,
`.env.example`, `.dockerignore`.

Gaps found:

| Gap | Severity | Notes |
|-----|----------|-------|
| **No `CODE_OF_CONDUCT.md`** | high | Standard for OSS; GitHub surfaces it in the community profile. Add Contributor Covenant 2.1 to `oss/overlay/`. |
| **No `.github/` community files** | high | Missing issue templates (bug/feature), `PULL_REQUEST_TEMPLATE.md`, `FUNDING.yml` (optional). Note: repo is published to **Gitea** (`swallow/maestro`), not GitHub — Gitea reads `.gitea/ISSUE_TEMPLATE/` (and also `.github/`). Add templates under a host-appropriate dir in the overlay. |
| **README is JA-only** | high | First-time visitor on an English-default host can't read it. EN-first is the single biggest readiness fix. |
| **README has 1 badge only** | medium | Only a static license badge. Add: build/CI status, release/version, Node version, "PRs welcome". Avoid badges that need a live service. |
| **No screenshots/GIF in README** | medium | An agent UI sells itself visually. Add 1–2 screenshots (task detail / settings) under `oss/overlay/docs/assets/` and embed in README. |
| **No architecture diagram image** | low | The execution-flow ASCII block is fine; a simple diagram would help. Optional. |
| **CHANGELOG date stale** | low | `v0.1.0 — 2026-06-02` predates current HEAD; refresh on release. |
| **No top-level "Documentation" landing for the curated set** | medium | If `docs/reference/*` lands, README/getting-started should link an index. |
| **License headers in source** | low | Apache-2.0 doesn't require per-file headers, but `NOTICE` + a short header policy in CONTRIBUTING avoids questions. Optional. |
| **`GEMINI.md` would leak** | medium | Tracked at root, NOT in `oss/exclude.txt` → ships publicly. It's an internal editor/assistant config like CLAUDE.md. Add to exclude. |
| **`docs/design/ui_kits_reference/**` would ship** | low-medium | Internal design references (JSX prototypes, legacy admin kit). Not user docs. Add `docs/design` to exclude. |

README quality for a first-time visitor (overlay README): structure is good
(features → quickstart → requirements → docs → security → license). What's
missing for a strong first impression: English, a screenshot, a one-line
"what/why" hook in English at the very top, and CI/release badges.

---

## C. i18n PLAN

Current state: all public docs (overlay README + getting-started + configuration
+ architecture) and tracked `docs/**` are Japanese. GitHub/Gitea OSS audiences
default to English. The product also targets 多言語対応 as a goal.

**Convention (recommended): English-first with a `.ja` sibling.**
This is the lowest-friction, most-recognized GitHub pattern.

- `README.md` → English (the public README, i.e. `oss/overlay/README.md`).
- `README.ja.md` → Japanese (current content moved here).
- Cross-link at the top of each: `[English](README.md) | [日本語](README.ja.md)`.

For `docs/`, use a suffix convention to avoid a parallel directory tree:

```
oss/overlay/docs/
  getting-started.md        # EN (canonical)
  getting-started.ja.md     # JA
  configuration.md          # EN
  configuration.ja.md       # JA
  architecture.md           # EN
  architecture.ja.md        # JA
```

Rationale: a `docs/en/` + `docs/ja/` split doubles directory depth and breaks
relative links on every move. The `.ja.md` suffix keeps EN as the default a
visitor hits and keeps JA one click away. (If a richer i18n site is built later
— e.g. Docusaurus/MkDocs — migrate then; don't over-engineer now.)

**Translate-first order (highest visitor impact first):**

1. `README.md` (overlay) — the storefront. **Do first.**
2. `docs/getting-started.md` — clone→running path.
3. `docs/configuration.md` — `config.yaml` reference.
4. `docs/architecture.md` — for evaluators/contributors.
5. `CHANGELOG.md` (already EN), `SECURITY.md` (already EN), `CONTRIBUTING.md`
   (already EN), `AGENTS.md` (already EN) — no action.
6. Later/optional: top 5–8 `docs/tools/*.md` by usage (bash, websearch, browseweb,
   spawnsubtask, office) and the `docs/reference/*` set if landed.

**Tooling/convention:**

- Keep EN canonical, JA as translation. Do not auto-generate JA at build time;
  hand-maintain the high-value pages, accept staleness on the long tail.
- Add a short "Translations" note in CONTRIBUTING describing the `.ja.md`
  convention and that EN is canonical (PRs that change EN should flag the JA
  sibling as needing update — don't block on it).
- The existing JA overlay docs are already written and accurate — they become
  the `.ja.md` siblings essentially for free. The work is the EN translation,
  not throwing away the JA.

---

## D. DOCKER DOCS PLAN

From `git clone` to running via Docker, a new user needs (and currently has):

| Step | Covered today? | Where |
|------|----------------|-------|
| `cp .env.example .env` | yes | README quickstart + getting-started §5 |
| Set LLM endpoint | yes | `.env.example` comments (`OLLAMA_BASE_URL`, `OLLAMA_MODEL`) |
| `docker compose up -d` | yes | README + getting-started |
| Where the UI is | yes | `http://localhost:9876` |
| Data persistence | yes | named volumes `maestro-data` / `maestro-workspaces` |
| Security default (localhost-only) | yes | README + getting-started + SECURITY |

What's **missing / unclear** for a Docker-first OSS user:

1. **`host.docker.internal` on Linux.** `.env.example` defaults to
   `http://host.docker.internal:11434/v1`. On Linux Docker this name is not
   resolvable by default (works on Docker Desktop mac/win). New Linux users will
   hit "connection refused" with no hint. **Add a note**: on Linux use the host
   gateway IP or `--add-host=host.docker.internal:host-gateway` (compose:
   `extra_hosts`), or point at the LAN IP of the Ollama host.
2. **No "verify it's running" step.** Add a healthcheck/`docker compose logs -f`
   + "open the UI, create a task" smoke check to getting-started §5.
3. **Mounting `config.yaml` into the container** is referenced ("see the comments
   in docker-compose.yml") but not shown inline. New users benefit from one
   explicit example of mounting a host `config.yaml` and where setup runs in the
   container (does the image run `npm run setup`, or only env-var config?).
4. **Bash sandbox in Docker.** bwrap needs unprivileged user namespaces; in a
   container that may need extra flags or `--privileged`-adjacent settings, or
   the hardened fallback applies. Getting-started §8 covers host provisioning but
   not the containerized story. Add one paragraph: what `bash_sandbox` mode the
   Docker image ships with and any caveats.
5. **Image build vs prebuilt.** Is there a published image, or is
   `docker compose up` building locally from the `Dockerfile` every time? State
   it. If build-from-source, note the first-run build time.
6. **GPU / external Ollama.** Make explicit that MAESTRO's container does **not**
   run the LLM; users point it at an existing OpenAI-compatible endpoint. The
   README says it but the Docker section could restate it (common confusion).

Recommend a dedicated `oss/overlay/docs/docker.md` (EN) consolidating the above,
linked from README + getting-started §5, rather than growing getting-started.

---

## E. RECONCILIATION — HTML-staged docs vs GitHub Markdown

The tension: the owner's convention wants `docs/` as **staged HTML**
(design/implementation/completed, color badges, `index.html` nav). GitHub/OSS
convention wants **Markdown** README + `docs/` that render on the repo host.

These are not actually in conflict if we treat HTML as a **generated artifact**,
not the source:

1. **Markdown is the single source of truth.** Author everything as `.md`
   (`README.md`, `docs/**/*.md`, the `docs/reference/*.md` set from `docs-wip`).
   Markdown renders natively on Gitea/GitHub and is what OSS contributors expect.

2. **`docs/build_html.py` (from `docs-wip`) generates the staged HTML view** from
   that Markdown for the owner's internal browsing/handoff workflow. The
   generator stays; its **output (`docs/html/**`) is a build artifact** — do not
   hand-edit it, and keep it out of OSS:
   - add `docs/html/` to `.gitignore` (don't commit generated output), and
   - add `docs/html` + the `*.json` manifests to `oss/exclude.txt` as belt-and-
     suspenders so even a stray commit never ships generated HTML publicly.
   This gives the owner the staged-HTML experience locally (`python3
   docs/build_html.py`) while the OSS repo ships clean Markdown — **no
   duplication of content**, only a generation step.

3. **The few hand-written HTML docs that exist today**
   (`docs/operations/index.html`, `initial-setup.html`, `guide.css`) are the
   exception: they're authored HTML, not generated. Two options —
   (a) convert them to Markdown so they fit the generated-from-MD model
   (preferred for OSS consistency), or
   (b) keep them as authored HTML but exclude them from OSS and let the public
   read the Markdown equivalents (`docs/operations/bash-sandbox-provisioning.md`
   already exists). Recommend (a) long-term, (b) as the immediate no-risk choice.

4. **Stage metadata** (design/impl/completed) lives in the Markdown frontmatter
   or the manifest JSON, consumed only by `build_html.py`. OSS readers never see
   stages; they see finished Markdown. Internal readers get the staged HTML view.

Net: keep `docs-wip`'s generator + the `docs/reference/*.md` consolidation; gate
the generated HTML behind `.gitignore` + `oss/exclude.txt`. One source (MD), two
renderings (host-native MD for OSS, staged HTML for internal).

---

## F. PRIORITIZED EXECUTION CHECKLIST

Effort: S ≤30min, M ≤2h, L ≤half-day. Tags: [public-facing] ships to OSS;
[internal] private-repo / tooling only.

### P0 — leak/correctness fixes (do before any OSS push)

1. [internal] **Add `GEMINI.md` to `oss/exclude.txt`** (internal assistant
   config, currently ships). — S
2. [internal] **Add `docs/design` to `oss/exclude.txt`** (JSX/HTML UI prototypes,
   not user docs). — S
3. [internal] **Resolve duplicate architecture doc**: pick canonical
   (`oss/overlay/docs/architecture.md`), exclude or stub the tracked
   `docs/architecture.md`. — S
4. [internal] **Decide AGENTS.md duplication** (overlay wins; document that the
   tracked root copy is internal). — S
5. [internal] Run `scripts/oss-sync.sh --dry-run --local-only` and read the
   release-gate output + diff stat to confirm nothing internal leaks. — S

### P1 — English README + storefront (highest visitor impact)

6. [public-facing] **Translate `oss/overlay/README.md` to English**; move JA to
   `oss/overlay/README.ja.md`; add the `EN | 日本語` switcher line. Use
   `docs/README.en.draft.md` (this branch) as the starting skeleton. — M
7. [public-facing] **Add badges** to README: CI/build, release/version, Node 22+,
   license (keep), PRs-welcome. Only badges that don't require a live host. — S
8. [public-facing] **Add 1–2 screenshots** (`oss/overlay/docs/assets/`) and embed
   under a "Screenshots" section. — S–M (needs capturing UI)

### P2 — community health files

9. [public-facing] **Add `CODE_OF_CONDUCT.md`** (Contributor Covenant 2.1) to
   `oss/overlay/`. — S
10. [public-facing] **Add issue + PR templates** under the host-appropriate dir
    in the overlay (`.gitea/ISSUE_TEMPLATE/{bug,feature}.md` + a
    `PULL_REQUEST_TEMPLATE.md`; also `.github/` if mirroring to GitHub). — M
11. [public-facing] **Promote `SECURITY.draft.md`** (this branch) — confirm the
    existing `oss/overlay/SECURITY.md` is sufficient (it is); the draft is a
    redundant stub, delete it once confirmed. — S

### P3 — i18n of core docs

12. [public-facing] Translate `docs/getting-started.md` → EN, move JA to
    `getting-started.ja.md`. — M
13. [public-facing] Translate `docs/configuration.md` → EN (+ `.ja.md`). — M–L
14. [public-facing] Translate `docs/architecture.md` → EN (+ `.ja.md`). — M
15. [public-facing] Add a "Translations" note to CONTRIBUTING describing the
    `.ja.md` convention (EN canonical). — S

### P4 — Docker docs

16. [public-facing] Add `oss/overlay/docs/docker.md` (EN) covering the 6 gaps in
    section D (esp. Linux `host.docker.internal`, verify-running, config mount,
    sandbox-in-Docker, build-vs-prebuilt, external LLM). Link from README +
    getting-started §5. — M

### P5 — docs reorg reconciliation (coordinate with `docs-wip`)

17. [internal] **Land `docs-wip`'s `docs/reference/*.md` consolidation** onto main
    (the 18 curated feature docs; drop the generated `docs/html/**` from the
    merge). — L (review of 18 docs)
18. [internal] **Add `docs/html/` to `.gitignore`** and **`docs/html` +
    `docs/.investigate-status.json` + `docs/.*-manifest.json` to
    `oss/exclude.txt`** (generated artifacts; section E). — S
19. [public-facing] Add a `docs/README.md` (or section in main README) indexing
    the `docs/reference/*` set so the curated docs are discoverable. — S
20. [public-facing] Convert `docs/operations/*.html` to Markdown (or exclude from
    OSS); section E option (a)/(b). — M

### P6 — polish (optional, post-launch)

21. [public-facing] Translate top 5–8 `docs/tools/*.md`. — L
22. [public-facing] Refresh `CHANGELOG.md` date/contents at actual release. — S
23. [public-facing] Add an architecture diagram image to README. — M

---

## Drafts created on this branch (NOT replacing anything)

- `docs/README.en.draft.md` — English README skeleton (starting point for item 6).
- `docs/SECURITY.draft.md` — redundant stub pointing at the existing policy;
  exists only to confirm coverage (item 11) and should be deleted once the
  existing `oss/overlay/SECURITY.md` is accepted.

Both are clearly labeled DRAFT and live under `docs/` so they do not collide with
or overwrite the shipping overlay files.