Quickstart

This page walks a new operator from a clean checkout to a passing preflight. It mirrors the Five-minute smoke test section of the repo README.md. For deeper operational guidance, head to the Runbook and the CLI reference.

Prerequisites

• Python 3.13 managed by uv
• Quarto on PATH (only required for forensics report and forensics all)
• Optional: pydoc-markdown (for regenerating API pages locally) and spaCy en_core_web_md (for the full extract stage)

Caution

Preflight requires real authors in config.toml. The shipped example config keeps exactly one role = "target" (Colby Hall) and every other configured writer as role = "control". Placeholder slugs trip preflight guards — never re-introduce them.

Smoke test in five minutes

1. Clone and enter the repo.

   git clone git@github.com:Abstract-Data/mediaite-ghostink.git
   cd mediaite-ghostink

2. Bootstrap a reviewer environment.

   Make target

   make peer-setup

   Raw `uv`

   uv sync --extra dev --extra tui
   uv run forensics validate
   uv run forensics peer-setup

3. Run preflight.

   uv run forensics preflight

   This exits 0 when configuration, storage paths, optional model availability, and roster guardrails all pass. Any non-zero exit code is documented in Exit codes.

4. Browse the CLI surface.

   uv run forensics --help

   Every subcommand is also documented under CLI reference on this site (auto-generated from the Typer app).

Repository layout

The pipeline writes to data/ and reads operator-facing prose from docs/. Source modules live under src/forensics/.

• Directorymediaite-ghostink/

  • Directorysrc/forensics/

    • Directoryscraper/ WordPress REST + HTML

      • …
    • Directoryfeatures/ Lexical, structural, content, productivity

      • …
    • Directoryanalysis/ Change-points, drift, convergence

      • …
    • Directoryreporting/ Quarto-aware report stage

      • …
    • Directorycli/ Typer command surface

      • …
  • Directorydata/ Pipeline artifacts (gitignored)

    • Directoryraw/ Scraped documents

      • …
    • Directoryfeatures/ Parquet feature store

      • …
    • Directoryanalysis/ Per-author analysis JSON

      • …
    • Directoryreports/ Optional local Quarto output

      • …
  • Directorydocs/ Canonical operator prose (synced into this site)

    • Directoryadr/ Architecture decision records

      • …
    • ARCHITECTURE.md, RUNBOOK.md, TESTING.md, GUARDRAILS.md, …
  • Directorynotebooks/ Quarto chapters for the bound report

    • …
  • Directorywebsite/ This documentation site

    • …

What ships at /report/

Note

The Quarto-rendered forensic report is embedded under /report/index.html on this site. It is built by quarto render --output-dir website/public/report inside CI and copied into the deployed dist tree alongside the Starlight site. The report’s source notebooks live in notebooks/ and are read-only for the documentation pipeline.

Next steps

• Read the Architecture overview for stage contracts and data model definitions.
• Skim the Guardrails to see the Signs (failure patterns) maintainers and agents should respect.
• The Runbook collects every operational quick-reference command, environment knob, and recovery procedure.
• Each architectural decision is captured under Decision records — start with ADR-001 for the hybrid methodology rationale.