--- owner: gmikcon status: draft last_reviewed: 2026-05-09 review_interval: 30d confidence: medium source_of_truth: planning --- # Gnexus Book MVP Implementation Plan ## Planning Method This plan combines two sources: - explicit answers from the owner; - implementation defaults chosen by the agent when a decision is not risky or can be changed later. Open questions are grouped as an interview checklist. The default choices in this document should be treated as provisional until they are confirmed or changed. ## Current Goal Build a maintainable documentation system for personal digital and server infrastructure. The first version should make it easy for an AI agent to: - find existing infrastructure knowledge; - read canonical documentation; - update Markdown and YAML safely; - validate documentation structure; - create Git commits through a controlled interface; - identify stale or incomplete documentation. ## Default Decisions ### Repository Role Decision: keep this repository as the canonical documentation repository. Reasoning: - Markdown and YAML remain simple and portable. - Git gives history, review, rollback, and diffability. - The documentation server can be replaced later without migrating the knowledge base. ### Documentation Server Location Default: keep the server implementation in the same repository during MVP. Proposed layout: ```text gnexus-book/ docs content... server/ app/ tests/ pyproject.toml ``` Reasoning: - simpler local development; - easier to keep schemas, API, and docs conventions together; - no early overhead of coordinating two repositories. Possible later change: extract `server/` into a separate repository if it becomes a reusable product. ### Server Stack Default: Python + FastAPI. Reasoning: - good fit for agent tooling; - simple file and Git operations; - easy YAML, Markdown, and schema validation; - easy future MCP integration; - lightweight enough for a personal infrastructure documentation server. Alternative stacks: - Laravel if tighter integration with existing PHP/Laravel infrastructure matters more. - Node.js if the web UI becomes the dominant part of the project. ### Web UI Decision: build a custom web UI instead of using MkDocs as the primary documentation UI. Use: - Vue.js for the frontend; - `gnexus-ui-kit` as the UI foundation; - FastAPI for the backend API, validation, freshness checks, and controlled writes. Reasoning: - the documentation system needs more than static rendering; - the UI should expose inventory, relationships, stale docs, and agent-oriented operations; - this is a useful project for testing Vue support in `gnexus-ui-kit`; - a custom UI can become the main operational surface for both humans and agents. Static rendering can still be added later as an export feature, but it is not the primary MVP direction. ### Agent Interface Default: REST API first, MCP later. Reasoning: - REST is simpler to debug and test. - MCP can wrap stable domain operations once the workflow is clearer. The API should still be designed with MCP-style operations in mind. ### Change Policy Decision: - low-risk documentation changes may be committed automatically; - infrastructure facts, access paths, backup policies, and security-sensitive changes require review mode first; - secrets must never be stored directly. Agents may create new documentation pages without review if validation passes and the change does not introduce sensitive information. ### Deployment Model Decision: the MVP should not be public. The documentation server should be hosted on a VPS inside the local network. It may be reachable from trusted local or VPN-accessible environments, but it should not be exposed as a public internet service. Initial Git behavior should be local commits only. Remote push should remain a manual owner action for the MVP. The owner can periodically review commits and run `git push` manually. ## Known Infrastructure Context This section captures early facts that should influence the data model. It is not yet the canonical inventory. ### Physical Infrastructure Known physical server: ```yaml id: hp-proliant-dl380-g6 name: HP ProLiant DL380 G6 type: physical-server status: active location: home os: Ubuntu 22.04.4 LTS kernel: 5.15.0-176-generic virtualization_stack: type: kvm-libvirt libvirt_version: 8.0.0 management_tools: - virsh - cockpit-machines management: cockpit: url: https://192.168.1.130:9090/system version: 310.1-1~bpo22.04.1 ``` The home infrastructure currently has three physical servers and is expected to grow to four. One of the servers runs approximately two dozen VPS/VM instances. Confirmed on `hp-proliant-dl380-g6`: - system libvirt connection: `qemu:///system`; - active services: `libvirtd`, `virtlogd`; - installed stack includes `libvirt-daemon-driver-qemu`, `libvirt-clients`, `libvirt-daemon-system`, `python3-libvirt`, and `cockpit-machines`; - user `bserv` belongs to the `libvirt` group. Known VM state from system libvirt: ```yaml running: - ovpn - gitbucket - alex - anicusi - navi - mctl - jellyfin - gnexus-home - nextcloud - ovpn_reserv - home - transmission - files - gnauth shut_off: - cats - fdroid - kitan - m1connect - mail-server - mine - radio - shome - topics - unmanic - vec_search - yt ``` Known libvirt networks: ```yaml - default - isolated-net - OpenNet - united ``` Known libvirt storage pools: ```yaml - default - jellyfin_os - vm_main ``` ### Network Edge Known local edge device: ```yaml id: pfsense-router name: pfSense Router type: router-firewall status: active location: home management_url: https://192.168.1.1/ ``` ### Public Entry And VPN Path Known public-side components: - domain: `gnexus.space`; - external VPS; - external VPS acts as a VPN server; - public traffic is sent through the VPN tunnel to an internal VPS; - the internal VPS runs nginx; - nginx proxies traffic to target VPS instances or other internal machines. Canonical traffic pattern: ```text Internet -> gnexus.space -> external VPS -> VPN tunnel -> internal VPS -> nginx -> target VPS or internal machine -> target service ``` The data model should make this route explicit enough for AI agents to understand what is public, what is VPN-only, and what is local-only. ## MVP Scope The MVP should include only the minimum that proves the full loop: ```text read -> search -> propose/update -> validate -> commit -> render -> freshness check ``` ### Included - documentation directory conventions; - Markdown frontmatter convention; - structured YAML inventory; - schemas for core inventory files; - FastAPI documentation server; - Git read/write/commit adapter; - local text search; - basic validation; - basic freshness report; - custom Vue-based documentation and maintenance UI; - initial agent-oriented API. ### Excluded For MVP - embedding search; - automatic infrastructure discovery; - complex approval workflow; - multi-user permissions; - remote deployment automation; - automatic Git push; - secret storage; - integration with monitoring systems. ### UI Scope The MVP UI is not a document editor. Included UI capabilities: - browse documents; - view inventory records; - view freshness and validation reports; - view traffic route records; - view recent commits or change history if available. Excluded UI capabilities: - direct Markdown editing; - direct YAML editing; - visual topology map; - approval workflow UI. All writes should go through the API and agent workflow during the MVP. ## Proposed Repository Layout ```text gnexus-book/ README.md 00-overview/ infrastructure-map.md mvp-implementation-plan.md project-implementation-notes.md principles.md glossary.md 10-systems/ hardware/ servers/ virtualization/ domains/ networks/ traffic-routes/ storage/ databases/ applications/ automations/ 20-services/ 30-runbooks/ add-new-service.md incident-response.md restore-backup.md 40-inventory/ hardware.yml hosts.yml virtual-machines.yml services.yml domains.yml traffic-routes.yml databases.yml backups.yml 50-decisions/ 60-generated/ inventory-index.md 90-maintenance/ documentation-rules.md freshness-checks.md review-log.md schemas/ hardware.schema.json host.schema.json virtual-machine.schema.json service.schema.json domain.schema.json traffic-route.schema.json database.schema.json backup.schema.json server/ app/ main.py config.py docs_repository.py git_adapter.py inventory.py markdown.py search.py validation.py freshness.py tests/ pyproject.toml ui/ package.json src/ ``` ## Core Data Model ### Hardware Node Represents a physical server or important physical infrastructure device. The infrastructure includes several physical home servers, with more expected later. Physical topology is important and should be modeled explicitly rather than hidden inside generic host records. Required fields: - `id` - `name` - `type` - `status` - `location` - `hardware_role` - `management_address` - `network_interfaces` - `runs_hosts` - `docs` - `last_reviewed` Example: ```yaml - id: home-server-01 name: Home Server 01 type: physical-server status: active location: home hardware_role: - virtualization-host - storage management_address: unknown network_interfaces: [] runs_hosts: - main-vps docs: ../10-systems/hardware/home-server-01.md last_reviewed: 2026-05-09 ``` ### Host Represents a physical server, VPS, local machine, VM, container host, or managed hosting environment. For physical machines, a `hardware` record should exist as well. The `host` record describes the operating system or runtime environment; the `hardware` record describes the physical machine. Required fields: - `id` - `name` - `type` - `status` - `environment` - `provider` - `location` - `roles` - `hardware_node` - `docs` - `last_reviewed` Example: ```yaml - id: main-vps name: Main VPS type: vps status: active environment: production provider: unknown location: unknown roles: - web - database hardware_node: home-server-01 docs: ../10-systems/servers/main-vps.md last_reviewed: 2026-05-09 ``` ### Virtual Machine Represents a VPS/VM running on a physical host or virtualization platform. This is separate from `service` because the same VM can run multiple services and participate in traffic routing. Required fields: - `id` - `name` - `status` - `hypervisor_host` - `os` - `addresses` - `exposed_ports` - `local_only` - `runs_services` - `docs` - `last_reviewed` ### Service Represents an application, system service, website, worker, scheduled task, or infrastructure service. Websites are modeled as services that use one or more domains. Required fields: - `id` - `name` - `type` - `status` - `host` - `domains` - `ports` - `criticality` - `docs` - `runbook` - `last_reviewed` ### Traffic Route Represents how traffic reaches a service or host. This model is important because the infrastructure contains a mix of externally exposed services, local-only services, port forwards, reverse proxies, VPS-to-host relationships, and internal routing. Required fields: - `id` - `name` - `status` - `source` - `entrypoint` - `path` - `destination` - `protocols` - `ports` - `exposure` - `used_by` - `docs` - `last_reviewed` Allowed `exposure` values: - `public` - `vpn` - `local` - `private` Example: ```yaml - id: public-web-to-main-vps name: Public web traffic to Main VPS status: active source: internet entrypoint: router-or-edge-proxy path: - public-ip - edge-router - reverse-proxy destination: main-vps protocols: - https ports: - 443 exposure: public used_by: - example-service docs: ../10-systems/traffic-routes/public-web-to-main-vps.md last_reviewed: 2026-05-09 ``` ### Domain Represents a domain or subdomain. Required fields: - `id` - `fqdn` - `status` - `registrar` - `dns_provider` - `points_to` - `used_by` - `docs` - `last_reviewed` ### Database Represents a database instance or logical database. Required fields: - `id` - `engine` - `version` - `host` - `used_by` - `backup_policy` - `docs` - `last_reviewed` ### Backup Policy Represents backup rules and recovery expectations. Required fields: - `id` - `target` - `method` - `frequency` - `retention` - `storage` - `restore_runbook` - `last_tested` - `last_reviewed` ## Markdown Frontmatter Each important Markdown document should use frontmatter: ```yaml --- owner: gmikcon status: active last_reviewed: 2026-05-09 review_interval: 90d confidence: medium source_of_truth: manual --- ``` Required frontmatter fields for MVP: - `owner` - `status` - `last_reviewed` - `review_interval` - `confidence` - `source_of_truth` Allowed `status` values: - `draft` - `active` - `deprecated` - `archived` Allowed `confidence` values: - `low` - `medium` - `high` ## Agent API MVP ### Read Operations ```text GET /docs GET /docs/{path} GET /search?q= GET /inventory/{type} GET /inventory/{type}/{id} GET /traffic-routes GET /health/freshness ``` ### Write Operations ```text POST /docs/{path} POST /docs/{path}/propose POST /inventory/{type} PATCH /inventory/{type}/{id} POST /traffic-routes PATCH /traffic-routes/{id} POST /commit ``` The commit endpoint should receive a short agent-provided summary and use it as the commit message or as the main part of the commit message. Example request: ```json { "summary": "Document external VPS traffic route", "details": "Added traffic route from gnexus.space through external VPS and VPN tunnel to internal nginx proxy." } ``` Current MVP implementation starts with a safer pending-changes layer: ```text GET /changes GET /changes/{id} POST /changes ``` Pending changes are stored under `90-maintenance/pending-changes/` and are not applied automatically. ### Validation Operations ```text POST /validate GET /validate ``` Current MVP implementation has `GET /validate` for read-only validation reporting. Write-side validation can later reuse the same validation module before accepting changes. ### Generated Output ```text POST /generate/inventory-index ``` ## Agent Change Rules Default rules for AI agents: - Do not store passwords, tokens, private keys, recovery codes, or secret values. - Store references to secret locations instead, for example password manager item names or vault paths. - Prefer structured inventory operations over raw Markdown edits when changing infrastructure entities. - Update `last_reviewed` only when the agent has actually verified the information. - Do not mark `confidence: high` unless the information came from a reliable source or was explicitly confirmed. - Create review-mode changes for security-sensitive or access-related updates. - Every service should have a linked docs page. - Every critical service should have a linked runbook. ## Freshness Checks The MVP freshness report should detect: - Markdown documents missing frontmatter; - documents past their review interval; - inventory records missing required fields; - inventory records pointing to missing docs; - services without runbooks; - critical services without backup notes; - domains not linked to services; - public traffic routes without linked services; - services marked public without a traffic route; - virtual machines without a physical or hypervisor host; - broken relative links. ## Implementation Phases ### Phase 1: Documentation Foundation Deliverables: - create repository structure; - add documentation rules; - add Markdown frontmatter convention; - add starter inventory files; - add starter schemas; - add custom UI foundation. Done when: - documentation can be read through the local UI or API; - inventory files have clear expected fields; - a human or agent knows where to add new infrastructure facts. ### Phase 2: Validation Foundation Deliverables: - implement schema validation for YAML inventory; - implement Markdown frontmatter validation; - implement link checks; - add tests for validators. Done when: - invalid inventory is rejected; - missing frontmatter is reported; - broken doc references are reported. Current status: - `GET /validate` exists; - YAML inventory parsing works through `PyYAML`; - required inventory fields are checked from schema metadata; - JSON schema files are checked for parseability; - Markdown frontmatter is checked; - inventory `docs:` links are checked; - full JSON Schema semantics are not implemented yet. ### Phase 3: Read API Deliverables: - FastAPI app skeleton; - list docs endpoint; - read doc endpoint; - inventory read endpoint; - search endpoint. Done when: - an agent can discover and read documentation without direct file access. ### Phase 4: Write API And Git Adapter Deliverables: - controlled document writes; - inventory create/update operations; - diff/proposal support; - Git commit operation; - audit log entry for changes. Done when: - an agent can update docs through the server and create a validated commit. Current status: - pending-change records can be created and read through API; - `kind=doc` pending changes can be applied after validation; - `kind=inventory-item` pending changes can update existing inventory records after validation; - `kind=inventory-item` pending changes can create new inventory records after validation; - failed doc apply attempts are rolled back; - failed inventory item apply attempts are rolled back; - replacing whole inventory files is not implemented yet; - local commit workflow exists with explicit file lists; - `git push` remains manual. ### Phase 5: Freshness And Generated Indexes Deliverables: - freshness report endpoint; - generated inventory index; - stale document report; - missing runbook report. Done when: - the system can tell which documentation needs attention. ### Phase 6: Agent Workflow Hardening Deliverables: - document allowed agent workflows; - define review-required change types; - add tests for risky update paths; - optionally expose MCP-compatible operation names. Done when: - agent maintenance is predictable enough to use regularly. ## Interview Checklist These questions should be answered before or during implementation. Defaults are provided where reasonable. ### Infrastructure Shape 1. What are the first infrastructure entities we should document? Decision: hosts, services, domains, databases, backups, hardware infrastructure, virtualization, and traffic routes. 2. Do you want to include local development environments in the inventory? Default: yes, but mark them as `environment: local`. 3. Should websites be modeled as services, domains, or a separate entity? Decision: websites are services that use one or more domains. ### Server And Deployment 4. Should the documentation server run only locally at first? Decision: no public access; hosted on a VPS inside the local network. 5. Should it push to a remote Git repository during MVP? Decision: no. The server creates local commits only; the owner reviews and pushes manually. 6. Should the documentation web UI be public, private, or local-only? Decision: private/local-network only. ### Agent Permissions 7. Which agents are allowed to commit directly? Default: none until the workflow is tested. 8. Which changes should always require review? Default: access, security, backup, network exposure, and critical service changes. 9. Should agents be allowed to create new docs without review? Decision: yes, if validation passes and no sensitive fields are introduced. ### Secrets 10. Where should secret references point? Default: named password-manager entries or future dedicated secret storage paths, never raw values. 11. Should the documentation mention usernames, hostnames, and internal IPs? Decision: yes for operational value, but never raw passwords, tokens, private keys, or recovery codes. ### Technology 12. Is Python/FastAPI acceptable for the server? Decision: yes. 13. Is MkDocs Material acceptable for the first documentation UI? Decision: no. Use a custom Vue UI based on `gnexus-ui-kit`. 14. Should MCP be in MVP or phase 2? Default: phase 2, after REST operations stabilize. 15. Which virtualization stack is used on the home servers? Decision: at least HP ProLiant DL380 G6 uses KVM/QEMU through system libvirt (`qemu:///system`), managed with Cockpit Machines and `virsh`. 16. Is a visual topology map required in MVP? Decision: no. The priority is agent-readable structure, not visual representation. 17. Should the UI support editing in MVP? Decision: no. The UI should browse and report; editing goes through API and agent workflows. 18. How should commit messages be created? Decision: the agent passes a short change summary, and the server uses it for the Git commit message. ## Immediate Next Steps 1. Confirm or adjust the default decisions. 2. Create the documentation foundation files. 3. Define the first YAML schemas. 4. Scaffold the FastAPI server. 5. Scaffold the Vue UI with `gnexus-ui-kit`. 6. Implement read-only API first. 7. Add validation. 8. Add controlled writes and local Git commit support. 9. Add traffic route views. 10. Add recent local commit/change history view if practical. ## Current Working Recommendation Proceed with: - monorepo layout; - Python/FastAPI server under `server/`; - custom Vue UI under `ui/` using `gnexus-ui-kit`; - Markdown and YAML as canonical storage; - REST API first; - MCP wrapper later; - private local-network deployment on a VPS and local Git commits for MVP; - manual owner-controlled Git push after commit review; - first-class modeling for physical hardware, VPS/VMs, services, domains, databases, backups, and traffic routes; - no visual topology map in MVP; - read-only UI for documents, inventory, freshness, validation, and traffic routes; - review-required policy for sensitive infrastructure changes. ## Current UI Status The first Vue/Vite UI scaffold exists under `ui/`. Current behavior: - uses `gnexus-ui-kit` as a package dependency; - local development dependency points to `file:../../gnexus-ui-kit`; - imports official kit CSS and Vue components from `gnexus-ui-kit/vue`; - reads backend API through `/api` proxy to `127.0.0.1:3005`; - shows document count, inventory count, pending changes, validation status, freshness status, git status, docs list, inventory types, and changes list. Current UI dev server: ```text http://127.0.0.1:3006/ ``` Known UI follow-up: - resolve or standardize UI kit font asset handling in Vite builds; - add richer inventory item views; - add pending change detail/apply controls; - add commit controls only after review UX is clear.