# Docs Services Automation Runbook

Date: 2026-02-16
Scope: GitHub, Gitea, Jupyter, Pieces documentation integration workflow.

## Goal

Keep docs state synchronized with service reality and publish curated docs updates safely.

## 1) Refresh service status

```bash
cd /Users/apple/github-projects/microdao-daarion
bash scripts/docs/session_bootstrap.sh
```

Primary output:
- `docs/consolidation/INTEGRATIONS_STATUS_LATEST.md`

## 2) Run service adapters (Jupyter + Pieces)

```bash
cd /Users/apple/github-projects/microdao-daarion
bash scripts/docs/services_sync.sh --dry-run
```

Apply mode:

```bash
cd /Users/apple/github-projects/microdao-daarion
bash scripts/docs/services_sync.sh --apply
```

Optional local Pieces API probe:

```bash
cd /Users/apple/github-projects/microdao-daarion
bash scripts/docs/services_sync.sh --apply --probe-ports 39300,39301
```

Outputs:
- `docs/consolidation/jupyter/JUPYTER_SYNC_LATEST.md`
- `docs/consolidation/jupyter/notebooks_index_latest.csv`
- `docs/consolidation/pieces/PIECES_SYNC_LATEST.md`
- `docs/consolidation/pieces/pieces_index_latest.csv`
- `docs/backups/LATEST.txt` (latest backup archive reference)

## 3) Review pending docs updates

```bash
cd /Users/apple/github-projects/microdao-daarion
git status --short
bash scripts/docs/docs_sync.sh --dry-run
```

## 4) Apply sync to remotes

```bash
cd /Users/apple/github-projects/microdao-daarion
bash scripts/docs/docs_sync.sh --apply --targets github,gitea
```

## Safety gates

- `docs_sync.sh` is dry-run by default.
- `--apply` refuses to proceed if staged non-doc files are present.
- Only curated doc paths are auto-staged by the script.
- `services_sync.sh --apply` creates docs backup before writing integration artifacts.

## Standardization and lint

Local lint:

```bash
cd /Users/apple/github-projects/microdao-daarion
bash scripts/docs/docs_lint.sh
```

CI lint:
- `.github/workflows/docs-lint.yml`
- config: `.markdownlint.yml`, `.markdownlintignore`

Style and template:
- `docs/standards/DOCS_STYLE_GUIDE.md`
- `docs/standards/DOC_TEMPLATE.md`

## Jupyter and Pieces notes

- `jupyter_sync.sh` probes active Jupyter servers via `/api/status` when servers are discovered.
- `pieces_sync.sh` captures local Pieces runtime markers and supports optional local API probes (`--probe-ports`).