Portable Wiki Export

​

Motivation

​

Theory & design

​

Folder layout

<output>/
├── wiki/                  # one page per document, id-prefixed filenames
│   └── {id}[-slug].md     # frontmatter + the document's readable content
├── raw/                   # the stored conversion artifact, when one exists
│   └── {id}[-slug].md     # absent entirely for a raw_missing document
├── README.md              # what this is, tenant/project, .mcp.json connection steps
├── AGENTS.md               # untrusted-content boundary, generic-agent flavoured
├── CLAUDE.md               # the same boundary, Claude-flavoured
├── MANIFEST.json          # per-file sha256 + a running chain hash + status
├── .mcp.json              # server URL + env-referenced headers — no credential (W4c)
└── .export.lock           # reservation marker — see Gotchas

​

Frontmatter contract

​

Manifest & consistency, not tamper evidence

{
  "tenant_id": "acme",
  "project_key": "eng",
  "status": "partial",
  "exported_at": "2026-09-21T14:00:00+00:00",
  "files": { "README.md": "…sha256…", "wiki/57.md": "…sha256…" },
  "raw_missing": [{ "document_id": 57, "reason": "missing" }],
  "chain_hash": "…sha256 of the sorted (path, hash) pairs, chained…"
}

​

Untrusted-content boundary

​

CLI — synchronous core (W4a)

php artisan kb:export-wiki \
  --tenant=acme \
  --project=eng \
  --as-user=reviewer@acme.example \
  --output=/tmp/acme-eng-export   # optional — defaults to a fresh
                                    # storage/app/kb-wiki-exports/... path

• --as-user must resolve to a real user with a ProjectMembership in --tenant — an unknown email or a non-member refuses before touching any data.
• Omitting --output builds a destination from slugged, filesystem-safe --tenant/--project segments plus a timestamp and a random suffix (Str::random(8)), so two exports for the same tenant/project started in the same second never collide.
• The exit summary reports status (complete/partial) and warns when raw_missing is non-empty.

​

Async HTTP surface (W4b, ADR 0032 §5/§11/§12)

# Start (or reuse, via idempotency key) an async export
curl -X POST https://<host>/api/admin/kb/exports \
  -H "Authorization: Bearer <sanctum-token>" \
  -H "Content-Type: application/json" \
  -d '{"project_key":"eng"}'
# → 202 { "data": { "id": "...", "status": "queued", ... } }

# Poll
curl https://<host>/api/admin/kb/exports/<id> -H "Authorization: Bearer <sanctum-token>"
# → { "data": { "status": "completed", "document_count": 42,
#               "download_url": "/api/admin/kb/exports/<id>/download" } }

# Download (re-authorizes the CURRENT session, see below)
curl -OJ https://<host>/api/admin/kb/exports/<id>/download -H "Authorization: Bearer <sanctum-token>"

• Idempotency. The key is sha256(tenant, principal, project, normalised options, corpus snapshot, authorization digest). The corpus snapshot (max updated_at + row count) alone would miss an ACL/membership change that removes a document from the principal’s view without touching any updated_at — the authorization digest (sorted visible document ids + role + project memberships) is what forces a narrowed view to invalidate the cache and start a fresh export.
• Principal restoration mirrors ExecuteAgentRunJob. ExecuteKbWikiExportJob takes only scalar ids in its constructor, reloads the User by id inside handle(), re-checks they still hold the export permission (a permission can be revoked between the HTTP request and the worker picking up the job — that’s not retryable, so the job marks the request failed rather than throwing), authenticates as them, and clears the guard in finally — a reused queue worker must never leak one export’s principal into the next.
• Download-time re-authorization is a SECOND, independent gate. The export’s document_ids_json (the ACL-scoped set it was actually computed against) is re-checked against the downloading session’s current visibility on every download, not only at creation. If any id is no longer visible the response is 403 export_invalidated — because a cached idempotency key can outlive the ACL state it was computed from, and this is the catch the idempotency key alone cannot provide. Deliberately not a bypass-auth Laravel signed URL: a link that skips the session couldn’t re-authorize a principal at all.
• Staging, not a new disk. The job zips the folder and stages it on kb.staging.disk (ADR 0029’s upload-staging disk, reused — raw/’s .export.lock reservation marker is excluded from the zip, it has no value once the export is complete).
• Retention. kb:prune-wiki-exports [--dry-run] sweeps by expires_at (not created_at + a status list, like kb:prune-staging-batches) — hourly (onOneServer()->withoutOverlapping()), a deliberately different cadence and knob from the once-nightly staging sweep, because KB_WIKI_EXPORT_RETENTION_HOURS’s default (24h) is short enough that a daily-only sweep would leave expired bundles around for up to a day past expiry.

​

Gotchas & operations

