Federate archives via content mounts

@@ -1,113 +1,67 @@
---
schema: foundry-doc-v1
title: "How to federate archives via content mounts"
title: "Federate archives via content mounts"
slug: federate-archives-via-content-mounts
short_description: "Federates one knowledge instance's articles into another by declaring a mount in knowledge.toml, restarting the engine, and confirming they resolve without copying files."
short_description: "Federates a second knowledge instance's articles into a running instance through a knowledge.toml [[mount]] entry — a flat, merged namespace with no isolation, not a URL-prefixed federation scheme."
category: how-to
content_type: how-to
type: how-to
status: stable
last_edited: 2026-06-14
quality: complete
status: active
audience: "Engineers (hands on keyboard); customer operators"
last_edited: 2026-08-06
editor: pointsav-engineering
paired_with: federate-archives-via-content-mounts.es.md
research_trail:
  sources: [pointsav-monorepo app-mediakit-knowledge/src/config.rs (Mount struct), app.rs (router table, primary()/first() bug), content/walk.rs (index build, slug collision), content/render.rs (wikilink resolution)]
  verification_method: "independently source-verified against pointsav-monorepo on 2026-08-06 by reading the Rust source directly, with file:line citations recorded per claim; this guide replaces its own prior fictional URL-namespace schema with the real mechanism confirmed while rewriting use-knowledge-mounts.md in the same pass — content mounts are one flat merged namespace, not isolated federated sub-spaces"
---

Content mounts allow one knowledge instance to read article content from a second instance's local path without copying files. The reading instance renders the mounted content as if it were native, with wikilinks resolving within their source graph. This guide covers declaring a secondary mount in `knowledge.toml`, verifying the mount is live, and accessing articles from the federated source.
## Prerequisites

For the federation architecture, see [[federation-via-content-mounts]]. For the knowledge engine that processes mount declarations, see [[app-mediakit-knowledge]].

## Before you begin

You need:

- Two running `app-mediakit-knowledge` instances on the same host or on hosts
  with a shared filesystem (NFS or equivalent)
- Read access from the primary instance's process user to the secondary
  instance's content directory
- Two `media-knowledge-*` content repositories on the same filesystem (or a shared mount like NFS)
- Read access from the primary instance's process user to the secondary repository's content directory
- `knowledge.toml` write access on the primary instance

## Step 1: Confirm the secondary content path

On the host running the secondary instance, locate its content directory. The
path is the `content_root` value in the secondary instance's `knowledge.toml`:

```shell
grep content_root /path/to/secondary/knowledge.toml
# example output: content_root = "/srv/wiki/media-knowledge-projects"
```

Confirm the primary instance's process user can read the path:

```shell
sudo -u <wiki-process-user> ls /srv/wiki/media-knowledge-projects
```

If the path is on a remote host, mount it before proceeding. The engine reads
mount sources at startup; a path that is absent at that point causes the mount
to be skipped with a warning in the log.

## Step 2: Declare the mount in `knowledge.toml`
## Purpose

**Correction (2026-08-02, verified against canonical `origin/main`):** the mount schema below is fictional. The real `app-mediakit-knowledge/src/config.rs` schema uses `[[mount]]` entries with `path`/`role`/`blueprint_set` fields, where `role` distinguishes editable-primary vs. read-only-guide mounts — not a `source`/`prefix` URL-namespace mechanism as described. This exact schema mistake is already correctly flagged in this article's own sibling, `use-knowledge-mounts.md` (dated 2026-07-18 self-correction, independently re-confirmed this session). **Flagged, not resolved** — needs the same correction applied here.
Read a second instance's articles from a running instance without copying files — the mechanism `app-mediakit-knowledge` calls a content mount. This is narrower than a "federation" in the isolated, namespaced sense the term usually implies: mounted content joins the same flat slug space as everything else the instance already serves.

Open the primary instance's `knowledge.toml` and add a `[[mount]]` entry:
## Procedure

