Company Wiki

Mediatech onboarding

Structure

├── AGENTS.md # Schema & operational protocol for the LLM ├── index.md # Machine-readable catalog of all pages + 1-line summaries ├── log.md # Chronological append-only record of updates ├── raw/ # Immutable source documents (transcripts, docs, repos) └── wiki/ # LLM-maintained synthesized knowledge base ├── entities/ # Teams, key stakeholders, critical vendors ├── systems/ # Architectures, services, data pipelines, tech stacks ├── processes/ # Deployments, incident response, sprint cadences └── glossary/ # Internal jargon, acronyms, company metrics

High-Level Methodology

Implementing a Git-backed LLM Wiki requires treating documentation like a software codebase: version-controlled, modular, validated by CI, and maintained via automated agent loops.

                       ┌────────────────────────────────────────┐
                       │               Human Layer              │
                       │   - Drops notes/transcripts into raw/  │
                       │   - Reviews PRs & browses via Obsidian │
                       └───────────────────┬────────────────────┘
                                           │ (git push / gh pr)
                                           ▼
┌───────────────────────┐          ┌───────────────┐          ┌───────────────────────┐
│     Agent Layer       │          │   Git Remote  │          │   Automation / CI     │
│ - Ingests raw files   │ ───────> │               │ <─────── │ - Schema validation   │
│ - Cross-links wiki/   │ (PR/push)│   `main` +    │          │ - Broken link checker │
│ - Compiles index/log  │          │ agent branches│          │ - llms.txt compiler   │
└───────────────────────┘          └───────────────┘          └───────────────────────┘

1. Repository Topology & Branching Architecture

• Two-Tier Directory Structure:
  • raw/: Read-only inbox for source materials (meeting notes, Google Doc exports, Slack threads, architecture decision records).
  • wiki/: Write-target for the LLM agent, containing small, atomic concept pages (entities/, systems/, processes/, glossary/).
• Branch Policy:
  • main: Protected branch representing the verified current state.
  • agent/*: Ephemeral feature branches used by the LLM for multi-file updates and batch ingestions.
  • Direct pushes to main are reserved for human quick-edits or restricted service accounts running fast sync routines.

2. The Agent Operating Loop

• Ingestion Lifecycle:
  1. Human commits a source file to raw/notes-2026-09.md.
  2. Agent parses the source, references index.md, and determines which entity, system, or process pages require creation or mutation.
  3. Agent creates a branch, applies atomic edits across target files, and appends a log entry.
  4. Agent opens a Pull Request using the GitHub CLI (gh pr create) containing a summary of touched pages.
• Autonomous Maintenance (Linting):
  • Periodic scheduled jobs prompt the agent to inspect the graph for dead ends, unlinked references, orphan pages, and stale dates

3. Continuous Integration & Artifact Compilation

• Every push to main or open PR runs an automated CI pipeline:
  • Frontmatter Linting: Validates required YAML fields (title, type, updated, sources).
  • Wikilink Integrity: Verifies all [target-page](./target-page.md) links resolve to existing files.
  • AI Context Compilation: Aggregates core wiki pages into single-file machine contexts (llms.txt and llms-full.txt) published to an internal endpoint or artifact registry for internal retrieval.

Obstacles, Risks & Pragmatic Solutions

1. Merge Conflicts on Central Registry Files

• Obstacle: If the agent and multiple team members try to append entries to a monolithic index.md or log.md, Git line-level collisions will halt automated merges.
• Solution:
  • Fragmented Logs: Replace a single log.md with a directory of small append-only records: log/YYYY-MM-DD-ingest-<topic>.md.
  • Dynamic Indexing: Stop manually editing index.md. Use an automated CI script (or an Obsidian Dataview query) to recompile the index table dynamically from page frontmatter metadata on every build.

2. Local Desktop Sync Clashes (e.g., Obsidian Git)

• Obstacle: Team members running auto-sync plugins (like obsidian-git) on a timer will encounter local rebasing failures if the agent pushes updates to the remote repository while local changes are uncommitted.
• Solution:
  • Configure obsidian-git to use Merge instead of Rebase as its pull strategy. Merge commits preserve dirty working states and allow standard text conflict resolution.
  • Educate the team to keep local notes in raw/personal/ or separate scratchpad folders, minimizing overlapping file locks in wiki/.

3. Human Adoption Friction for Non-Git Users

• Obstacle: Product managers, operations leads, or researchers who do not use terminal Git or Markdown IDEs may avoid contributing or reading the documentation.
• Solution:
  • Git-Backed Web UI: Deploy a zero-friction Git-backed CMS (such as Decap CMS or TinaCMS) or publish the repository as a static internal site via VitePress, MkDocs, or Docusaurus.
  • Chat-Driven Ingestion: Allow users to drop documents or transcripts into a dedicated Slack channel hooked to a webhook/n8n pipeline, which commits the raw file into raw/ on their behalf.

4. Model Hallucinations & Knowledge Drift

• Obstacle: When generating wiki pages, the LLM may synthesize assumptions not present in the source material, contaminating the corporate single source of truth.
• Solution:
  • Strict Grounding Rule in AGENTS.md: Require that every assertion in wiki/ cite its source file path directly in the frontmatter sources: array or via Markdown footnotes ([^raw/file.md]).
  • Review Gate for Ingestions: Configure the agent to submit non-trivial changes via PRs with a needs-review tag, allowing team leads to scan diffs before merging.

5. Repository Bloat from Large Artifacts

• Obstacle: Team members dropping meeting video recordings, large slide decks, or massive raw logs directly into raw/ will cause the Git repository size to balloon, slowing down cloning and agent file-reading.
• Solution:
  • Implement .gitignore rules for binary assets (*.mp4, *.zip, *.pdf).
  • For transcripts or audio, mandate pre-processing through an automated speech-to-text pipeline, committing only the resulting plain-text Markdown transcript into raw/.

Referrences

• HTML instead of MD https://ndoto-g.github.io/doc.html/documents/the-wiki-shape.doc.html