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:

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:

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:

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:

- default
- isolated-net
- OpenNet
- united

Known libvirt storage pools:

- default
- jellyfin_os
- vm_main

Network Edge

Known local edge device:

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:

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:

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

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:

- 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:

- 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:

- 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:

---
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

GET /docs
GET /docs/{path}
GET /search?q=
GET /inventory/{type}
GET /inventory/{type}/{id}
GET /traffic-routes
GET /health/freshness

Write Operations

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:

{
  "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:

GET  /changes
GET  /changes/{id}
POST /changes

Pending changes are stored under 90-maintenance/pending-changes/ and are not applied automatically.

Validation Operations

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

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

What are the first infrastructure entities we should document? Decision: hosts, services, domains, databases, backups, hardware infrastructure, virtualization, and traffic routes.
Do you want to include local development environments in the inventory? Default: yes, but mark them as environment: local.
Should websites be modeled as services, domains, or a separate entity? Decision: websites are services that use one or more domains.

Server And Deployment

Should the documentation server run only locally at first? Decision: no public access; hosted on a VPS inside the local network.
Should it push to a remote Git repository during MVP? Decision: no. The server creates local commits only; the owner reviews and pushes manually.
Should the documentation web UI be public, private, or local-only? Decision: private/local-network only.

Agent Permissions

Which agents are allowed to commit directly? Default: none until the workflow is tested.
Which changes should always require review? Default: access, security, backup, network exposure, and critical service changes.
Should agents be allowed to create new docs without review? Decision: yes, if validation passes and no sensitive fields are introduced.

Secrets

Where should secret references point? Default: named password-manager entries or future dedicated secret storage paths, never raw values.
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

Is Python/FastAPI acceptable for the server? Decision: yes.
Is MkDocs Material acceptable for the first documentation UI? Decision: no. Use a custom Vue UI based on gnexus-ui-kit.
Should MCP be in MVP or phase 2? Default: phase 2, after REST operations stabilize.
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.
Is a visual topology map required in MVP? Decision: no. The priority is agent-readable structure, not visual representation.
Should the UI support editing in MVP? Decision: no. The UI should browse and report; editing goes through API and agent workflows.
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

Confirm or adjust the default decisions.
Create the documentation foundation files.
Define the first YAML schemas.
Scaffold the FastAPI server.
Scaffold the Vue UI with gnexus-ui-kit.
Implement read-only API first.
Add validation.
Add controlled writes and local Git commit support.
Add traffic route views.
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.