> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazoo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage multiple wikis as a workspace

> Compose an umbrella wiki from independent sub-wiki repositories, and manage those repositories as one multi-repo workspace with wspace.

A single wiki suits one team or one domain. When teams move independently,
separate wikis keep their history and release cadence separate. The trade-off is
that isolated wikis stop answering queries as one corpus. This guide shows how
to compose an umbrella wiki from independent sub-wiki repositories, and how to
manage those repositories as one multi-repo workspace with `wspace`.

The umbrella wiki lists each sub-wiki under `sources:` in its `wiki.yml`, pins
exact commits in `wiki.lock`, and keeps each sub-wiki as a named RDF graph. You
can query the whole corpus at once, or trace a result back to its source
repository. `wspace` keeps the repositories in sync with `check`, `update`, and
worktree workflows.

## Prerequisites

* The `wiki` CLI, installed per the
  [Wiki install guide](/projects/wiki#install).
* The `wspace` CLI, installed per the
  [Workspace install guide](/projects/workspace#installation).
* A repository for each sub-wiki, and one repository for the umbrella wiki.

## Reasons to split

Split when you want independent ownership, versioning, or release surfaces:

* Each team owns its wiki history and merges its own changes.
* A reference library (product docs, regulations, shared domain models) can be
  reused across multiple umbrellas.
* Sub-wikis can publish or evolve on their own schedule.

Keep one wiki when the corpus is small or static, or when every page changes at
the same pace. Splitting adds a composition layer; a single wiki is still
simpler.

## Layout

The umbrella repository owns `wiki.yml` with a `sources:` block that points at
each sub-wiki repository. Each sub-wiki is its own Git repository. All
repositories, umbrella and sub-wikis, are listed in one `workspace.json`
manifest so `wspace` manages them as a workspace:

```text theme={null}
workspace-root/
  wiki.yml          # umbrella: inputs + sources
  workspace.json     # wspace manifest
  repos/
    umbra-wiki/     # umbrella repository
    product-docs/   # sub-wiki repository
    team-brain/     # sub-wiki repository
```

## Steps

<Steps>
  <Step title="Declare the repositories in the manifest">
    List the umbrella and each sub-wiki repository in `workspace.json`,
    following the [manifest schema](/projects/workspace#manifest-schema):

    ```json theme={null}
    {
      "$schema": "https://wazootech.github.io/workspace-cli/schema.json",
      "workspaceRoot": ".",
      "repositoriesDirectory": "repos",
      "repositories": [
        {
          "name": "umbra-wiki",
          "url": "https://github.com/acme/umbra-wiki.git"
        },
        {
          "name": "product-docs",
          "url": "https://github.com/acme/product-docs.git"
        },
        {
          "name": "team-brain",
          "url": "https://github.com/acme/team-brain.git"
        }
      ]
    }
    ```

    Clone the missing repositories and confirm the workspace is healthy:

    ```sh theme={null}
    wspace install
    wspace check
    ```

    `wspace check` confirms every repository is present and clean. Keep the
    default branch current with the remote so later updates fast-forward
    cleanly:

    ```sh theme={null}
    wspace update
    ```

    See [Workspace](/projects/workspace) for the full command reference.
  </Step>

  <Step title="Compose the sub-wikis in wiki.yml">
    In the umbrella repository, declare each sub-wiki as an external source.
    Use a git URL with a `#ref` pin (branch, tag, or commit) so the composition
    is reproducible:

    ```yaml theme={null}
    sources:
      - name: product-docs
        type: git
        url: https://github.com/acme/product-docs.git
        ref: v2.4.0
      - name: team-brain
        type: git
        url: https://github.com/acme/team-brain.git
        ref: main
    ```

    If a sub-wiki keeps its pages in a subdirectory, add `path: <dir>` to point
    at it. Each source name must be unique across the umbrella.

    Fetch the sources and pin the resolved commits:

    ```sh theme={null}
    wiki install
    ```

    This clones each repository into `.wiki/sources/<name>/repo/`, resolves the
    requested refs to commit SHAs, and writes `wiki.lock`:

    ```text theme={null}
    wiki.lock: {
      "product-docs": "9f2a1c4",
      "team-brain": "3be7d90"
    }
    ```

    Check `wiki.lock` into version control; it is the source of truth for
    which commit of each sub-wiki builds the corpus. If a source declares its
    own `sources:` block, `wiki install` fetches those transitive dependencies
    recursively; circular dependency chains raise an error.

    <Note>
      For the full contract, see
      [wiki install](https://wiki.wazoo.dev/wiki_install/)
      and
      [External data sources (`sources:`)](https://wiki.wazoo.dev/Wiki_Configuration/#external-data-sources-sources).
      For the product framing, see
      [Recursive Semantic Datasets](https://wiki.wazoo.dev/Recursive_Semantic_Datasets/).
    </Note>
  </Step>

  <Step title="Query the composed corpus with per-source provenance">
    Each sub-wiki stays a named RDF graph. List the graph boundaries:

    ```bash theme={null}
    wiki graph list
    ```

    This prints the root graph plus one graph per installed source, with the
    named graph URI, resolved commit, and dependency owner. Query the whole
    umbrella as one corpus:

    ```sparql theme={null}
    SELECT ?s ?name WHERE {
      ?s schema:name ?name .
    }
    ```

    Scope a query to one sub-wiki with a `GRAPH` clause:

    ```sparql theme={null}
    SELECT ?s ?name WHERE {
      GRAPH <https://example.org/wiki/graphs/source/product-docs> {
        ?s schema:name ?name .
      }
    }
    ```

    Return the source graph with each result to trace provenance:

    ```sparql theme={null}
    SELECT ?g ?s ?name WHERE {
      GRAPH ?g {
        ?s schema:name ?name .
      }
    }
    ```

    <Note>
      For the read-only boundary and graph URI derivation, see
      [wiki graph](https://wiki.wazoo.dev/wiki_graph/).
    </Note>
  </Step>

  <Step title="Keep repositories and content in sync">
    Refresh repository baselines, then refresh installed sources:

    ```sh theme={null}
    wspace update
    wiki update
    ```

    `wspace update` fast-forwards clean default branches and skips dirty or
    feature-branch checkouts. `wiki update` re-fetches the installed sources,
    installs newly declared transitive sources, and reports orphaned ones.
    Remove sources you no longer want from the corpus (and their now-unused
    transitive dependencies):

    ```sh theme={null}
    wiki remove team-brain
    ```
  </Step>

  <Step title="Publish the umbrella">
    Sub-wiki edits happen in the sub-wiki repository, not in the umbrella's
    `.wiki/sources/` cache. Make changes there with the normal worktree
    workflow, then publish the umbrella:

    ```sh theme={null}
    wiki build
    ```
  </Step>
</Steps>

## Advanced: multiple workspaces

The steps above declare every repository in one flat manifest. Schema v4 keeps
workspaces flat by design: each directory that contains a `workspace.json` is
its own workspace. There is no nesting or delegation between manifests.

### Nested workspaces were removed in schema v4

Earlier schema versions (v1-v3) supported nesting through a top-level
`workspaces:` array and entry-level `manifest` and `path` fields. Schema v4
removed them:

* A manifest that declares a top-level `workspaces:` key fails to load with a
  migration error: declare each child workspace's repositories directly in the
  parent manifest instead.
* Repository entries accept only `name`, `url`, and `owner`; the `manifest` and
  `path` entry fields are gone.
* Manifests are JSON or JSONC only. The `.yaml` and `.yml` formats were removed,
  along with the fallback filenames `wspace.json` and `repos.json`.

### Give a cluster its own workspace

To let a cluster of repositories change on its own cadence, give the cluster its
own manifest. Any directory that holds a `workspace.json` is a workspace root; a
checked-out repository can carry one at its root. Run `wspace` from that
directory, or pass `--manifest`, to manage the cluster as its own workspace:

```json theme={null}
{
  "$schema": "https://wazootech.github.io/workspace-cli/schema.json",
  "schemaVersion": 4,
  "owner": "acme",
  "repositoriesDirectory": "repos",
  "repositories": ["umbra-wiki", "product-docs", "team-brain"]
}
```

Relative paths always anchor to the directory containing the manifest, so the
umbrella repository's checkout becomes the root of its sub-workspace. The parent
workspace and the sub-workspace are independent: `wspace` commands run in the
parent see only the parent's `repositories[]`, and commands run inside the
umbrella checkout see only the sub-workspace's list. A repository claimed by a
sub-workspace must not also appear in the parent's `repositories[]`.

<Note>
  Workspaces organize Git repositories, while transitive `sources:` blocks
  compose RDF corpora. An umbrella can install another umbrella's published
  corpus within one workspace, and separate workspaces can each hold umbrella
  wikis whose graphs never merge.
</Note>

## Check for success

Run the integrity checks in the umbrella repository:

```sh theme={null}
wiki check --strict
wiki lint --strict
```

Then confirm each source resolves and its graph exists:

```sh theme={null}
wiki graph list
```

## Next steps

* [Wiki](/projects/wiki): validate, query, and publish semantic Markdown wikis
* [Workspace](/projects/workspace): manage multi-repository workspaces with
  `wspace`
* [External data sources (`sources:`)](https://wiki.wazoo.dev/Wiki_Configuration/#external-data-sources-sources):
  the composition reference
* [Recursive Semantic Datasets](https://wiki.wazoo.dev/Recursive_Semantic_Datasets/):
  the design behind named-graph provenance


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.