--- owner: gmikcon status: draft last_reviewed: 2026-05-09 review_interval: 30d confidence: medium source_of_truth: planning --- # Gnexus Book Project Implementation Notes ## Purpose Gnexus Book is intended to be a knowledge base for the owner's digital and server infrastructure. The documentation should be useful for both humans and AI agents. Its main job is to explain the high-level structure of the infrastructure: what exists, where it runs, how components depend on each other, and how operational changes should be made. The project should not become only a folder of Markdown files. Markdown is the preferred storage and reading format, but the system also needs an operational layer that helps AI agents keep the documentation current. ## Agreed Direction The source of truth should remain a Git repository containing Markdown and structured inventory files. Git provides: - version history; - rollback; - review; - portability; - compatibility with existing developer tools; - easy offline access. However, Git should not be the main editing interface for AI agents. The agent workflow of cloning the repository, editing files manually, committing, and pushing is too cumbersome and too error-prone for regular documentation maintenance. Instead, the project should include a documentation server that works as an operational layer over the repository. ## Target Architecture ```text Human / AI Agent | v Documentation Server | +-- Markdown and YAML Git repository +-- Search index +-- Validation layer +-- Commit manager +-- Audit log +-- Web documentation UI +-- Agent API / MCP interface ``` ## Storage Model The repository should use a hybrid documentation model: - Markdown files for architecture, explanations, runbooks, decisions, and operational notes. - YAML files for structured inventory such as hosts, services, domains, ports, databases, and relationships. - YAML files for hardware, virtual machines, traffic routes, and exposure maps. - Schemas for validating structured files. - Generated indexes for navigation and agent-friendly lookup. Markdown remains the main human-readable format, but structured YAML should be used where agents need predictable data. ## Documentation Server The documentation server should provide a safer and more convenient interface for maintaining the documentation. Expected responsibilities: - read Markdown and YAML documents; - expose documentation through a web UI; - expose an API for AI agents; - provide search; - accept proposed changes; - validate document structure and inventory schemas; - manage commits to the Git repository; - optionally create review records or pull requests; - track document freshness; - maintain an audit trail of changes. The documentation server should hide most raw Git operations from agents. For the MVP, the server should be hosted privately on a VPS inside the local network. It should not be publicly exposed. The server should create local Git commits, while pushing to the remote repository remains a manual owner action after reviewing the commit history. The first UI should be focused on reading and inspection rather than editing: documents, inventory records, validation status, freshness reports, traffic routes, and recent changes. ## Agent Interface The agent interface should expose domain-level operations instead of only raw file editing. Examples: ```text search_docs(query) read_doc(path) list_inventory(type) create_doc(path, content) propose_change(path, patch, reason) add_service(data) update_service(id, data) check_staleness() commit_changes(message) ``` For example, an agent should ideally be able to call `add_service(data)` instead of manually editing `services.yml`. The implementation may begin as a REST API and later be wrapped as an MCP server, or it may provide MCP support from the start. ## Change Modes The server should support several change modes: 1. Draft mode - The agent can prepare changes without committing them immediately. 2. Validated commit mode - The server validates Markdown metadata, links, YAML structure, and required fields before creating a commit. 3. Review mode - Important changes can be held for human approval. 4. Direct commit mode - Low-risk changes can be committed automatically by trusted agents. The exact authorization and review rules still need to be designed. ## Freshness Model Documents should include metadata that helps determine whether they are still reliable. Example: ```yaml --- owner: gmikcon status: active last_reviewed: 2026-05-09 review_interval: 90d confidence: medium source_of_truth: manual --- ``` The server should be able to report: - stale documents; - documents without owners; - services without runbooks; - hosts without backup policy; - domains without DNS notes; - inventory records without linked documentation; - public traffic routes without linked services; - services marked public without a traffic route; - broken internal links. ## Initial Repository Structure The exact structure is still flexible, but the current working proposal is: ```text gnexus-book/ README.md 00-overview/ infrastructure-map.md project-implementation-notes.md principles.md glossary.md 10-systems/ hardware/ servers/ virtualization/ domains/ networks/ traffic-routes/ storage/ databases/ applications/ automations/ 20-services/ gnexus-auth.md websites.md mail.md backups.md monitoring.md 30-runbooks/ deploy.md restore-backup.md rotate-secrets.md incident-response.md add-new-service.md 40-inventory/ hardware.yml hosts.yml virtual-machines.yml domains.yml services.yml traffic-routes.yml credentials-map.md 50-decisions/ ADR-0001-documentation-structure.md 90-maintenance/ documentation-rules.md freshness-checks.md review-log.md ``` ## Practical MVP The first implementation should stay small. Recommended MVP: - Markdown and YAML repository structure. - Basic documentation conventions. - YAML inventory schemas. - Simple documentation server. - Git adapter for read/write/commit operations. - Search using local text search first. - API for reading, searching, proposing changes, and committing validated updates. - Basic freshness checks. - Custom Vue.js web UI based on `gnexus-ui-kit`. Possible minimal API: ```text GET /docs GET /docs/{path} GET /search?q= GET /inventory/{type} GET /traffic-routes POST /docs/{path}/propose POST /inventory/services POST /commit GET /health/freshness ``` ## Later Capabilities Possible later additions: - MCP server for direct AI-agent access. - Embedding-based semantic search. - Auto-generated documentation indexes. - Static documentation export. - Rich web editor for humans. - Approval workflow. - Scheduled freshness review. - Infrastructure probes that compare documentation with real state. - CI validation for links, schemas, and metadata. - Integration with deployment systems or monitoring tools. ## Open Questions - Should the documentation server live inside this repository or in a separate repository? - Which stack should be used for the server: Python/FastAPI, Laravel, Node.js, or something else? - Should MCP support be part of the first MVP? - What changes may agents commit directly? - What changes require human review? - How much of the custom Vue UI should be included in the first MVP? - How should secrets and sensitive access information be represented without exposing actual credentials? - How detailed should the first traffic route records be? - Which exact virtualization layer should be recorded for the home servers? - What review rules should apply to traffic exposure changes? ## Current Decision Use Markdown and YAML in Git as the durable storage format. Build a documentation server that acts as the main operational interface for agents and humans. The server should provide controlled editing through API, validation, search, freshness checks, local commit management, and a custom Vue.js UI based on `gnexus-ui-kit`. The next planning step is to define the MVP implementation plan and choose the first version of the repository structure, schemas, and server responsibilities.