docs: add README.md — command center knowledge base overview

2026-08-31 15:45:47 -07:00
parent 5e27c67d87
commit 898519712b
1 changed files with 73 additions and 0 deletions
@@ -0,0 +1,73 @@
+# OMP — Command Center
+
+Configuration repository for Frank's homelab fleet and the agent tooling that runs on it.
+
+## The Fleet
+
+| Host | Role | IP |
+|------|------|-----|
+| **Dankware** | Workstation (CachyOS, Niri/Wayland, RTX 4070) | — |
+| **Dankclaw** | Server (Podman, reverse proxy, Gitea, NPU) | 192.168.0.143 |
+| **Dankserver** | LLM inference backend | 192.168.0.235 |
+
+Dankware is the primary host — this repository lives at `~/.omp/` and drives the OMP agent harness.
+
+## Structure at a Glance
+
+```
+~/.omp/
+├── agent/              # OMP harness runtime
+│   ├── config.yml      # Live agent configuration
+│   ├── models.yml      # Model providers (imported from ~/.pi/agent/models.json)
+│   ├── APPEND_SYSTEM.md  # System prompt extensions
+│   ├── managed-skills/ # Managed skills (SKILL.md bundles)
+│   ├── models.db       # Model cache
+│   └── sessions/       # Persistent session state
+├── omp-docs/           # Knowledge base (source of truth)
+│   ├── index.md        # KB index — start here
+│   ├── system/         # Fleet hardware, OS, network
+│   ├── tools/          # Installed software (llama.cpp, Gitea, Caddy, niri…)
+│   ├── core/           # Agent config conventions (settings, models, AGENTS.md)
+│   ├── pi/             # Legacy pi-era config reference
+│   ├── engineering/    # SDLC, languages, infra, skills ecosystem
+│   ├── research/       # Decision-support research (not yet facts)
+│   ├── references/     # OKF spec, maintenance procedures
+│   ├── caddy/          # Reverse proxy configuration
+│   ├── packages/       # Pi packages and extensions
+│   ├── inventory/      # Userspace config census
+│   ├── reports/        # Investigation reports
+│   ├── log.md          # Change log
+│   └── .okf/           # OKF v0.1 conformance config
+├── scripts/            # Utility scripts (kb-lint.sh)
+├── plugins/            # npm plugins (pi-peon, etc.)
+├── puppeteer/          # Browser automation config
+├── .githooks/          # Pre-commit hook
+├── .gitignore          # Runtime state ignored (databases, logs, cache)
+├── AGENTS.md           # Agent conventions (niri reload, keybindings)
+└── README.md           # This file
+```
+
+## What Lives Here
+
+**Config in, state out.** Everything tracked is something an agent reads or writes. Runtime databases (`*.db`, `*.sqlite`), logs, caches, and session state are git-ignored — git history captures configuration changes, not agent heartbeat.
+
+## Quick Start
+
+| Task | How |
+|------|-----|
+| Read the knowledge base | `omp-docs/index.md` — every concept linked from here |
+| Check agent config | `agent/config.yml` + `agent/models.yml` |
+| Lint the KB | `scripts/kb-lint.sh` (OKF v0.1 conformance) |
+| View change log | `omp-docs/log.md` |
+| Run a pre-commit | `.githooks/pre-commit` |
+
+## Conventions
+
+- **OKF v0.1** — every doc file carries YAML frontmatter with a `type:` field. `index.md` files are directory listings (no frontmatter).
+- **Progressive disclosure** — `index.md` is a landing page; drill into subdirectories for detail.
+- **Verified facts** — stamped with `verified:` when probed against the live fleet. Trust over memory.
+- **Two config copies** — `~/.omp/agent/models.yml` is generated from `~/.pi/agent/models.json`. Edits touch both.
+
+## Legacy Notes
+
+The pi-era configuration at `~/.pi/` still exists for reference. Live harness config lives in `~/.omp/`. New managed skills live in `~/.omp/agent/managed-skills/` alongside legacy symlinked skills at `~/.pi/agent/skills/`.