docs

/docs — Documentation Pipeline

Unified pipeline for documentation across all project types. Dual mode:

• App mode (app-ratio, app-himalaia, app-levero) → Starlight (Astro) in site/, deploy su VPS

Mode detection: automatic from repo name and structure:

• app-* or site/ exists → app mode (Starlight)
• private-lib-* → internal mode (library markdown)
• Override: /docs scaffold --mode app or /docs scaffold --mode internal

Future: Atrium gets a unified Starlight site aggregating all internal docs from libs/services.

Architecture — App Mode (locked)

• SSG: Starlight (Astro) — MIT, i18n IT+EN native, Pagefind search built-in
• Structure: site/ folder inside each app repo (marketing + docs unified Astro project)
• URL: {app-domain}/docs (subfolder, not subdomain) — SEO unificato
• Auth: nginx auth_request → FastAPI /auth/verify finché l'app non è pubblica
• Deploy: make deploy-site oggi; Forgejo Actions staging/stable in futuro
• Language: Italiano first, i18n EN configurato da day-0

Architecture — Internal Mode

• Output: plain markdown in docs/user-guide/ (non deployato, letto da sviluppatori e integratori)
• Stessi template concettuali di Starlight ma senza MDX/components
• Registry: docs/docs-registry.yaml (stesso formato, stessa skill)
• Nessun site/, nessun npm, nessun Astro

Quick Start

/docs                          # stato docs + mode auto-detect
/docs scaffold                 # app mode: site/ | internal mode: docs/user-guide/
/docs create getting-started   # crea pagina da template (adattato al mode)
/docs audit                    # trova stale, mancanti, link rotti
/docs update                   # aggiorna pagine stale da git diff + CHANGELOG
/docs translate it             # EN→IT (solo app mode)
/docs publish                  # deploy su VPS (solo app mode)
/docs publish staging          # deploy ambiente staging (solo app mode)
/docs review-drafts            # lancia N agent paralleli per completare e verificare le draft
/docs registry                 # mostra stato registry docs del progetto
/docs features                 # estrae feature list da CHANGELOG + routes/API
/docs migrate                  # audit strutturale repo + propone migrazione a convenzione
/docs full                     # scaffold → audit → create missing → review-drafts → (translate → publish se app mode)

---

Subcommand: /docs (summary)

Auto-detect progetto corrente e mostra stato docs.

Steps:

1. Auto-detect mode (app vs internal)
2. App mode: verifica site/ + site/docs-registry.yaml + staleness + language parity Internal mode: verifica docs/user-guide/ + docs/docs-registry.yaml + staleness
3. Output report con status per dimensione
4. Proponi il prossimo passo concreto e chiedi se eseguirlo

Step 4 — Next action routing (obbligatorio):

Dopo il report, identifica l'azione con priorità più alta e proponi di eseguirla:

Condizione (in ordine di priorità)	Prossima azione
Né site/ né docs/user-guide/ esistono	"Eseguo /docs scaffold?"
scaffold esiste ma 0 pagine	"Eseguo /docs create getting-started?"
pagine in status draft (anche senza placeholder)	"Eseguo /docs review-drafts?" (N agent paralleli VERIFICANO accuratezza vs codice)
draft completate, modifiche non committate	"Eseguo /pre-commit → /ship?" (valida + commit + push + PR)
pagine stale >30 giorni	"Eseguo /docs update <file più stale>?"
pagine EN mancanti (solo app mode)	"Eseguo /docs translate en?"
tutto OK ma non deployato (solo app mode)	"Eseguo /docs publish?"
tutto published, non video (app mode)	"Video guide da esplorare — /docs video (sessione dedicata)"
tutto published, tutto deployato	"Docs in ordine. Nessuna azione necessaria."

Chiedi sempre conferma con AskUserQuestion prima di eseguire. Se l'utente dice sì, esegui l'azione e poi ricicla al punto 4 (proponi il passo successivo). Questo crea un loop guidato: report → proposta → esecuzione → report → proposta → ... fino a quando tutto è PASS o l'utente dice stop.

Step 4b — Parallel draft review (quando ci sono multiple draft):

Quando ci sono ≥2 pagine draft, proponi di lanciare agent paralleli:

"Hai N pagine draft. Lancio N agent Explore in parallelo per completarle?"

Se l'utente conferma:

1. Per ogni pagina draft, lancia un Agent (subagent_type: general-purpose, model: sonnet):

   • Input: il file draft + CHANGELOG.md + codice sorgente rilevante (backend/, app/, src/)
   • Istruzioni: "Leggi il template, sostituisci tutti i placeholder con contenuto reale basato sul codice e CHANGELOG. Mantieni la struttura del template. Non inventare funzionalità — documenta solo ciò che esiste."
   • Output: il file completato

