Fragment symlinks

A fragment symlink makes a fragment from one workspace available in another workspace as a read-only child. The source remains the parent and the maintained source of truth.

Use a symlink when the same knowledge should be discoverable in more than one workspace without creating independent copies that can drift apart.

Parent and child

A symlink has two sides:

• The parent fragment is the original, editable source in its workspace.
• The child fragment is the linked, read-only representation in the target workspace.

When the parent is updated, the child is synchronized. When the parent is deleted, its symlink child is deleted as part of the relationship. Removing the symlink deletes the child copy but leaves the parent intact.

Because the child is read-only, changes should be made at the parent. This preserves one clear source of truth.

Access and permissions

Creating a symlink crosses workspace boundaries, so the caller must have suitable owner or collaborator access in both the source and target workspaces. The operation also requires fragment update permission.

Removing a symlink requires permission to delete the child relationship and appropriate access to the parent workspace.

A symlink does not make private knowledge public by itself, and it should never be used to work around workspace permissions. Before linking into a broader workspace, review whether the parent’s content is appropriate for that audience.

When to use a symlink

Symlinks are useful for maintained knowledge that belongs conceptually to one workspace but is relevant in another.

Examples include:

• a shared security policy referenced by several team workspaces;
• a canonical API authentication guide exposed in both product and developer documentation;
• a standard operational procedure made available to multiple service workspaces.

The parent workspace should be the place responsible for maintaining the content.

When to copy instead

Create an independent fragment rather than a symlink when the target needs to diverge.

For example, a public explanation derived from an internal runbook should usually be rewritten as a separate public fragment. The two documents serve different audiences and should not automatically synchronize private operational detail.

Copying creates maintenance responsibility: future updates must be reviewed separately. Use it only when independence is intentional.

Symlinks and workspace context

The child appears in the target workspace, where it can participate in that workspace’s discovery experience. Readers should still be able to understand the fragment outside its original workspace context.

Write parent titles and summaries so they remain meaningful wherever the fragment is linked. Avoid unexplained references such as “this workspace” when the content may appear elsewhere.

Automatic linking rules

Usable also supports workspace-level auto-link rules in supported interfaces. A rule can match exact tags on source fragments and create symlink children in a target workspace.

Rules can match any configured tag or require all configured tags. Preview the result before enabling or reprocessing a rule, especially when the target has a broader audience.

Automatic linking skips existing symlink children and includes cycle protection. Treat rule execution as eventually consistent: the parent operation can complete before all linked effects are visible.

Use automation for stable, reviewed routing conventions—not as a substitute for deliberate publishing.

Example: one canonical policy

An organization keeps its approved incident communication policy in a governance workspace. Engineering and support both need it in their normal search scope.

The governance fragment remains the parent. Symlink children are created in the engineering and support workspaces. The governance team updates one source, and both linked contexts receive the revised content.

If a public-facing policy needs sensitive details removed, it should be a separately maintained public fragment rather than another symlink child.

Good practices

• Choose a parent workspace that clearly owns maintenance.
• Review the target audience before creating the link.
• Keep parent titles, summaries, and content understandable across contexts.
• Edit the parent rather than trying to change a child.
• Use independent copies when content must diverge.
• Preview broad tag-based auto-link rules before enabling them.
• Remove stale symlinks when the target no longer needs the source.

Related concepts

• Workspaces define the boundaries a symlink crosses.
• Memory fragments explains the source knowledge being linked.
• Tags and summaries are especially important for automatic rules and cross-context clarity.
• Collections group fragments within one workspace; they do not share content across workspaces.