Publish and share knowledge safely

Publishing makes knowledge easier to discover and increases the cost of mistakes. Review the entire sharing boundary—not only the fragment body—before making a workspace public or connecting it to a documentation site.

Decide what “published” means

Usable can expose knowledge through several paths:

• members in a private workspace;
• subscribers to a public workspace;
• a documentation site backed by a workspace;
• REST or MCP clients with access;
• webhook receivers and connected applications;
• cross-workspace symlinks.

Changing a fragment status to published does not override workspace access. Conversely, a public workspace can expose active content even when an author did not think of it as a formal document.

Prepare the source workspace

Define:

• audience and owner;
• included fragment types and statuses;
• title, summary, and tagging conventions;
• review and release process;
• file and screenshot policy;
• treatment of old releases;
• incident/removal process.

Separate private operational material from public documentation rather than relying on authors to remember which paragraphs are safe.

Review every content surface

Check:

• fragment title, summary, body, frontmatter, tags, and author-visible metadata;
• attached files, filenames, embedded images, and screenshots;
• collection names and descriptions;
• related links and symlink targets;
• workspace name, description, members, and visibility;
• webhook payload destinations and app permissions.

Remove secrets, tokens, cookies, keys, customer data, personal data without a lawful purpose, private URLs, internal tickets, and unreleased feature claims.

Screenshots can expose browser tabs, emails, hostnames, tokens, and admin-only controls. File metadata can expose author names and internal paths.

Write for humans and AI retrieval

A publishable page should have:

• one clear user question or outcome;
• prerequisites and audience;
• current terminology;
• complete durable content;
• expected results and failure guidance;
• concise summary and stable tags;
• links to canonical related pages;
• release context when behavior changes by version.

Avoid release-note dumps, unexplained endpoint lists, and duplicated definitions.

Validate permissions

Use the least-privileged role that represents the audience. Test as a viewer or subscriber, not only as an owner.

Confirm that:

• readers can open intended fragments and files;
• readers cannot edit settings or content;
• private workspaces and fragments remain inaccessible;
• applications and tokens are scoped to intended workspaces;
• public subscription does not accidentally grant authoring.

Publish a documentation workspace

For a workspace-backed docs site:

1. Create or select a dedicated documentation workspace.
2. Add consistent frontmatter required by the site, including unique slug, section, order, published status, and description.
3. Keep page titles and summaries useful outside sidebar context.
4. Configure tenant workspace identity, public site origin, and stable section order.
5. Publish pages in coherent reading order.
6. Revalidate or wait for the configured refresh interval.
7. Open every production route.

Use the public origin in generated links. Do not let development request origins leak into production indexes.

Verify discovery

Test:

• sidebar section and page order;
• direct routes and previous/next navigation;
• ordinary docs search;
• Usable fragment search;
• agentic search using realistic questions;
• full-source retrieval;
• llms.txt, llms-full.txt, and Markdown exports where provided;
• links from related pages.

An index entry is not enough: open the URL and confirm the body is current.

Maintain after publication

Assign an owner and review trigger. When behavior changes:

1. find the canonical page;
2. verify released sources;
3. update the page and related links;
4. remove stale files and duplicate pages;
5. reverify routes, search, and LLM indexes;
6. record material user-facing changes in the appropriate changelog source.

Keep schemas, prices, quotas, and tool inventories linked to authoritative deployed sources when they change frequently.

Respond to accidental disclosure

1. Remove or restrict the exposed content.
2. Rotate any credential immediately.
3. Disable affected integrations or webhooks.
4. review caches, files, indexes, and downstream copies;
5. notify the responsible owner and follow the applicable incident/privacy process;
6. republish only after verification.

Deleting a page does not invalidate copied credentials or remove downstream webhook data.

Related pages

• Organize and maintain useful knowledge
• Public workspace subscriptions
• Files in Chat, embeds, and secure deployments
• Security, privacy, and data lifecycle
• Frontmatter and metadata