2. Dopo che tutti gli agent finiscono:

   • Mostra diff per ogni file modificato
   • Chiedi conferma: "Marco tutte come published?"
   • Se sì: /docs registry update <page> status=published per ognuna

Questo parallelizza il lavoro più pesante (compilare N draft) senza richiedere intervento umano per ogni singola pagina.

Output example:

Mode         internal   private-lib-* library → markdown
user-guide/  [MISS]     docs/user-guide/ assente
Registry     [MISS]     docs/docs-registry.yaml assente
Staleness    [WARN]     code 19 giorni più recente dei docs

───────────────────────────────────
Prossimo passo: /docs scaffold (crea docs/user-guide/ + registry)
Eseguo?

---

Subcommand: /docs scaffold

Inizializza la struttura docs nel repo corrente. Dual mode.

Pre-condizioni:

• Siamo nella root del repo (pyproject.toml o package.json presente)
• Mode auto-detect: app-* → app mode, private-lib-* o services → internal mode
• Override: --mode app o --mode internal

App Mode (Starlight)

Condizione: repo name app-* oppure --mode app

Stack locked (2026-03-17): Starlight 0.32 + Astro 5 + pnpm workspace. Il locale default IT va alla root di docs/ (NON in it/ subdir) — vedi sotto.

Steps:

1. Crea struttura directory:

site/
├── src/
│   ├── content/
│   │   └── docs/
│   │       ├── index.md         ← homepage IT (root locale = IT)
│   │       ├── getting-started.md
│   │       ├── features/        ← feature guides IT
│   │       └── en/              ← SOLO EN in subdir
│   │           ├── getting-started.md
│   │           └── features/
│   └── content.config.ts        ← OBBLIGATORIO in Astro 5
├── public/
└── docs-registry.yaml

CRITICO — Struttura i18n corretta per Starlight 0.32 + Astro 5:

• Locale default (IT) = root: i file IT vivono direttamente in docs/ (NO it/ subdirectory)
• Locale EN = en/: i file EN vivono in docs/en/
• Se metti IT in docs/it/ il build genera solo 1 pagina — il sito non funziona

2. Genera site/package.json:

{
  "name": "app-{name}-site",
  "type": "module",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "dev": "astro dev --port 4321",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "@astrojs/starlight": "^0.32.0",
    "astro": "^5.4.0"
  },
  "devDependencies": {
    "sharp": "^0.33.0"
  }
}

3. Genera site/src/content.config.ts — OBBLIGATORIO in Astro 5, senza questo le pagine non vengono trovate:

import { defineCollection } from "astro:content";
import { docsLoader } from "@astrojs/starlight/loaders";
import { docsSchema } from "@astrojs/starlight/schema";

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};

4. Genera site/astro.config.mjs:

import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  base: "/docs",
  integrations: [
    starlight({
      title: "{APP_NAME} — Guida Utente",
      description: "Documentazione ufficiale di {APP_NAME}",
      defaultLocale: "root", // 'root' = IT a root level, NON 'it'
      locales: {
        root: { label: "Italiano", lang: "it" },
        en: { label: "English", lang: "en" },
      },
      sidebar: [
        {
          label: "Inizia qui",
          translations: { en: "Start here" },
          items: [{ slug: "getting-started" }],
        },
        {
          label: "Funzionalità",
          translations: { en: "Features" },
          autogenerate: { directory: "features" },
        },
      ],
    }),
  ],
});

Nota sidebar slugs: con docsLoader() i slug NON hanno prefisso locale. { slug: 'getting-started' } punta a docs/getting-started.md (IT root) E a docs/en/getting-started.md (EN) — Starlight gestisce l'i18n internamente.

5. Genera site/src/content/docs/index.md — homepage IT (template splash)

6. Genera site/docs-registry.yaml vuoto

7. Aggiorna pnpm-workspace.yaml nella root (se il progetto usa pnpm):

packages:
  - "frontend"
  - "site" # ← aggiungere

8. Aggiorna package.json root per permettere build scripts di esbuild/sharp (richiesti da Astro):

{
  "pnpm": {
    "onlyBuiltDependencies": ["esbuild", "sharp"]
  }
}

Poi esegui pnpm install per aggiornare il lockfile.

9. Aggiungi a .gitignore root:

site/dist/
site/.astro/

10. Aggiungi target Makefile

---

Content truncated.