Auto-Wiki — the self-compiling tier

A second-class ‘auto’ knowledge tier the system builds and maintains itself — enrichment, graph materialisation, concept synthesis, indexing, linting, agentic navigation, and cross-model review — all behind the human > auto > raw firewall.

Motivation

A knowledge base decays unless someone tends it: links rot, concepts go undocumented, related decisions stay disconnected. AskMyDocs compiles its own wiki on top of every ingested corpus and keeps it healthy over time — without ever weakening the human-vouched authoritative tier.

The auto tier and the firewall

The cornerstone is a second-class auto tier (knowledge_documents.generation_source ∈ {human, auto}). AI-compiled knowledge is real, searchable and navigable, but the reranker always ranks human-accepted > auto > raw, and an admin can promote auto → human. Every layer is reversible, audited to kb_canonical_audit, tenant-scoped (R30), and config-gated (default-ON but cleanly degradable, R43). See the anti-hallucination firewall.

The phases

Phase	What it does
Compiler	After ingest, an LLM enriches frontmatter (tags / summary / aliases / cross-references, allow-listed to real neighbours — anti-hallucination).
Evidence-tier	Derives a per-doc evidence tier in the same call; the RAG prompt flags low-confidence claims. See grounding.
Graph canonicalization	Cross-references become real kb_edges + kb_nodes; every auto doc gets a stable auto--namespaced slug → the tier becomes navigable.
Concept synthesis	Recurring concepts across a project become new domain-concept pages, grounded only in the docs that mention them.
Indices + log	Per-project roll-ups + a per-tenant index hub (the agentic map) + the operation log (a read over kb_canonical_audit).
Lint / health	Deterministic checks — dangling / orphan / stale-cross-ref / missing-index — with safe auto-fix.
Agentic navigation	Multi-hop, cycle-safe BFS over the graph, anchor-driven from the index — the “navigate the wiki” primitive beyond 1-hop expansion.
Cross-model review	An independent review-LLM audits each auto page for grounding / novelty / contradictions before it is trusted.
Apply engine	Change/delete suggestions become audited, reversible mutations (add cross-ref / deprecate impacted).
Scheduled maintenance	A daily sweep rebuilds indices, lints, and backfills enrichment — “knowledge improves over time”.

Tri-surface (R44)

Every capability is exposed across PHP / HTTP API / MCP over one shared core service. Representative Artisan commands (all tenant-scoped via --tenant):

php artisan kb:wiki-link 57                          # materialise a doc's cross-refs into edges
php artisan kb:synthesize-concepts eng --limit=10    # synthesize domain-concept pages for a project
php artisan kb:wiki-index --project=eng              # rebuild the index hub + roll-ups
php artisan kb:wiki-lint --project=eng --fix         # health check + safe auto-fixes
php artisan kb:wiki-review 57                        # cross-model grounding/novelty/contradiction audit
php artisan kb:wiki-promote 57                       # promote auto → human (or --discard)
php artisan kb:wiki-maintain --project=eng --fix     # the daily orchestration (also a scheduled slot)

The same operations are HTTP endpoints under /api/admin/kb/* (RBAC-gated) and MCP tools on the enterprise-kb server (KbWikiNavigateTool is the primary agentic surface).

Config gates (R43)

Each phase is independently toggleable and degrades cleanly when off: KB_AUTOWIKI_GRAPH_ENABLED, KB_AUTOWIKI_CONCEPTS_ENABLED, KB_AUTOWIKI_REVIEW_ENABLED (+ a dedicated review model via KB_AUTOWIKI_REVIEW_AI_PROVIDER/_MODEL for true cross-model diversity), KB_CHANGE_AUTOAPPLY_ENABLED (default-OFF). With every flag off, AskMyDocs behaves exactly like its pre-Auto-Wiki self.

Maintenance as a routine (v8.39/W5, ADR 0033)

kb:wiki-maintain’s nightly cron (index rebuild + lint + backfill) can optionally run as a named, observable routine instead of an anonymous scheduler entry — the same padosoft/laravel-routines engine other delegated-agent work in this platform uses. Default OFF (KB_WIKI_ROUTINE_ENABLED, R43): with it off, the cron is byte-identical to before this ADR.

What it is: a routines row (package table, no schema of its own added by AskMyDocs) whose target_type is askmydocs.wiki_maintenance and whose organization_id holds this app’s tenant id — the package has no tenant concept, so WikiRoutineService does the R30 scoping itself. Reading or triggering it goes through AskMyDocs’ own tenant-scoped, RBAC-gated tri-surface — padosoft/laravel-routines’ own generic admin API (api/routines/v1) is turned OFF in this deployment (ROUTINES_API_ENABLED=false) because it has no tenant boundary and would otherwise let any authenticated user of any tenant read every tenant’s routines.

Why no MCP run tool. Starting the routine spends and rewrites auto-tier pages — the same posture the OCR re-run and review-approval surfaces elsewhere in this platform already take. An agent may see KbWikiRoutineStatusTool’s read-only report of the routine’s status, last run, and any pending question; it can never start a run itself.

An honest gap. The routine has no granted mandate this cycle — no step-up consent flow exists yet to authorize one — so it runs with exactly the same authority the unattended cron already had: WikiMaintainer still only ever compiles and lints, never touches a human-tier page. The MandateExceeded/pause-and-ask machinery this engine provides is real and wired through, but nothing in this cycle can trigger it. A future cycle that wants the full “ask a human when it exceeds its mandate” experience needs to build that consent UI first — genuinely separate scope, documented rather than glossed over in ADR 0033.

php artisan kb:wiki-routine status --tenant=acme   # always available, {disabled: true} when the flag is off
php artisan kb:wiki-routine run --tenant=acme      # requires KB_WIKI_ROUTINE_ENABLED=true

Gotchas & operations

• The firewall is non-negotiable: never write retrieval code that ignores generation_source.
• Auto pages are machine-reviewed by a different model than the compiler — point the review override at a distinct provider for real diversity.
• Concept synthesis + maintenance are explicit-trigger / scheduled, never per-ingest, and bounded per run.

Anti-hallucination firewall

Why machine knowledge never outranks human-vouched truth.

Chat & retrieval

How the auto tier feeds grounded, cited answers.