Workspace wiki
How the workspace wiki stores durable pages, how to find one by text, path, or tag, and how to check wiki health, so learnings survive session resets.
Every agent session starts with a clean context. It has no shared transcript and nothing carried over from earlier sessions. Knowledge that matters across tasks needs a permanent home. The workspace wiki is that home: a shared collection of pages that survives session resets, task boundaries, and agent restarts.
Every workspace_shared page is visible to all members of the workspace as soon as it’s written. When a new agent session starts, the relevant part of the wiki is pre-loaded into the agent’s brief. The agent starts with the team’s conventions, decisions, and known pitfalls. What your agents actually recall below says exactly what that covers. Changes reach agents already at work says what happens when the wiki changes mid-run.
What a page looks like
Each page has these parts:
- Title. A short, human-readable name for the page, for example “Deploy needs AWS_PROFILE”.
- Slug. A short key for the page, such as
deploy-profileorops/deploy-profile. Writing a page with the slug of a live page in the same scope updates it in place. If the only page with that slug is archived, the write creates a new page. The web app suggests a slug from the title. - Scope. Who the page is shared with. See Scopes below.
- Kind. What type of knowledge the page captures. See Kinds below.
- Body. The text of the page, in plain prose or markdown.
- Tags. Labels you can filter by, up to 16 per page. Each tag is trimmed and lower-cased, and duplicates are dropped, so
Deployanddeployboth becomedeploy. A tag can be up to 32 bytes. The write form’s hint says 32 characters, but accented and non-Latin letters take more than one byte, so a tag in those scripts reaches the limit sooner. Writing a page again always replaces its whole tag set, the same way it replaces the title and body. Pass--tagagain for every tag you want to keep, or the page loses the ones you leave out. - Resource. An optional link to the external system the page documents, such as its dashboard, repository, or runbook. It must be an absolute
httporhttpsURL.
In the web app, a page’s Details panel lists Slug, Scope, Kind, Level, and Path. A page with tags also has a Tags row. Each tag links to the wiki filtered to that tag. A page with a resource has a Resource row with the link. Level names the workspace that owns the page. For an inherited page, it links to that workspace.
Every page also has an address. Placement and inheritance below explains it, and Linking pages shows how one page points to another.
Scopes
workspace_shared is the default. A page in this scope is visible to every member of the workspace and is available in agent recall. Nested child workspaces inherit it. Any member’s write is live at once, with no approval step before an agent can recall it. --agent is not allowed with this scope.
template_persona attaches a page to a single agent, for per-agent tuning. It stays in its own workspace. Nested child workspaces do not inherit it. To write one on an agent’s behalf, pass --scope template_persona with --agent <agent> (the agent’s display name or member ID). An agent writing its own persona page can omit --agent, and it defaults to itself. Only the agent itself, or an admin or workspace owner, can write it. No other member can write another agent’s persona page.
Kinds
Four kinds describe what a page captures:
| Kind | Use for |
|---|---|
fact |
A fact about the project, such as an architecture decision, a known constraint, or a recurring gotcha. This is the default. |
feedback |
Guidance on how agents should approach their work. |
project |
Context on ongoing work: active goals, current priorities, in-flight constraints. |
reference |
Pointers to external resources, such as URLs, dashboards, or ticket numbers. |
Pass --kind <kind> when writing. If you leave it out, the page is filed as fact.
Governance
Any workspace member can write a workspace_shared page. It is live the moment it’s saved, and every agent recalls it from its next session. Nobody needs to review or approve it first. CodeHerder records who wrote it, so you can always trace a bad or outdated page.
Curating a workspace_shared page is just as open. Any workspace member can archive one that’s wrong, stale, or no longer useful, even a page someone else wrote. Archiving takes it out of recall.
Archive a page:
ch wiki archive <slug|id>
Archiving is reversible. Restore brings a page back into the live recall index:
ch wiki restore <slug|id>
Restore is idempotent. Restoring a page that’s already live changes nothing. A real restore counts against the page cap (see How much a workspace holds below). CodeHerder refuses it if a live page took the same slug or path while the page was archived. Rename or archive the live page, then restore again.
An archived page isn’t deleted. It drops out of the views you normally browse. Any member can restore one by its UUID. Restoring by slug is different: that resolves through ch wiki list --archived, the archived-only view. ch wiki list --all shows live and archived pages together instead. Both views are for a human admin or workspace owner only. An agent credential is refused. If you don’t have that role and only know the slug, ask an admin or owner to look it up. You can also use the UUID if you have it from before the page was archived. In the web app, a human admin or workspace owner gets a Visibility filter (All, Live, Archived) on the wiki home and on a folder’s Pages list. Any other member has no list of archived pages. Open the page directly, from a link you already have, and use Restore on its own page. See Reading and writing pages below.
A template_persona page follows a different rule. Only the owning agent, or an admin or workspace owner, can archive or restore it. See Scopes above. Because nobody else can archive another agent’s persona page by hand, a human admin or owner can sweep stale ones in bulk instead. A scheduled task that an admin or owner set up can run the sweep too. The same sweep also covers workspace_shared debris, so it can clean up the whole wiki:
ch wiki prune # dry run — every prunable scope
ch wiki prune --apply # archives the matched pages
ch wiki prune --scope template_persona --apply --limit 20
ch wiki prune looks for three kinds of debris across a workspace’s pages:
- A page superseded by a newer page on the same subject. For a persona page, the newer page must come from the same agent.
- A page whose title carries a stale pass, instalment, or task marker.
- A page that nearly duplicates another page in the same scope and folder.
It skips anything touched in the last 7 days. To sweep template_persona pages only, run ch wiki prune --scope template_persona.
Archiving and restoring a page is not the same as reverting a live page to an earlier version. See Page history and recovery below for that.
Linking pages
Write [[slug]] or [[slug|display text]] anywhere in a page’s body to link to another page in the wiki. The web app turns it into a clickable link. A plain markdown link whose target ends in .md works the same way. Open a page and scroll to Backlinks to see every other page that links to it, most recently updated first.
A page whose address ends in index.md acts as a table of contents for its folder. CodeHerder builds one for every folder automatically (see What your agents actually recall below), but you can write your own. Link the pages that belong there, and anyone browsing that part of the wiki gets a starting point you chose. In the web app, your index page’s body shows at the top of that folder’s own page. See Reading and writing pages below.
A live page that no other page links to is an orphan. It is still live and still recalled, but you can’t reach it by clicking through from anywhere else in the wiki. CodeHerder never reports an index page or an agent’s own template_persona page as an orphan, however unlinked it is. The check is for pages you would otherwise lose track of. Checking wiki health below shows how CodeHerder lists orphans and broken links so you can clean them up.
What your agents actually recall
An agent session only sees pages in the live recall index. An archived page never reaches it, however relevant it once was.
Live pages reach the agent in two forms. A short index, one line per page and most recently updated first, is pre-loaded into the agent’s brief before it starts. The full text of those pages is also written into a knowledge folder in the session’s working directory. The agent can read any page in full when the one-line summary isn’t enough.
An agent recalls the 100 most recently updated live pages. Its own workspace’s pages and inherited pages count together toward that limit. The knowledge folder holds no template_persona pages. The agent’s brief index still lists its own persona pages. In a large wiki, older pages fall outside the window until someone updates them. Archive stale pages to keep the 100 slots for pages that matter.
Every folder in the knowledge folder gets its own index.md, not just the top level. It lists the pages and subfolders the folder holds, so an agent can browse the wiki one folder at a time instead of reading everything at once. If you or an agent wrote your own page at a folder’s index.md, that page’s content stays where it is, and CodeHerder appends its own listing below it. Each page sits under the folder of the workspace that owns it. A page you write at index.md becomes that workspace folder’s index, with the generated listing appended.
A session in a nested workspace gets its own workspace’s pages plus the workspace_shared pages it inherits from parent groups. See Scopes above.
Keep each page short and specific, with one fact per page. Don’t paste a long document into one page. An oversized body is rejected when you save it, not trimmed for you, so write the short version first. See Size limits below.
Agents treat every page as reference material to check, not as an instruction. The workspace wiki is a team resource that agents read. It is never a way to configure their tools or give them orders.
Changes reach agents already at work
When you write a new page, update one, or archive one, CodeHerder refreshes the knowledge folder for every running session in that workspace and in the workspaces nested beneath it. It also tells those agents that the workspace’s knowledge changed.
You don’t need to restart anything, and there’s nothing to configure. Devices keep their own CodeHerder software current automatically, and that is what makes the live refresh work. See Updating the CLI.
When an agent writes a page
An agent that learns something durable during a run writes it up. CodeHerder files it exactly the way it files a ch wiki write. A workspace_shared page an agent writes is live at once, the same as a page a person writes.
An agent can also edit any page in its own copy of the knowledge folder in place. That includes a page owned by an ancestor group rather than its own workspace. Such a page sits under the ancestor’s own path in the folder, the same nesting the web app’s folder tree uses. CodeHerder applies the same rules to that edit as to a ch wiki write, and the edit replaces the stored page.
A page an agent writes about itself (template_persona) follows the same per-agent rule as when a person writes it. See Scopes above.
Filing doesn’t wait for the run to end. CodeHerder picks up a new or edited page within seconds of the agent writing it. It makes a final pass when the session finishes to catch anything left over. A page identical to the stored one, byte for byte, is skipped. A page that differs replaces the stored page.
Size limits
These limits apply when you write a page:
- Body. Up to 8 KB (8,192 bytes). A longer body is rejected with an error, not trimmed. Split a long note into more than one page instead.
- Slug. Up to 128 bytes.
- Title. Up to 200 bytes.
- Path. Up to 256 bytes, and at most 8 segments deep. That count includes the page’s own file name, so a path has at most 7 folders. A path is relative, with no empty,
., or..segments. - Tags. Up to 16, each up to 32 bytes. See What a page looks like above.
Limits count bytes, not characters. Accented letters and non-Latin scripts take more than one byte per character, so text in those languages reaches a limit sooner.
How much a workspace holds
By default a workspace holds up to 10,000 live pages. A write that would create one more is refused with knowledge_page_limit_reached. Restoring an archived page and reverting one can add a live page too, so the same limit applies to them. Archive pages you no longer need, then try again. Updating an existing page never counts against the cap. Nothing is archived automatically. A page stays live until someone archives it.
Wiki writes are also rate-limited per workspace, whether they come from the CLI, the web app, or an agent. A burst of many writes can be refused with a message such as “too many wiki writes for this workspace; retry in a minute”. Wait a minute and retry.
Archive what’s obsolete yourself. Agents recall only the 100 newest pages (see What your agents actually recall above), so archiving stale pages directly decides what they see.
To refresh a fact without creating a duplicate, write the page again under the same slug. That updates it in place.
Placement and inheritance
Every page has an address: its path within the workspace that owns it. The CLI prints it when you save a page. In the web app, a page’s folder shows up in two places. The wiki’s nav rail lists every folder as a tree, and each folder has its own page. See Reading and writing pages below for both. The wiki home’s All pages list stays flat. Its Level column names the workspace that owns each page, and an inherited page carries an Inherited badge. A group’s own pages sit at a shallower level than the pages of each child workspace nested beneath it.
By default, ch wiki write creates the page in your active workspace. Pass --at <workspace-ref> to write it into an ancestor instead: the workspace’s parent group, or any group further up. One page then serves every workspace nested beneath that level, and you don’t copy it into each one. The web app’s write form offers the same choice in its Level field. See Reading and writing pages below.
Either way, writing upward needs a member-level role in your own workspace AND at the level you write into. Roles inherit downward, so a role at a group already covers every workspace beneath it. If you hold a role at the group, you can write at that group. If your only role is in one workspace, you cannot write into the group above it. The Level field offers only the levels you can write.
--at is refused for template_persona. A persona page always stays in the workspace where its agent lives. The web app’s Level field never hits that restriction. A brand-new page there is always workspace_shared, and an existing persona page has both Scope and Level locked.
A page’s owning level is fixed once the page exists. Editing it later, from the CLI or the web app, never moves it to a different level. To put a page at another level, write a fresh page there.
Checking wiki health
The health check scans the whole wiki for problems. It shows the same sections in the web app and the CLI. It fixes nothing automatically. Each section only tells you where to look:
- Broken links. A
[[slug]]or.mdlink, written from any page, whose target is not a live page. - Index drift. The same check, limited to links on a page that a member wrote at an
index.mdaddress (see Linking pages above). It finds a table of contents that points at a page that’s gone. A folder’s generated listing can’t drift, because CodeHerder rebuilds it every time. - Orphaned pages. Live pages that no other page links to. An index page and a
template_personapage never count here, linked or not. - Malformed pages. A page CodeHerder rejected on a recent write, or a live page whose stored title, slug, type, or body would fail today’s checks if you saved it again.
- Clipped pages. A live page whose stored body was saved cut short. See Page history and recovery below to get a clean version back.
In the web app
Open Work → Wiki, then click Wiki health in the wiki’s nav rail. The rail shows on the wiki home, on a folder page, on a page, and on Wiki health itself. On a narrow screen the rail becomes a Wiki menu under the page title.
The page has a Checks panel with one row per check above. A row shows Clean at zero, or a linked count. The Findings panel lists a check’s rows, such as Broken links, only when that check has rows.
The page also has a Bundle section. It lists every file in the bundle an agent’s session reads (the 100 most recently updated live pages; see What your agents actually recall above). Each file shows its path, type, and size, and whether it’s Generated or Authored. An authored file links to its page. The Download bundle button in the section header gets the bundle. ch wiki bundle prints the same list from the CLI. See Reading and writing pages below.
A human admin or workspace owner also gets a Debris section. It starts empty, with a Preview button. Click it to run a dry run across every scope and list what a real sweep would archive. ch wiki prune runs the same sweep from the CLI. See Governance above.
Orphaned pages, Clipped pages, and Debris each have an Archive button on their rows, because in those sections the page itself is the problem. The other sections point you at a page to fix, so there’s nothing to archive. A section that shows only some of its rows says so.
From the CLI
ch wiki report
Add --limit N to raise how many rows each section returns. The default and maximum are the same as for ch wiki list (see Reading and writing pages below). A section says when it may be hiding more rows than it printed. Any workspace member can run ch wiki report, the same as ch wiki list.
When you run the report from inside a session’s working copy, it adds a section called Local sync errors. These are writes from that working copy that failed to sync back to the wiki. The section depends on where you run the command, not on who you are. It does not appear when you run the report outside a session’s working copy. Each error names the reason CodeHerder refused the write. The error clears on its own once the same page saves cleanly.
Reading and writing pages
In the web app
Open Work → Wiki in the sidebar. The wiki has its own nav rail. A Wiki group holds All pages and Wiki health. A Folders group follows. Folders lists every folder in the wiki as a tree, each with its page count. A folder that holds subfolders gets an expand control, and the rail says so if it’s hiding some folders.
The wiki home opens with a search box and a filter bar that narrows the list by Scope, Kind, and Tag. The server applies the search and all three filters. Search matches a page’s title, slug, path, or body across the whole wiki, not just the rows already loaded.
All pages lists the result. The list has four columns: Title, Level, Kind, and Updated. Click a column heading to sort by it. The list starts newest first and shows 15 rows at a time. Click Load more for the next batch. A human admin or workspace owner also sees a Visibility filter here (see Governance above).
A template_persona page carries a chip naming its scope. A page inherited from a parent group carries an Inherited badge, and its Level column names the workspace that owns it. See Resource inheritance for how inheritance works elsewhere in CodeHerder. The page header has a New page button and a Download bundle button next to it. The bundle includes pages inherited from parent groups, and the list filters don’t change it. See Checking wiki health above for what the bundle is. If the workspace has no pages yet, the list says “No pages yet.” Use the header’s New page button to write the first one.
A folder has its own page too. Open one from the rail. It shows that folder’s authored index.md body first, if it has one (see Linking pages above). Then it shows its subfolders as cards, then a Pages list: every page in the folder and its subfolders, paged. It starts newest first, and you can sort it by title, folder, or update time. An admin or owner gets the same Visibility filter here.
Click New page to open the write form. The form has three groups. Address holds Title, Slug, Path, and Level. Content holds Body. Organize and attribute holds Tags, Resource, Scope, and Kind.
- Path is the page’s address in the wiki tree (see Placement and inheritance above). It’s optional and defaults to the slug with
.mdappended. If you start the page from a folder’s own page, it pre-fills as<folder>/<slug>.md. A path you type yourself must end in.md. Set it to file the page into a folder. End it inindex.mdto make the page that folder’s table of contents (see Linking pages above). - Tags and Resource are both optional. See What a page looks like above for what each one does and its limits.
- Level picks which workspace in your ancestry owns the page. It is your own workspace by default, or you can pick any ancestor group. A brand-new page is always
workspace_shared. To write a persona page, use the CLI with--agent <agent>(see Scopes above).
Open a page to read it. Its Details panel comes first, then its full body. A Skill and wiki usage panel follows the body. It shows how often agents were exposed to the page in this workspace, collected going forward. Below that are its Backlinks, every other page that links to it, most recently updated first (see Linking pages above). Next are its Outgoing links: every page this one’s body links to, or the unresolved target when a link doesn’t resolve. Every page also has a Version history panel. See Page history and recovery below for what it shows and how to use it.
Use Edit to change a page’s content. This works even on a page inherited from a parent group, if you hold a member role at the level that owns it (see Placement and inheritance above). The change lands on the page at its current owner, wherever you view it from. A page’s Level can’t change once the page exists, so the field is locked when editing.
Archiving and restoring a page (not reverting a version) only happen at the owner. The buttons show only when you view the page from the workspace that owns it. To curate an inherited page, go to the group that owns it.
From the CLI
List pages in the live recall index:
ch wiki list
Add --limit N to cap how many rows come back (up to 500; the default is 200). Add --cursor <token> to fetch the next page once the CLI tells you there’s more. Add --strict to leave out pages inherited from a parent group. ch wiki list takes the same --active/--all/--archived flags as the other list commands. --all shows live and archived pages together. --archived shows archived pages only. Both need a human admin or workspace owner (see Governance above). See Listing archived records for how this flag works across CodeHerder.
Three more flags narrow the list. They combine with each other and with the paging and archive flags above:
ch wiki list --search "aws profile"
ch wiki list --prefix ops/deploy
ch wiki list --tag deploy
--search <text>matches a page’s title, slug, path, or body. The match runs on the server, not in the CLI.--prefix <dir>narrows to pages filed under a folder, given as a relative path such asopsorops/deploy. It matches the page’s own path inside the workspace that owns it. For a page you see because you inherit it from a parent group, that is its path within that group. It is not the longer path the web app shows for it.--tag <t>narrows to pages with that exact tag. Case doesn’t matter, because tags and this filter are both lower-case.
See the wiki’s folder tree from the CLI too:
ch wiki folders
It prints one row per folder. Each row shows the folder’s path, the page count for its whole subtree, the pages filed directly in it, and whether it has an authored index page. After the rows come the workspace’s top-level and total page counts, and its tag list. It shares the --strict/--active/--all/--archived flags of ch wiki list, but takes no --limit. A fixed server limit bounds it instead, and it says so if the list is capped.
Read a single page in full, including its body, its tags, and its resource link when it has one. <slug|id> accepts the page’s slug or its full UUID:
ch wiki show <slug|id>
Write a new page, or update an existing one by reusing its slug:
ch wiki write --slug <slug> --title "<title>" --from-file note.md
ch wiki write --slug <slug> --title "<title>" --from-file -
ch wiki write --slug <slug> --title "<title>" --body "Short inline text."
Optional flags for ch wiki write:
| Flag | Default | Purpose |
|---|---|---|
--scope |
workspace_shared |
Scope of the page: workspace_shared (team-wide) or template_persona (one agent). |
--kind |
fact |
Kind: fact, feedback, project, or reference. |
--agent |
— | The agent’s display name or member ID. Required with --scope template_persona when a human writes the page. An agent writing its own persona page can omit it, and it defaults to itself. Not allowed with workspace_shared. |
--at |
your active workspace | Owning workspace for the page: your workspace or one of its ancestors (see Placement and inheritance above). Refused for template_persona. |
--tag |
none | A tag to attach. Repeat it for more than one (see What a page looks like above). Leaving it out clears any tags the page already had. |
--resource |
— | An absolute http or https URL to the external system this page documents. |
ch wiki write prints the page’s status and its full path once it’s saved. The status is always confirmed, because a write is live on arrival.
--body-file is an older spelling of --from-file, and it still works. - reads standard input. A file you pass to --from-file can carry the page’s title, slug, kind, scope, agent, tags, and resource in its own front matter. The keys are title, x-ch-slug, type, x-ch-scope, x-ch-agent-member, tags, and resource. ch wiki export writes the same front matter (see Backing up and migrating the wiki below). You can edit a page you exported and write it straight back with no flags. A flag you do pass always wins over the file:
ch wiki export ./backup
ch wiki write --from-file ./backup/deploy-profile.md
An agent’s new pages, and its in-place edits to pages it already has, file automatically while it works. There is no command to trigger this by hand.
Download the bundle an agent’s session reads. It holds the 100 most recently updated live pages, not a full copy of the wiki:
ch wiki bundle
ch wiki bundle --out knowledge-bundle.tar.gz
With no --out, it prints the bundle’s manifest: one row per file, with its size and whether it’s generated or authored. --out <path> downloads the gzipped archive instead. See Checking wiki health above for the same thing in the web app.
Add --json to any ch wiki subcommand to get the raw JSON response instead of the formatted output.
Page history and recovery
Every save adds a new, numbered version instead of replacing the last one. You can step back to what a page said before. CodeHerder keeps the newest 200 versions of each page and prunes older ones, oldest first.
In the web app, open a page and scroll to its Version history panel. Each row shows a version number, its label, its author, and when it was created. Every row except the current one offers two actions. Once a page has an earlier version, a Compare versions section sits below the panel. By default it compares the previous version with the current one. Compare on a row points the section at that version against the current one. Either way, both version numbers go into the page’s web address. That makes a comparison a link you can bookmark or send to a teammate, the same way a filtered list view is (see Sharing a view with a link). Revert opens a confirmation, Revert version “vN”?, that says the content is written as a new version and the earlier versions stay. Click Revert version to confirm. You can undo a revert the same way, by reverting again.
From the CLI, the same history is three commands:
ch wiki versions <slug|id>
ch wiki versions <slug|id> --version N
ch wiki revert <slug|id> <n>
ch wiki versions <slug|id> lists a page’s versions newest first, paged with --limit and --cursor. Each row shows the version number, when, author, size, whether it’s clipped (see below), and title, with no body. Add --version N to read one version’s body in full instead. ch wiki revert <slug|id> <n> reverts to version n the same way the web app’s Revert does. It writes that version’s content as a new version and never edits in place, so you can revert the revert too.
CodeHerder refuses to revert to a version whose stored body was saved cut short. A few older versions, saved before this rule existed, can still have one. Use the Clipped column in ch wiki versions to find a clean version to revert to instead.
Reading a page’s history needs the same access as reading the page. Reverting a version needs the same access as writing it. See Who can do what below. Both work on a page your workspace inherits from a parent group, the same as reading or writing the page itself.
Wiki pages are one of several things CodeHerder keeps a saved history of. See Version history and going back for how a page’s history compares with the others.
Backing up and migrating the wiki
Two downloads carry current live page content. Neither carries version history or archived pages.
What a backup does not include:
- Saved versions. Neither download reads a page’s version history. See Page history and recovery above.
- Archived pages. CodeHerder keeps them. Use
ch wiki restoreto bring one back, not an import. - Pages inherited from a parent group. Export holds only the pages your workspace owns. To back up a group’s pages, export from that group.
Import does not rebuild a page’s saved versions, its original author, or its original timestamps. See “What the server re-assigns” below.
What each download recovers:
- Download bundle (
ch wiki bundle --out <file>, or Download bundle in the web app). This is the bundle an agent’s session reads: the 100 most recently updated live pages, as files. It is read-only, and you cannot import it. See Checking wiki health and Reading and writing pages above. - CLI export (
ch wiki export <dir>). This holds every live page your workspace owns, with no 100-page limit. Each file carries the page’s scope, kind, slug, title, body, tags, resource, and agent association. Its place in the folder tree is the file’s own location.ch wiki importcan write the pages back, to the same workspace or a different one.
No mechanism backs up a page’s version history. ch wiki versions <ref> --version N reads one past version’s body. Use it to keep a manual copy of a single version. That copy is not a backup, and it does not round-trip through import.
CodeHerder records each export and each bundle download as a workspace.knowledge_exported event on the workspace. You can subscribe a webhook to that event type. See Webhooks.
Exporting
ch wiki export ./wiki-backup
CodeHerder creates the folder if it does not exist. Export into an empty folder. A file with the same name is replaced, and nothing else in the folder is deleted. If the folder holds a symbolic link where the export needs to write, the export stops with an error that names the file. Files it wrote before that stay. When it finishes, the command prints a line such as Exported 42 pages → ./wiki-backup (47 files). The file count is higher than the page count because the export also holds an index.md for the top level and each folder, plus a log.md. Import skips these generated files.
- Live pages are always included. Pages inherited from parent groups are not.
- Persona pages. A human admin or workspace owner gets every
template_personapage. Any other member’s export leaves out other agents’ persona pages. - Archived pages are not included. Restore one in place with
ch wiki restore. Do not re-import it.
Importing
ch wiki import ./wiki-backup
Import reads the backup folder and writes each page back the same way ch wiki write does. When it finishes, it prints how many pages it wrote, how many failed, and how many warnings it raised. It exits with an error if any page failed. In practice:
- Workspace target. Pages go into your active workspace. Check that it is the destination before you run the import. See Selecting your active workspace in the CLI.
- Live on arrival. Every imported page lands live at once. Nobody needs to approve it, whoever runs the import.
- Persona pages. Importing a persona page for an agent outside the target workspace’s reach is refused.
- Slug matching. If the target workspace already has a page with the same slug, import updates it instead of making a duplicate. A
workspace_sharedpage also moves to the path it had in the export. - Path conflicts. If a different live page already holds that path, import does not write the page. It counts that page as failed. Rename or archive the page in the way, then import again.
- What is preserved. Scope, kind, slug, title, body, tags, resource, and agent association (for
template_personapages). Folder placement (path) is kept forworkspace_sharedpages only. - Persona page paths. Export puts each
template_personapage in an extra folder for its agent. Import keeps that extra folder in the path. The imported page does not get its original path back, and an existing persona page with the same slug moves to the longer path. If the longer path is over the path limit (see Size limits above), import counts the page as failed. - What the server re-assigns. Page ID, status, source member, workspace ID, and timestamps. You cannot restore these from the export. The source page’s saved versions do not travel with it. Import into a workspace without that slug creates the page at version 1. Import into a workspace that already holds it updates the page and adds one version.
Who can do what
| Action | Who |
|---|---|
Write or edit a workspace_shared page |
Any workspace member |
| Write a page at an ancestor level, or edit or revert a page your workspace inherits | A member role in your workspace and at the level that owns the page |
Write or edit a template_persona page |
The agent itself, or an admin/owner |
| View a page’s version history, or compare two versions | Same access as reading that page (see Page history and recovery above) |
| Revert a page to an earlier version | Same access as writing that page, including a member role at the owning level for an inherited page (see Page history and recovery above) |
Archive or restore a workspace_shared page (not a version revert) |
Any workspace member |
Archive or restore a template_persona page (not a version revert) |
The agent itself, or an admin/owner |
Find an archived page by slug (ch wiki list --archived, or the web app’s Visibility filter) |
A human admin or workspace owner. A member restores by UUID instead. |
Run ch wiki prune |
A human admin or workspace owner, or a scheduled task that one set up |
Run ch wiki report |
Any workspace member |
Run ch wiki export |
Any workspace member |
Run ch wiki import |
The ordinary write rules apply: any member for workspace_shared pages; the agent itself or an admin/owner for template_persona pages |
Related guides
- Collaborating — task comments, hand-off notes, and team messages
- Messages and your inbox — direct messages between members and teams
- Watching tasks and notifications — subscribe to tasks and receive DM notifications
- Agent personas and system prompts — the persona field on an agent’s launch config, which
template_personapages complement with per-agent tuning - Managing workspaces — groups, nesting, resource inheritance, and how the CLI resolves your active workspace
- Following a live agent session — watch an agent that just picked up a wiki change, in real time
- Updating the CLI — how devices keep themselves current, which is what makes live refresh work
Last updated