README.adoc

OikosBot Documentation Map

The single entry point to OikosBot’s documentation, grouped by audience. OikosBot is an ecological & economic code-review GitHub/GitLab App (alpha, 0.1.0-dev). It is OikosBot — not the oikos DSL, nor the sustainabot fleet slot (see DISAMBIGUATION).

Start here (everyone)

• README — what OikosBot is, and the repo layout.

• EXPLAINME — what is actually built vs in-flight. Read this to calibrate expectations.

• DEBT — the debt register: licence, docs, code, proof and CI/CD, each item evidenced. Read alongside EXPLAINME; between them they are the honest account of the project.

• ARCHITECTURE — the target platform design, scoring model, and tech stack. Several components in it were never built; the document now flags which.

The estate pipeline (newest surface)

• Design spec — why the unit of analysis is the estate rather than the diff, and how DEA supplies allocative and productive efficiency.

• Verification record — the six checks round one had to pass, with results, including the falsifier that would have sunk the premise.

• oikosbot-estate — the snapshot dataset repository (Parquet + analysis.json + rendered report).

For developers

• QUICKSTART — build and run the CLI.

• ARCHITECTURE — components, analyzers, policy engine, data layer.

• policies/README — Eclexia (.ecl) policies and the finding taxonomy.

• bot-integration-affine — the AffineScript webhook receiver (scaffold).

• CONTRIBUTING — fork / branch / PR flow.

• CI runbook — every gate, what it enforces, and how to read a red check when the logs are unavailable.

• Crate guides — one README per workspace crate, each stating what it owns, its public surface, and what it does not do: metrics, analysis, pareto, sarif, eclexia, telemetry, capability, dea, cli, plus the optional fleet bridge (excluded from the default workspace).

• Haskell analyzer — what analyzers/code-haskell computes and how it relates to the Rust workspace.

• Still open (#16): an end-to-end build walkthrough.

For maintainers

• GOVERNANCE + MAINTAINERS — governance model and roles.

• ROADMAP — phases and milestones.

• .machine_readable/descriptiles — the machine-readable state/runbook (see below).

• CI runbook — the gate inventory, actions.lock rules, how to diagnose Hypatia and Publish Image failures, the just target reference, and the pre-release (GitHub Marketplace) checklist.

• Still open (#16): the README → docs/ split.

For end users

• GitHub App setup — install and configure the App.

• SECURITY — vulnerability reporting and data handling.

• Using OikosBot — action inputs, the three modes, what each verdict and confidence level means, the SARIF shape, .oikos.yml configuration, BOT_MODE, and a troubleshooting table.

• Still open (#17): a production deploy runbook — DEPLOY is still a stub, gated on AffineScript operational parity.

Machine-readable docs (A2ML)

The canonical project state and decisions live in .machine_readable/descriptiles/:

• STATE.a2ml — current status, milestones, blockers, next actions.

• META.a2ml — architecture decisions (ADRs).

• NEUROSYM.a2ml — neurosymbolic config + the canonical finding taxonomy.

• PLAYBOOK.a2ml — operational runbook.

• AGENTIC.a2ml / ECOSYSTEM.a2ml — AI-agent gating and ecosystem position.

Current state (read first)

• STATUS — what works, what does not, and how each claim was verified. Includes the standing caveat that resource figures are static estimates, that only calibrated findings may block a merge, and that the eco score’s absolute scale saturates under calibrated magnitudes.

• OikosBot vs Climate Warrior — positioning against the nearest GitHub Marketplace neighbour.

Concepts (to engage fully, beyond setup)

• Eco/econ review lens (carbon 40 / economic 30 / quality 30) — ARCHITECTURE, Scoring Model.

• Finding taxonomy (intent / maintenance / locus) — policies/README + NEUROSYM.a2ml [finding-taxonomy].

• Eclexia policies (resource-bounded, dogfooded) — policies/README.

• VeriSimDB octad data layer (deferred) — verisimdb-client + META.a2ml ADR-001.

• Provenance & the PMPL license — PALIMPSEST.

Remaining audience-depth gaps: the README→docs/ split and the end-to-end build walkthrough in #16, and the production deploy runbook in #17.

Handoff

For whoever picks this up next — the automation or a new maintainer:

• PROMPT — the per-issue plan for the open backlog, with the hard facts that should not be rediscovered.

• Owner actions — everything that needs a permission a checkout does not have: repository settings, other repositories, and the design rulings the code is waiting on. Includes ready-to-post issue comments for the tracker.

• open-issues.txt — verbatim issue bodies.

• CI-EVIDENCE — how the CI failures were diagnosed without access to logs or artifacts.