```toml
[[mount]]
source = "/srv/wiki/media-knowledge-projects"
prefix = "projects"
```
1. On the host running the secondary content, confirm the primary instance's process user can read it:

`source` is the absolute path to the secondary content directory. `prefix` is
an optional namespace string that prevents slug collisions when both instances
define articles with the same slug. With `prefix = "projects"`, an article
with slug `topic-co-location-methodology` in the secondary archive resolves as
`projects/topic-co-location-methodology` in the primary.
   ```
   sudo -u <wiki-process-user> ls /srv/wiki/media-knowledge-projects
   ```

Omit `prefix` only when you are certain no slug appears in both instances.
   If the path is on a remote host, mount it locally first. A path that's absent at startup causes the mount to be skipped, not to error.

## Step 3: Restart the wiki engine
2. Declare the mount in the primary instance's `knowledge.toml`. See [[use-knowledge-mounts]] for the full mechanical steps and the real `Mount` schema (`path`, `role`, `blueprint_set` — no URL-prefix field exists).

Apply the configuration by restarting the service:
3. Restart the primary instance. Both the config and the mounted content are read once, at startup — changes on either side require a restart to take effect.

```shell
sudo systemctl restart app-mediakit-knowledge
```
4. Access an article from the mounted repository at the same `/wiki/<slug>` path pattern the primary uses for its own articles — there is no separate namespace or prefix to navigate to.

The engine reads `knowledge.toml` once at startup. A `[[mount]]` entry added
after initial start has no effect until the service restarts.
## Expected outcome

## Step 4: Verify the mount is live
The primary instance serves both its own articles and the mounted repository's articles, indistinguishably, from one merged content index.

Check the startup log for the mount confirmation line:
## Verification

```shell
journalctl -u app-mediakit-knowledge --since "1 minute ago" | grep -i mount
# expected: Mounted secondary archive at prefix=projects (N articles)
```
Confirm an article you know exists only in the mounted repository resolves correctly, and — critically — confirm neither repository has an article with a slug the other one also uses. See [[use-knowledge-mounts]]'s verification steps for exactly how to check.

If the output shows `0 articles`, confirm that the `source` path is readable
and contains `.md` files at the expected depth. If the path is absent, the
log line reads `Mount source not found — skipping` rather than a startup error.
> **Warning:** wikilinks inside mounted articles resolve into the same merged namespace as everything else, with no existence check — a `[[some-slug]]` link works if that slug exists anywhere across every mount, and produces a dead link if it doesn't, regardless of which repository originally contained it. Don't assume a mounted article's internal links stay scoped to its own source repository.

## Step 5: Access mounted articles
## Rollback

Navigate the primary instance to confirm articles from the secondary archive
are available. With `prefix = "projects"` and a secondary article at slug
`topic-co-location-methodology`, the URL is:
Remove the `[[mount]]` entry and restart. See [[use-knowledge-mounts]] for what to check if a slug collision already shadowed an article before you noticed.

```
https://<primary-domain>/how-to/projects/topic-co-location-methodology
```
## Next steps

Wikilinks within mounted articles resolve against the secondary archive's own
link graph. A `[[topic-regional-markets-system]]` link inside a mounted
article resolves within the secondary graph, not the primary — cross-graph
links render as red links.
- [[use-knowledge-mounts]] — the full step-by-step mechanics and the real schema
- [[deploy-knowledge-instance]] — provision the instance that will serve federated content

## See also

- [[federation-via-content-mounts]] — the declarative federation architecture and mount model
- [[app-mediakit-knowledge]] — the wiki engine that processes `knowledge.toml` mount declarations
- [[build-a-colocation-map]] — consume location-intelligence data exposed via a mount
- [[self-host-a-deployment]] — provision the instance that will serve federated content
- [[app-mediakit-knowledge]] — the wiki engine that processes mount declarations