• Destination reservation is atomic. writeFolder() holds an exclusive, non-blocking flock() on a .export.lock file inside the destination for the entire write. Without it, two exports racing the same explicit --output could both observe it empty before either had written anything, then interleave wiki//raw/ files into one folder matching neither export’s manifest. A concurrent attempt is refused immediately (“Another export is already in progress”), before any file is written.
• A non-empty destination is always refused, lock contention aside — a reused directory from a prior, wider-ACL export must never leak documents the current export’s principal cannot read. Point --output at a fresh or empty directory; the CLI’s own default always is one.
• Guard/tenant state is always restored, including when setup itself throws. export()’s finally runs Auth::forgetGuards() unconditionally (never leaves --as-user authenticated on a reused process) and restores the previous tenant, whatever failed along the way.
• wiki/ is the readable copy and may legitimately reconstruct; raw/ never does. Don’t treat their absence/presence symmetrically when reading an export programmatically — check raw_missing for the artifact guarantee, not whether wiki/{id}.md exists (it always does).

​

.mcp.json — no credential, ever (W4c, ADR 0032 §4)

{
  "mcpServers": {
    "askmydocs": {
      "url": "https://<host>/mcp/kb",
      "headers": {
        "Authorization": "Bearer ${ASKMYDOCS_MCP_TOKEN}",
        "X-Tenant-Id": "${ASKMYDOCS_TENANT_ID}"
      }
    }
  }
}

1. Bearer authentication. /mcp/kb is mounted with only EnforceMcpScope (throttle:mcp + mcp.scope, no auth:sanctum — the middleware reads the McpTenantToken bearer directly, hashes and looks it up itself).
2. Principal binding (R33). EnforceMcpScope resolves the token’s created_by user and binds it as the request’s Laravel principal before any tool runs — so AccessScopeScope scopes every MCP retrieval to that user’s ACL, not an unrestricted bypass. Whoever mints their own token sees their own access, never the exporter’s.

​

Round-trip — kb:import-wiki and the MCP tools (W4c, ADR 0032 §10/§11)

• Single-document surface, everywhere except the CLI. POST /api/admin/kb/imports and KbImportWikiTool take {project_key, markdown} — the same shape POST /api/kb/promotion/candidates already validates — because an HTTP client or an MCP tool call has no server-side folder to walk. Only kb:import-wiki {folder} has local filesystem access, so folder-walking is CLI-only; all three surfaces funnel into the identical KbWikiImportService::importDocument().
• Two DIFFERENT path checks, on purpose. {folder} is resolved with realpath() and every candidate file is re-checked to stay under that resolved root — a local-containment concern. The resulting candidate’s eventual KB-disk source_path is separately normalised through KbPath::normalize() (R1) once it is approved and written. Neither substitutes for the other.
• The diff is BODY-only, deliberately. Comparing the whole file against a regenerated export representation would false-positive on every export cycle whose frontmatter serialization or governance fields legitimately shift without an editorial change. Comparing only the Markdown body against DocumentVersionService::contentFor() — the same source wiki/ itself renders from — targets what a person actually edits, and the lookup runs under the IMPORTING user’s own AccessScopeScope: a user who cannot see a slug is told “new”, never “unchanged” for a document they have no visibility into.
• Idempotency has one honest limit. A replayed call resolves the SAME paused flow run rather than starting a second one, but does NOT mint a second usable approval token — the underlying ApprovalTokenManager::reissuePendingForStep() is a one-shot operation per approval record. A replay reports the run’s id with no new token, which is more honest than pretending a second single-use token exists.
• Rate-limited per actor (kb.wiki_export.import_candidates_per_hour, default 30/hour) — the same knob on all three surfaces.

# CLI — the folder-walking surface
php artisan kb:import-wiki /tmp/acme-eng-export \
  --tenant=acme --as-user=reviewer@acme.example
#   unchanged   wiki/57-deploy-runbook.md
#   proposed    wiki/58-incident-2026-08.md  (flow_run_id: ...)
# Import complete: 1 unchanged, 1 proposed, 0 replayed, 0 invalid, 0 other.

# HTTP / MCP — one document at a time
curl -X POST https://<host>/api/admin/kb/imports \
  -H "Authorization: Bearer <sanctum-token>" -H "Content-Type: application/json" \
  -d '{"project_key":"eng","markdown":"---\nslug: incident-2026-08\nid: inc-2026-08\ntype: incident\nstatus: accepted\n---\n\n# Incident 2026-08\n..."}'
# → 202 { "data": { "status": "created", "flow_run_id": "...",
#                    "approval": { "token": "...", "approve_path": "..." } } }

​

Still deferred

• llms.txt/llms-full.txt and the --format=markdown|llms-txt variants — only --format=llm-wiki (the default) exists.
• include_images — figures are omitted by default when the tenant’s PII policy is active (ChunkRedactor rewrites text, not pixels); the opt-in inclusion path is not built.