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

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:

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:

Draft mode
- The agent can prepare changes without committing them immediately.
Validated commit mode
- The server validates Markdown metadata, links, YAML structure, and required fields before creating a commit.
Review mode
- Important changes can be held for human approval.
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:

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

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:

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.