Wiki

The catalog describes your software. The wiki is where you write down how your organization uses the catalog: “how we choose a tier”, “what a service’s description should cover”, “which collection is the PCI scope”, “when to add a new kind”. It is guidance for the people and AI agents who maintain the catalog.

The wiki doesn’t replace entity documentation. What a particular system or service does, and how to run it, belongs in that entity’s documentation. The wiki holds the conventions that apply across entities.

Each organization has one wiki of Markdown pages, and the pages can reference catalog entities, teams, schema definitions, collections, scorecards, and other pages. Every one of those references works in both directions: the page links to what it names, and what it names lists the pages that reference it.

Every organization member can read and edit the wiki. You can write the pages in Componecat, or keep them in a Git repository and let Componecat import them.

Find your way around

Open Wiki in the main navigation.

• The home page is the page whose address is home. It is the first thing readers see, so use it to welcome them and point at the most useful guides. Until it exists, the wiki offers to create it.
• All pages lists every page with its title, path, tags, and who last updated it. Tags show as the same chips a page’s side rail uses, with the name of what they point at; select a tag chip to list every page carrying it. Type in the filter box to narrow the list by title, path, or tag, and turn on Group by folder to group pages under the folders in their paths.
• Page addresses are paths. A page’s address (its slug) is made of lowercase letters, digits, and hyphens, in /-separated segments, such as conventions/service-tiers. The segments before the last one act as folders: the breadcrumb at the top of a page links each folder to the matching pages in All pages. home is reserved for the home page and can’t contain other pages.

Each page shows its content beside a side rail with the page’s Tags and Referenced by, which lists the other pages that link to this one or are tagged with it. A link to a page that doesn’t exist yet starts counting as soon as the page is created, renamed to that address, or restored from Trash.

Write a page

Choose New page, give the page a title, and write Markdown in the Write tab; Preview shows it as readers will see it. The slug follows the title until you change it yourself. A page title is at most 250 characters, and its content at most 500 KB.

To change a page, choose Edit on it. Delete moves the page to Trash, where it can be restored. Moving a page to a new slug is an edit of its slug; links to the old slug stop resolving, so update the pages that use them.

If someone else saves the page while you are editing it, the editor tells you that the page changed while you were editing. Your changes are kept, and you choose: Keep my changes keeps your version so that your next save replaces theirs, and Load latest version shows their version and discards yours, after asking you to confirm. A save never silently overwrites a newer version. If you haven’t changed anything yet, the editor simply switches to the latest version. If someone renamed the page meanwhile, the editor says so and shows its new slug; the same choices apply, and Keep my changes saves onto the page at its new slug (unless you changed the slug yourself). The editor’s address moves to the new slug too, so reloading it reopens the same page. If someone deletes the page while you are editing it, the editor keeps your changes on screen so you can copy them, but can’t save them. If the latest version can’t be loaded (for example, the network drops), your changes also stay on screen, with Try again to load it once more.

Componecat keeps no revision history of wiki pages. Every create, edit, and delete is recorded in the audit log, with who made it.

Reference the catalog

A reference is a sigil followed by a target. Write one anywhere in a page and it renders as a chip that links to its target; hover over or focus the chip for a summary card. From the keyboard, press Tab while the card is open to move into it (for example, to its Pages referencing link), Shift+Tab to return to the chip, and Escape to close it.

