Build and publish project documentation — Starlight (Astro) for apps, markdown for libraries/services, with IT+EN i18n and VPS deploy. Use when writing user guides, scaffolding a docs site, or publishing docs. Trigger on "write docs", "documentation site", "user guide", "publish docs".
Scanned 6/6/2026
Install via CLI
Skills Directoryopenskills install matteocervelli/llms---
name: docs
description: Build and publish project documentation — Starlight (Astro) for apps, markdown for libraries/services, with IT+EN i18n and VPS deploy. Use when writing user guides, scaffolding a docs site, or publishing docs. Trigger on "write docs", "documentation site", "user guide", "publish docs".
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
---
# /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`:
```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:**
```typescript
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`:
```javascript
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):
```yaml
packages:
- "frontend"
- "site" # ← aggiungere
```
8. Aggiorna `package.json` root per permettere build scripts di esbuild/sharp (richiesti da Astro):
```json
{
"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 (usa `pnpm`, NON `npm ci`):
```makefile
site-dev: ## Start docs site development server (localhost:4321/docs)
cd site && $(PNPM) run dev
site-build: ## Build docs site for production
cd site && $(PNPM) install --frozen-lockfile && $(PNPM) run build
deploy-site: site-build ## Build and deploy docs site to VPS
rsync -avz --delete site/dist/ {vps-host}:/opt/{app}/site/dist/
```
11. Aggiungi snippet nginx a `docs/deployment/nginx-site.conf` (o crea il file):
Usa template `templates/nginx-site.conf` con auth_request configurato
12. Aggiungi endpoint FastAPI `GET /auth/verify` (controlla se già esiste):
Cerca in `backend/` per `auth/verify` → se assente, propone aggiunta
13. Output:
```
✓ site/ creata con Starlight 0.32 + Astro 5 (IT root + EN)
✓ src/content.config.ts creato (docsLoader)
✓ pnpm-workspace.yaml aggiornato
✓ docs-registry.yaml inizializzato
✓ Makefile aggiornato con target site-dev, site-build, deploy-site
✓ Snippet nginx generato in docs/deployment/nginx-site.conf
⚠ Aggiungi manualmente endpoint /auth/verify a backend/app/api/auth.py
Prossimi passi:
pnpm install && make site-dev # preview locale su localhost:4321/docs
/docs create getting-started # crea prima pagina
```
### Internal Mode (Markdown)
Condizione: repo name `private-lib-*` oppure service noto oppure `--mode internal`
**Steps:**
1. Crea struttura directory:
```
docs/
├── user-guide/
│ ├── getting-started.md
│ └── README.md ← indice delle guide
└── docs-registry.yaml
```
`docs/user-guide/` è separata dai dev docs esistenti (`docs/architecture/`, `docs/deployment/`, ecc.).
2. Genera `docs/user-guide/README.md` — indice delle guide con link
3. Genera `docs/docs-registry.yaml` (stesso formato dell'app mode, senza campi deploy)
4. Output:
```
✓ docs/user-guide/ creata
✓ docs/docs-registry.yaml inizializzato
Mode: internal (no Starlight, no deploy)
Prossimi passi:
/docs create getting-started # crea prima guida utente
/docs features # estrae feature list da CHANGELOG + API
```
---
## Subcommand: `/docs create <type>`
Crea una nuova pagina docs da template. **Adattato al mode corrente:**
- App mode → MDX con Starlight components (Steps, Cards, Aside)
- Internal mode → plain markdown (stessi contenuti, senza MDX)
**Tipi disponibili:**
| Tipo | Template app | Template interno | Cartella target (app) | Cartella target (interno) |
|---|---|---|---|---|
| `getting-started` | `templates/getting-started.md` | `templates/internal/getting-started.md` | `site/src/content/docs/{lang}/` | `docs/user-guide/` |
| `feature-guide` | `templates/feature-guide.md` | `templates/internal/feature-guide.md` | `site/src/content/docs/{lang}/features/` | `docs/user-guide/features/` |
| `how-to` | `templates/how-to.md` | `templates/internal/how-to.md` | `site/src/content/docs/{lang}/guides/` | `docs/user-guide/guides/` |
| `faq` | `templates/faq.md` | `templates/internal/faq.md` | `site/src/content/docs/{lang}/` | `docs/user-guide/` |
| `release-notes` | `templates/release-notes.md` | `templates/internal/release-notes.md` | `site/src/content/docs/{lang}/` | `docs/user-guide/` |
| `api-reference` | — | `templates/internal/api-reference.md` | — | `docs/user-guide/` |
| `feature-guide` | `templates/feature-guide.md` | `site/src/content/docs/{lang}/features/` |
| `how-to` | `templates/how-to.md` | `site/src/content/docs/{lang}/guides/` |
| `faq` | `templates/faq.md` | `site/src/content/docs/{lang}/` |
| `release-notes` | `templates/release-notes.md` | `site/src/content/docs/{lang}/` |
**Steps:**
1. Chiedi (o rileva da args): tipo, lingua (default: `it`), nome/slug pagina
2. Leggi template corrispondente
3. Sostituisci placeholder: `{{APP_NAME}}`, `{{DATE}}`, `{{VERSION}}` (da CHANGELOG)
4. Scrivi file in cartella target
5. Aggiorna `site/docs-registry.yaml` con la nuova pagina (status: `draft`)
6. Output: path creato + prossimo passo (`/docs audit` o `npm run dev`)
---
## Subcommand: `/docs review-drafts`
Lancia N agent paralleli per **verificare l'accuratezza** e completare le pagine draft.
**CRITICO: Lanciare SEMPRE gli agent.** Non shortcuttare mai questa fase. Anche se non ci sono
placeholder `{{...}}`, la review verifica che il contenuto sia **accurato rispetto al codice sorgente**.
Zero placeholder NON significa "già verificato" — significa solo "qualcuno ha scritto del testo".
**Pre-condizioni:**
- `docs-registry.yaml` esiste con almeno 1 pagina in status `draft`
- Se 0 draft: "Nessuna draft da revisionare. Tutte le pagine sono published o missing."
**Steps:**
1. Leggi `docs-registry.yaml` → filtra pagine con `status: draft`
2. Per ogni draft, verifica che il file esista su disco (skip se missing)
3. Chiedi conferma: "Hai N pagine draft. Lancio N agent in parallelo per verificarle?"
4. Se confermato, per ogni draft lancia un **Agent** in parallelo:
```
Agent(
subagent_type: "general-purpose",
model: "sonnet",
description: "Review and verify draft doc: <filename>",
prompt: """
Sei un technical reviewer. Il tuo compito è VERIFICARE l'accuratezza di questa
pagina di documentazione rispetto al codice sorgente reale.
FILE DA VERIFICARE: <path-to-draft>
PROGETTO: <project-name>
ISTRUZIONI:
1. Leggi il file docs da verificare
2. Leggi il codice sorgente corrispondente in backend/ o app/ o src/
3. Leggi CHANGELOG.md per le feature documentate
4. Per ogni affermazione nella docs, VERIFICA che corrisponda al codice reale:
- I nomi delle classi/funzioni sono corretti?
- I parametri e i return type corrispondono?
- Gli esempi di codice funzionerebbero se eseguiti?
- Le versioni citate sono corrette?
- Mancano funzionalità importanti non documentate?
5. Se trovi placeholder ({{...}}, [Passo X], TODO, TBD): sostituiscili con contenuto reale
6. Se trovi errori: correggili con Edit tool
7. Se trovi funzionalità mancanti: aggiungile
8. Non inventare funzionalità — documenta solo ciò che esiste nel codice
Output finale:
- VERDICT: ACCURATE / NEEDS_FIXES / INACCURATE
- Lista di ciò che hai verificato
- Lista di ciò che hai corretto (se NEEDS_FIXES)
- Lista di funzionalità mancanti aggiunte (se presenti)
"""
)
```
5. Attendi completamento di tutti gli agent
6. Per ogni file, mostra il verdetto dell'agent:
```
✓ getting-started.md — ACCURATE (verified 12 code refs, 0 fixes)
⚠ features/audio.md — NEEDS_FIXES (2 wrong param names corrected)
✓ guides/router-pattern.md — ACCURATE (verified 8 code refs, added 1 missing feature)
```
7. Chiedi conferma finale: "Agent hanno verificato N pagine. Le marco come published?"
8. Se confermato: aggiorna `docs-registry.yaml`:
- `status: draft → published`
- `last_updated: <today>`
- `linked_version: <latest-from-changelog>`
**Output:**
```
## Review Drafts — <project> — <date>
Lancio 6 agent in parallelo...
✓ getting-started.md — 12 placeholder → contenuto reale (agent 1, 45s)
✓ feature-guide-media.md — 8 placeholder → contenuto reale (agent 2, 38s)
✓ feature-guide-audio.md — 9 placeholder → contenuto reale (agent 3, 41s)
✓ how-to-upload.md — 6 placeholder → contenuto reale (agent 4, 32s)
✓ faq.md — 10 placeholder → contenuto reale (agent 5, 35s)
✓ api-reference.md — 15 placeholder → contenuto reale (agent 6, 52s)
Tutti completati. Marco come published? [Sì / No / Revisiono prima]
```
Se l'utente sceglie "Revisiono prima": mostra il contenuto di ogni file per review manuale prima di marcare published.
**Invocato da:**
- Direttamente: `/docs review-drafts`
- Step 4b del routing di `/docs` (summary) quando ci sono ≥1 draft
- `/docs full` dopo la fase create
---
## Subcommand: `/docs audit`
Trova pagine stale, mancanti, link rotti. Usato da `/health docs`.
**Steps:**
1. **Registry delta** — confronta `docs-registry.yaml` con file effettivi in `site/src/content/docs/`
- File nel registry ma non su disco → `missing`
- File su disco ma non nel registry → `unregistered` (aggiunge al registry come `draft`)
2. **Staleness check** — per ogni pagina `published`:
```bash
PAGE_TS=$(git log -1 --format="%ct" -- site/src/content/docs/it/getting-started.md)
CODE_TS=$(git log -1 --format="%ct" -- backend/ src/ 2>/dev/null)
DIFF_DAYS=$(( (CODE_TS - PAGE_TS) / 86400 ))
# Se DIFF_DAYS > 30 → stale
```
3. **Link check** — grep per `[text](url)` e `href="..."` nelle pagine IT e EN
- Link interni (`/docs/...`) → verifica file esista in `site/src/content/docs/`
- Link esterni → skip (troppo lenti per audit locale)
4. **Language parity** — per ogni pagina IT, verifica esista controparte EN e viceversa
- Mancante → `status: missing` nel registry
5. **Output:**
```
## Docs Audit — <project> — <date>
Pages: 8 total (5 published, 2 draft, 1 stale, 0 missing)
Links: 12 internal (all OK), 0 broken
Languages: IT 8 pages | EN 3 pages | 5 EN missing
Stale (>30 days behind code):
⚠ it/features/invoices.md — last updated 45 days ago
Missing EN translations:
⚠ en/getting-started.md
⚠ en/features/invoices.md
... 3 more
Suggested actions:
/docs update it/features/invoices.md
/docs translate en
```
**Gate (usato da `/health docs`):**
- `PASS`: 0 stale, 0 missing, 0 broken links
- `WARN`: stale > 30 giorni OR missing EN pages
- `FAIL`: pagine required mancanti (getting-started) OR broken links interni
---
## Subcommand: `/docs update`
Aggiorna una pagina stale basandosi su git diff + CHANGELOG.
**Steps:**
1. Leggi il file docs da aggiornare
2. `git log --oneline -- backend/ src/` dall'ultima modifica del file docs → lista commit recenti
3. Controlla CHANGELOG per entry aggiunte dall'ultima modifica docs
4. Propone aggiornamenti specifici: nuove feature da documentare, comportamenti cambiati
5. Applica aggiornamenti con conferma utente
6. Aggiorna `last_updated` e `linked_version` nel registry
---
## Subcommand: `/docs translate <lang>`
Traduce pagine mancanti da lingua source a lingua target.
**Default:** `it → en` (IT è la lingua primaria)
**Steps:**
1. Identifica pagine con status `missing` per la lingua target (da audit)
2. Per ogni pagina source:
- Leggi contenuto IT
- Traduci con Claude (istruzioni: mantieni struttura MDX, non tradurre codice, mantieni slug frontmatter)
- Scrivi file EN equivalente
- Aggiorna registry: status `draft` (richiede review umana)
3. Output: N pagine tradotte, lista path creati
**Nota:** traduzioni auto hanno status `draft` — richiedono review prima di `published`.
---
## Subcommand: `/docs publish [env]`
Deploya `site/dist/` sul VPS.
**Env disponibili:** `staging` (default durante sviluppo), `stable` (default senza args)
**Steps:**
1. Verifica `site/` esiste e `npm run build` funziona localmente
2. Build: `cd site && npm ci && npm run build`
3. Deploy:
- **Oggi (make):** `make deploy-site` — rsync su `/opt/{app}/site/dist/`
- **Futuro (Forgejo Actions):** push su branch `docs/staging` o `docs/stable` → trigger CI
4. Verifica: `curl -s https://{domain}/docs/` → controlla 200 OK
5. Aggiorna registry: `last_deployed: <date>` per tutte le pagine `published`
---
## Subcommand: `/docs registry`
CRUD su `site/docs-registry.yaml`.
**Operazioni:**
```
/docs registry # mostra tutte le pagine con status
/docs registry stale # solo pagine stale (>30 giorni)
/docs registry missing # pagine nel registry ma non su disco
/docs registry update <file> status=published
```
---
## Subcommand: `/docs features`
Estrae feature list da CHANGELOG.md + FastAPI routes.
**Steps:**
1. Leggi `CHANGELOG.md` → estrai sezioni `### Added` per tutte le versioni
2. Grep `backend/` o `src/` per route FastAPI (`@router.get`, `@router.post`, etc.)
3. Merge e deduplicazione → lista feature con versione di introduzione
4. Genera file `site/src/content/docs/it/features.md` con tabella feature
---
## Subcommand: `/docs migrate`
Audit strutturale del repo corrente e proposta di migrazione alla convenzione standard.
**Convenzione target:**
```
{repo}/
├── backend/ ← FastAPI (o app/ per HTMX)
├── frontend/ ← Next.js/React/Vite (se esiste)
├── site/ ← Astro (marketing + docs, NUOVO)
├── docs/ ← dev docs interni (invariata)
└── Makefile
```
**Steps:**
1. Scansiona struttura root del repo
2. Identifica deviazioni:
- `src/` invece di `backend/` o `frontend/` → suggerisci rename
- `docs/` contiene contenuto user-facing → suggerisci spostamento in `site/`
- `site/` o `docsite/` assente → suggerisci `/docs scaffold`
- `www/` separata da `site/` → suggerisci merge
3. Presenta tabella di migrazione proposta con impatto (rename, move, create)
4. Esegue solo le azioni approvate dall'utente
5. Aggiorna `docs/development/architecture.md` con la nuova struttura
---
## Subcommand: `/docs video` (P3)
Crea video guide automatizzate.
**Stack:** Playwright (registrazione headful) → Fabrica FFmpeg (captions overlay) → `/tts` (narrazione)
_Da implementare in DOCS-0.2 milestone._
---
## Subcommand: `/docs full`
Esegue pipeline completa.
```
1. /docs scaffold (se site/ non esiste)
2. /docs audit (trova gap)
3. /docs create (per ogni pagina missing required)
4. /docs translate en (se pagine EN mancanti)
5. /docs publish (deploy)
```
---
## Registry Format
`site/docs-registry.yaml` — una entry per ogni pagina docs:
```yaml
meta:
project: appratio
domain: appratio.it
docs_base: /docs
last_audit: 2026-03-16
docs:
getting-started-it:
file: src/content/docs/it/getting-started.md
type: getting-started # getting-started | feature-guide | how-to | faq | release-notes | reference | video
language: it
feature: onboarding
last_updated: 2026-03-16
status: published # draft | published | stale | missing
linked_version: "1.0.0"
getting-started-en:
file: src/content/docs/en/getting-started.md
type: getting-started
language: en
status: missing
```
**Valori status:**
- `draft` — creata ma non review-ata
- `published` — live in produzione
- `stale` — code più recente del docs di >30 giorni
- `missing` — nel registry ma file non su disco
---
## Integrazione `/health docs`
`/health docs` delega a `/docs audit` e ne eredita il gate:
```
Invoke: /docs audit
Gate:
PASS → /docs audit restituisce 0 stale, 0 missing required, 0 broken links
WARN → stale > 30 giorni OR missing EN pages OR pagine opzionali mancanti
FAIL → getting-started mancante OR broken links interni OR site/ assente
```
Sostituisce il check base attuale (CLAUDE.md/README staleness rimane in `/health docs` come check separato).
---
## Thresholds
| Check | WARN | FAIL |
| --------------- | ----------------------------- | ------------------------------------------------- |
| Staleness | >30 giorni codice più recente | >60 giorni |
| Missing pages | pagine opzionali mancanti | getting-started mancante |
| Language parity | EN pages < 50% delle IT | EN getting-started mancante |
| Broken links | - | qualsiasi link interno 404 |
| site/ presenza | - | `site/` assente (FAIL solo se progetto ha utenti) |
No comments yet. Be the first to comment!
