abyss-stack is the infrastructure substrate of the AoA and ToS ecosystem.
It is Fedora-first in deployment posture and Windows-usable for source
work, path mapping, and hybrid workflows.
Use this README as the source checkout front door. It routes readers to the owner surface that can answer the question. It is not the roadmap, changelog, decision log, runtime receipt, or package-local inventory.
Current release:
v0.2.2. See CHANGELOG for release notes.
| Function | Stronger surface |
|---|---|
| Names the runtime owner lane and what must stay elsewhere | CHARTER, BOUNDARIES |
| Describes the runtime body this repository should grow toward | DESIGN |
| Describes the intended shape of agent-facing guidance | DESIGN.AGENTS |
| Maps concrete runtime topology | runtime/ARCHITECTURE, mechanics |
| Explains deployment, paths, profiles, presets, and operator flow | docs |
| Holds current runtime-wide direction and future triggers | ROADMAP |
| Records release-visible history | CHANGELOG |
| Keeps durable obligations and packet state | QUESTBOOK, quests |
| Explains durable route or topology decisions | docs/decisions |
This repository is strongest when it keeps the runtime body portable, recoverable, and explicit. It is weakest when it absorbs sibling meaning or turns root docs into inventory ledgers.
Read only what matches your entry need.
The route vocabulary behind this entry surface is governed by START_HERE_ROUTE_CONTRACT.
| Route mode | Use when | Start surface |
|---|---|---|
first-reading |
you need the shortest runtime overview | README.md |
runtime-design |
the system form, topology, or source/runtime split may move | DESIGN |
agent-guidance |
root or nested agent guidance may move | DESIGN.AGENTS, AGENTS |
source-install |
a checkout must create or refresh a runtime layout | install/DEPLOYMENT, mechanics/config-projection |
runtime-operation |
live operation, logs, status, smoke, or incidents are involved | operations/RUNBOOK, scripts/README |
mechanic-change |
a runtime move belongs to a package or part | mechanics/README |
machine-fit |
host facts, platform adaptation, Windows, or model fit are involved | mechanics/machine-fit |
diagnostics-repair |
diagnosis, degradation receipts, or repair handoff are involved | mechanics/diagnostic-spine, mechanics/runtime-repair |
direction-change |
runtime-wide direction, horizon, or future trigger changes | ROADMAP |
release-history |
release-visible history changes | CHANGELOG |
decision-rationale |
future agents need to know why a route changed | docs/decisions |
- Source checkout:
~/src/abyss-stackby default, or${AOA_SOURCE_ROOT}when intentionally relocated. - Deployed runtime root:
/srv/AbyssOS/abyss-stack. - Deployed config tree:
/srv/AbyssOS/abyss-stack/Configs. - Source checkout shape is authoritative for the GitHub mirror and install
source. Do not edit
/srv/AbyssOS/abyss-stackas if it were the source repository.
The GitHub mirror is source/install-only. It may carry docs, templates,
schemas, public examples, tests, workflows, and scripts needed to create a
runtime. It must not carry live Secrets/, Logs/, Models/, stack.env,
rendered private config, local databases, model files, or private captures.
Runtime state is created from the checkout through scripts/aoa-install-layout,
scripts/aoa-sync-configs, and scripts/aoa-bootstrap-configs.
Before trusting or publishing a runtime claim, route it through the smallest surface that can answer it.
| Claim question | Check |
|---|---|
| Does this belong to the runtime substrate at all? | CHARTER, BOUNDARIES |
| Does this preserve the intended runtime form? | DESIGN |
| Does this move runtime-wide direction? | ROADMAP |
| Is this release-visible history? | CHANGELOG |
| Is this durable rationale rather than active law? | docs/decisions |
| Is this mechanic-local doctrine, validation, or landing detail? | mechanics, then the package README.md |
| Is this live state, private machine data, a model, a log, or a secret? | deployed runtime or operator-owned surface, not git |
| Does this copy AoA, ToS, skill, eval, memo, routing, playbook, KAG, stats, or agent authority? | the sibling owner repository |
The current v0.2.2 contour is runtime-substrate hardening, not AoA or ToS
meaning and not a claim of live service mutation.
The active source shape is:
- source/install mirror stays portable while live runtime state stays outside git
- mechanics are convex packages with parts, local roadmaps, landing logs, provenance, validation, and package-local legacy containment
- root operator commands remain stable wrappers while implementation bodies live beside their owning mechanic parts
- source/runtime parity uses synthetic release checks by default and live checks only through explicit operator intent
- the default source-owned runtime selection is the conservative
substrateprofile: storage underabyss-stack; workflow automation, local workers, retained fallback gateways, federation, tools, and observability layer on top explicitly abyss-machineis consumed through read-only bridge and machine-fit packets without transferring machine ownership into this repolangchain-apion5403,llama.cpp, and LangGraph remain bounded local-worker/inference posture, not proof of full autonomy- federation seams stay opt-in advisory inputs until explicit live-consumption decisions land
- diagnostic spine and runtime repair expose read models, receipts, and handoff candidates before any live mutation authority
- MCP access planes live under
mcp/and expose derived routes, not new source authority memo/is the local runtime memory port for candidates, receipts, exports, and stack-local notes
Detailed package contracts belong in mechanic packages. Detailed release
history belongs in CHANGELOG.md.
Runtime moves live under mechanics. Each package owns its local card, parts, direction, provenance, roadmap, landing log, and validation route.
| Package | Use for |
|---|---|
| runtime-lifecycle | layout, start/stop, smoke, logs, status, user units |
| config-projection | source templates, env examples, bootstrap, sync, rendering |
| machine-fit | host facts, fit records, platform adaptation, Windows, model fit |
| inference-pilots | local trials, llama.cpp, Qwen, LangGraph, promotion evidence |
| federation-seams | memo, eval, playbook, KAG, RPG, and ToS runtime seams |
| governed-execution | governed runs, return policy, autonomy status, candidate exports |
| diagnostic-spine | read-only diagnosis, diagnostic artifacts, truth-goal status |
| runtime-repair | degradation receipts, repair-safe closeout, dry-run repair posture |
| agon-runtime | Agon dry-run runtime kernels and contained legacy receipts |
| experience-runtime | contained experience runtime archives and distillation stop-lines |
Root-adjacent districts own repository-level function, not mechanic-local storage.
| District | Use for |
|---|---|
| compose | profile, preset, module, and tuning composition |
| config-templates | public-safe config templates synced into runtime |
| docs | repo-level operator, release, path, security, and decision surfaces |
| env | public environment examples |
| mcp | stdio/local access planes for owner-layer context |
| memo | local runtime memory candidates, receipts, exports, and notes |
| scripts | stable operator wrappers and repository validators |
| systemd | user-unit source skeletons and managed working-service adapters |
| tests | repository-level tests and validation routes |
| .agents | repo-local agent overlays and fast-loop lanes |
| .github | GitHub-native validation and landing surfaces |
District gates explain local handling. They do not replace root authority, mechanic packages, deployed runtime state, or sibling repositories.
Use scripts/release_check.py for broad release-facing or repo-wide
validation.
Exact current command lanes live in AGENTS, the nearest nested
AGENTS.md, scripts/README, tests/README,
and package-local mechanic cards. Diagnostic catalog checks belong to
diagnostic spine and the scripts
district, not this front door.
Live runtime checks belong in operations/RUNBOOK and should be run only when the operator intentionally checks the deployed runtime.
Grow the stack by making the next runtime route clearer.
Add mechanics, scripts, docs, schemas, examples, tests, decisions, and generated companions only where they improve reviewability and preserve source/runtime and sibling-owner boundaries. When a detail belongs to a mechanic, changelog, roadmap, quest, decision record, deployed runtime, or sibling repository, route it there instead of loading the README.