Project Documentation

Preview — available from release 26.05. Schema, endpoint, and rendered UI may change or be removed at any time while the feature is in preview.

Project Documentation is a per-namespace markdown document rendered inside the platform UI. It is meant for the implementation team to surface customer-facing notes — data sources, flows, contacts, runbooks — to business users without sending them to a separate wiki.

The document is uploaded via the API and rendered as a side panel that opens alongside whichever page the user is currently viewing. A CLI command is provided for convenience but it is not the only way to upload — anything that can issue an authenticated PUT request to the platform can update the document.

Who can see and update it

Capability	Permission	Default group
View the panel	read documentation	Default group (every namespace member)
Update the document	update documentation	Owner / FullAccess group

The read documentation scope is added to the Default group during namespace bootstrap, so every authenticated namespace member can read the document. Writes are gated behind update documentation, which is included in the FullAccess group.

⚠️ This document is shared with all users. Do not include secrets, credentials, internal infrastructure details, or anything you would not want a user to see.

Where it shows up

When a document has been uploaded for the active namespace, a Project Documentation button appears in the platform top bar, to the left of the user / namespace / avatar block. Clicking it opens a side panel that:

• Renders the markdown using a sanitizing markdown pipeline.
• Stays open while you navigate between pages.
• Has a draggable resizer on the left edge; the chosen width is persisted in localStorage.
• Closes on Escape or by clicking the X in the panel header.
• Hides the button entirely when no document has been uploaded.

How to upload a document

Via the API

The document is a singleton resource at:

PUT /v1/organizations/{organization}/projects/{project}/namespaces/{namespace}/documentation
GET /v1/organizations/{organization}/projects/{project}/namespaces/{namespace}/documentation

The PUT body is the ProjectDocumentation message itself:

{
  "name": "organizations/energyworx.org/projects/demo/namespaces/enrx_org_001/documentation",
  "content": "# My project\n\n..."
}

The authenticated user must have the update documentation permission on the target namespace.

Via the CLI

A command is available in ewx-cli under the project-documentation group as a convenience wrapper around the API:

# Upload a markdown file as the namespace's documentation.
ewx-cli project-documentation update <namespace> <path>

# Print the current documentation for a namespace.
ewx-cli project-documentation get <namespace>

Example:

ewx-cli project-documentation update demo/enrx_org_001 ./PROJECT.md

How to keep it up to date

The recommended workflow is to keep a PROJECT.md file at the root of the implementation repo for the customer and re-upload it on every relevant change (new flow, new market adapter, new data source, contact change, etc.). Tying the upload to your deploy pipeline keeps the platform copy and the source-of-truth copy in sync.

What can be inside

Anything supported by standard CommonMark plus tables, code blocks, fenced code, ordered/unordered lists, and inline links. HTML is sanitized out of the rendered output.