[Feature]: Add an org scope to OpenWiki

Summary

Add a third scope, openwiki org, that ingests multiple sources (git repos, developer portals, knowledge bases) into one Open Knowledge Format (OKF) tree with a global namespace, cross-origin references, a bootstrap manifest for agents, and staleness tracking between origins.

Motivation

OpenWiki today has two scopes: repo for a single codebase and personal for a user's local knowledge base. Most engineering work happens between them.

An organization has dozens of repos, a developer portal such as Backstage, and a knowledge base such as Confluence/mkdocs. An agent working in one repo routinely needs the shared API contract, platform deployment conventions, or the architecture decision that explains why a service exists.

The current options are to point the agent at many repo wikis one at a time, or to hand-maintain a personal wiki that mirrors org knowledge. Both fail in the same ways:

• No cross-repo identity. UserAuth in service A and UserAuth in the identity platform look identical to the agent. Nothing marks which one is canonical.
• Redundant context. Every repo wiki re-describes shared systems, so the agent loads the same concept several times and wastes context window.
• Silent staleness. When a schema changes in one repo, the guide describing it in another repo or in Confluence does not know.

Proposed Solution

Introduce openwiki org, a read-only aggregation scope over multiple origins.

                 openwiki org sync
                        │
      ┌─────────────────┼─────────────────┐
      ▼                 ▼                 ▼
 Git repos        Developer portal    Knowledge base
 (source, docs)   (Backstage/MkDocs)  (Confluence, Notion)
      │                 │                 │
      └─────────────────┼─────────────────┘
                        ▼
          Unified OKF tree (org scope)
          - global namespace + cross-refs
          - org manifest for agent bootstrap
          - staleness / drift markers
                        │
                        ▼
          Coding agent (Claude Code, Cursor, Copilot)

1. Global namespace and cross-references

• Reference syntax [[org::<origin>::<path>#<anchor>]], e.g. [[org::payment-gateway::docs/api.md#refund-flow]]. Existing [[page]] links keep resolving within their own scope, so repo and personal wikis are unaffected.
• Each origin can declare the concepts it owns. When two origins define the same term, one is recorded as canonical and the others become references to it.
• sync writes .openwiki/org/manifest.json listing origins, last-synced revisions, the top-level tree, and a dependency graph between origins. An agent reads this one file on start.

2. Declarative multi-origin config (openwiki.org.json)

{
  "$schema": "https://openwiki.ai/schemas/org/v1.json",
  "organization": "acme-engineering",
  "output": "./dist/org-wiki",
  "origins": [
    {
      "type": "git",
      "name": "core-services",
      "targets": [
        "https://github.com/acme/payment-gateway",
        "https://github.com/acme/identity"
      ],
      "include": ["docs/**/*.md", "architecture/*.md", "openapi/*.yaml"]
    },
    {
      "type": "portal",
      "name": "techdocs",
      "engine": "backstage-mkdocs",
      "target": "https://github.com/acme/techdocs"
    },
    {
      "type": "knowledge-base",
      "name": "architecture-wiki",
      "provider": "confluence-mcp",
      "spaces": ["ARCH", "PLAT"]
    }
  ],
  "routing": {
    "prefer_source_provenance": true,
    "max_depth": 4
  }
}

Origin types are pluggable. v1 ships git and one portal engine. Knowledge-base providers go through the existing MCP integration so OpenWiki does not own each vendor's API.

3. Cross-origin staleness tracking When a claim in origin A cites a file in origin B, the manifest records the revision of B it was grounded against. On the next sync, if that path in B changed, the claim is marked, e.g. [Stale: out of sync with payment-gateway@a1b2c3d]. The marker appears in the page body and is queryable from the manifest.

4. CLI

┌─────────────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────┐
│       Command       │                                             Purpose                                             │
├─────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ openwiki org init   │ Scaffold openwiki.org.json and the output directory.                                            │
├─────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ openwiki org sync   │ Fetch all origins, build the tree, write the manifest. --origin <name> for a partial run.       │
├─────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ openwiki org doctor │ Validate config, check credentials per origin, report unresolvable cross-refs and stale claims. │
├─────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ openwiki org status │ Show last sync time and revision per origin without fetching.                                   │
└─────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────┘

5. Access control (v1 scope)

• sync inherits the credentials of whoever runs it. OpenWiki adds no permission model of its own.
• Each origin carries a visibility tag (public, internal, restricted) propagated to every page it produces and recorded in the manifest. Consumers can filter at read time. Per-user enforcement is deferred.

Non-goals for v1: real-time sync or webhooks, per-user authorization at query time, editing origin content from OpenWiki.

Alternatives Considered

• Run openwiki repo against a monorepo or a meta-repo of submodules. Works only if the org already structures code that way. Gives no portal or knowledge-base ingestion, no canonical-entity resolution, and no cross-repo staleness.
• Extend openwiki repo to accept multiple targets. Simpler surface, but the config shape, output layout, and manifest differ enough that overloading repo would confuse both users and the codebase. A separate command is cleaner.
• Use openwiki personal as an org mirror. Puts the maintenance burden on each developer, drifts immediately, and cannot be shared or run in CI.
• Leave aggregation to the agent via MCP servers per source. Agents then do entity resolution and freshness checks ad hoc on every task, which is exactly the redundant-context and ambiguity problem this request is trying to remove. OpenWiki can still use MCP as the transport for knowledge-base origins.
• Adopt an external enterprise search or RAG platform. Solves retrieval but not grounding, provenance, or OKF compatibility, and does not produce a static artifact an agent can read without a running service.

Additional Context

• The org tree depends on OKF and the existing grounded-claims engine. It should be additive and leave repo and personal behavior unchanged.
• Rough effort ordering: config and git origin, then manifest and global cross-refs, then staleness tracking, then portal and knowledge-base providers.
• Open questions for maintainers:
  1. Separate org command versus a multi-target mode of repo? A separate command seems cleaner.
  2. When two origins both claim ownership of a concept, should sync fail, doctor warn, or config order decide?
  3. Should manifest.json be a versioned public contract that other tools can depend on?