Write	To reference	Examples
# + entity reference	A catalog entity, by its kind://namespace/name or kind://name address	#service://payments/api, #system://checkout
@ + name	A team, by its name, or by a name with spaces in braces	@platform, @{Platform Team}
$kind: / $rel: / $field: + key	An entity kind, relationship kind, or field definition, by its key	$kind:service, $rel:depends-on, $field:tier, $field:onCallRotation
! + name	A collection, by its name, or by its display name in braces	!tier-1, !{Tier 1 Services}
& + name	A scorecard, by its name, or by its display name in braces	&production-readiness, &{Production Readiness}
[[ slug ]]	Another wiki page	[[conventions/service-tiers]], [[home]]
[[ entity reference ]]	A catalog entity, as a cross-link	[[component://payments/gateway]]

For example, a sentence such as Ask @platform. references the team platform; the full stop is not part of the reference.

How names are matched

• Teams. @platform matches a team named platform regardless of case. If no team has that name, it also matches a team whose name, lower-cased with spaces and punctuation turned into hyphens, equals the token. Or write the name exactly as it is, spaces included, in braces: @{Platform Team}.
• Collections. !tier-1 matches a collection’s name, regardless of case. The brace form !{Tier 1 Services} matches its display name first, then its name.
• Scorecards follow the collection rules: &production-readiness matches a scorecard’s name, and &{Production Readiness} its display name first, then its name.
• Schema, entities, and pages match exactly: a key for $kind:, $rel:, and $field:, the entity’s address for # and for double brackets, and the page slug for a page link.

A name that matches more than one target, or nothing at all, is unresolved.

What is not a reference

The syntax is designed to stay out of the way of ordinary Markdown and prose:

• A sigil must start a line or follow a space. [email protected] is an email address, and (@platform) is plain text.
• # needs ://. # Heading is a heading, and Fixes #123 #hashtag has no references.
• $ needs a schema prefix. costs $5 or $HOME or $kind has no references.
• ! followed by [ is an image, so ![diagram](arch.png) stays an image.
• An ampersand in prose is not a reference. R&D, a & b, and a && b have none, and neither does an HTML character reference such as & or  .
• Double brackets must hold a valid slug or entity address. [[Not A Slug]] and [[Component://Foo_Bar]] render as literal text.
• Empty braces such as @{} are not a reference.
• Code is inert. References in inline code, code blocks, and a page’s frontmatter are left alone.
• A backslash escapes a sigil. \@platform renders as @platform with no chip.

When a reference doesn’t resolve

A reference to something that doesn’t exist — misspelled, deleted, or renamed — renders as a warning chip with “Not found” instead of a link, so you can see it and fix the text. References are never rewritten for you: when a team, collection, scorecard, or entity is renamed, the pages that name it keep their text, and their chips turn into warnings until someone updates them. Schema keys and entity addresses rarely change, so $kind:service and #service://payments/api are the most stable ways to reference something.

Autocomplete in the editor

Typing #, @, $, !, or & where a reference can start opens a list of matching entities, teams, schema definitions, collections, or scorecards. Pick one and the editor inserts reference text that is guaranteed to parse. For $, choose kind:, rel:, or field: first. The list opens only where the sigil starts a line or follows a space, so typing an email address doesn’t open it, and never inside code.

Tag a page

Tags say what a page is about. The tag bar above the editor holds a list of references: choose Add reference, pick the kind of target with its sigil, and search for it. Each tag is exactly one reference — $kind:service, @platform, [[conventions/service-tiers]], or any other form from the table above. Saving a tag that isn’t exactly one reference, such as Platform Team with no sigil, is refused with WIKI_TAG_INVALID.

The tag bar is the only way to tag a page written in the app. A YAML frontmatter block at the top of the body is kept as you wrote it, but its tags: list doesn’t tag the page. That list is how pages synced from a repository are tagged. If you paste such a page into the editor, a note under the tag bar says so; add each tag with Add reference instead. Over GraphQL, REST, or MCP, pass the tags in the tags field.

A tagged page appears in the wiki references of everything it is tagged with, just as a page that mentions a target inline does. For AI agents, tags carry more weight: the guides tagged with a target are listed first, as the ones to read before working on it. Tag a guide with the kind it is about ($kind:service) so it appears whenever someone works on an entity of that kind.

Wiki references

Wherever you work on something a page references, Componecat shows the pages that reference it:

• An entity’s page shows a Wiki references panel on its Documentation tab, with the guides about the entity itself and about its kind. Kinds with documentation turned off have no Documentation tab, so their entities don’t show the panel.
• A team’s page, a collection’s page, a scorecard, an entity kind, and a relationship kind each show the guides that reference them. On an entity kind or relationship kind, the panel sits in a column to the right of the kind’s settings (below them on narrow screens) and is always shown, saying so when no page references the kind yet.
• Field definitions. When you open a field definition, to edit it or, if you aren’t an admin, to view it, the guides for that field ($field:tier) are listed in the dialog. When you create or edit an entity, a field with a guide shows a link to it beside the field.

Elsewhere, the panel appears only when at least one page references the target. It shows the first few guides with a short excerpt. See all in wiki opens All pages filtered to the pages that reference the target. Guide links in a form open in a new tab, so following one never discards your edits.

Search

Wiki pages are part of the global command palette (Cmd/Ctrl + K). Matches are listed under Wiki, with the page’s path and the passage that matched; selecting one opens the page. AI agents’ global_search tool and the REST API’s global search include wiki pages too. See Search and discovery.

Keep the wiki in a repository

The wiki can live in a GitHub, GitLab, or Bitbucket repository instead. An organization admin connects it under Wiki → Settings, choosing an integration with Documentation Syncing enabled, the repository, the branch, and the root path that holds the Markdown files. Then:

• Each .md file is a page. The file path gives the page address, so conventions/service-tiers.md becomes conventions/service-tiers. A README.md or index.md stands for its folder, and the one at the root path is the home page.
• The title comes from the frontmatter title, then the first # heading, then the file name. Tags come from the frontmatter tags list.
• The wiki is read-only in Componecat. Every page shows a banner naming the repository, the branch, and the last sync, with a link to edit the page’s file on the provider. Creating, editing, deleting, and restoring pages is refused with WIKI_EXTERNALLY_MANAGED — in the app, over the REST API, and from AI agents alike. Make changes in the repository; they appear after the next sync.
• The wiki stays current. It syncs on the integration’s schedule, when an admin chooses Sync now, and — with the integration’s webhook connected — within moments of a push that changes its Markdown files.

Connecting moves the existing pages to Trash, where they are kept until the wiki is disconnected. Disconnecting turns the synced pages back into pages you edit in Componecat. For the full import rules, sync on push, and sync history, see Source the wiki from a repository.

Use the wiki from the API and AI agents

Access to the wiki is its own wiki category on access tokens and agent authorizations, with read and write access granted separately.

• REST API. The wiki is under /api/rest/v1/wiki: list, read, create, update, and delete pages by slug, list a page’s references, find the pages that reference a catalog object, and read or sync the wiki’s git source. See APIs.
• MCP server. Agents can list and read pages (list_wiki_pages, get_wiki_page), create and edit them (create_wiki_page, update_wiki_page), and look up the guides for a target with get_guides_for, written in the same reference syntax: $kind:service, #service://payments/api, or @platform. Agents are told to read the guides for an entity’s kind before creating or editing an entity, so the conventions you write down are applied. See Connect AI agents.
• Outgoing webhooks report page changes and the references on each page. See Outgoing webhooks.

Related

• Documentation sync — import Markdown, including the wiki, from repositories.
• Documentation and activity — documentation that belongs to a single entity.
• Connect AI agents