Documents
Documents are project-level Markdown documents meant for human readers. Unlike plans, completion reports, and co-actions, they are not tied to one fixed workflow. Use them for onboarding notes, design memos, user guides, operating procedures, research notes, and other knowledge that should remain easy to find.
The detail view shows the tags, share link, content, and comments together.
When to use documents
| Situation | Why documents help |
|---|---|
| Onboarding material | New members or new agent sessions can understand project context quickly. |
| Design notes | Preserve decision background and alternatives that do not belong directly in code. |
| Repeated procedures | Keep release, verification, and incident-response steps in one place. |
| Shareable writing | Create a public link and revoke it when sharing is no longer needed. |
| Collaborative review | Comment on the document and track revision history while editing. |
Plans describe “what should be done.” Completion reports describe “what was done.” Co-actions hand context to the next session. Documents preserve human-readable knowledge that does not fit those workflow records.
Create a document in the web app
Open Documents from the web sidebar, then select New document.
- Enter a title.
- Add comma-separated tags, such as
onboarding, release. - Choose visibility.
- Write Markdown content or import a Markdown file.
- Save the document.
The list page supports title/body search, tag filtering, visibility display, and archive-state filtering.
Attachments
On a project document detail page, you can attach image, PDF, text, Markdown, and HTML files, plus macro-free Word (.docx), PowerPoint (.pptx), and Excel (.xlsx) files. Office formats are supported only on document attachments. Macro-enabled formats (.docm, .pptm, .xlsm) and legacy formats (.doc, .ppt, .xls) are not supported.
Images, PDFs, text, Markdown, and HTML can be previewed in the app. Office files cannot be previewed, so download them to view their contents. An uploaded file appears immediately in the list below the document body, and files uploaded by mistake can be deleted from the document detail page. Each file can be up to 10MB, with up to 10 attachments per document.
Attachments belong to the document’s current state and are not part of document revision history. The same attachment list is available as read-only content in the Home activity panel.
Visibility and archive state
| Item | Meaning |
|---|---|
PROJECT | A document visible to project members. |
PRIVATE | A personal document centered on the author. |
| Active | A document shown in the normal list. |
| Archived | A document kept for history but separated from the active list. |
If a document is no longer used often but should remain as a record, archive it instead of deleting it. Archived documents can be unarchived later.
Revisions and restore
Edits create revision history. You can open previous revisions, inspect their content, and restore a selected version. Restoring does not erase the current content silently; the restore is preserved as a new revision.
Revision restore is useful when:
- a bad edit needs to be rolled back
- an older operating procedure must be checked
- a design note changed several times and you need to trace the path
Share links
Documents can have share links. When sharing is active, copy the link and send it to another reader. Revoke the link when it should no longer be accessible. The shared document page shows author, visibility, archive state, and attachment information. Anyone with the share link can also download attached files; revoking the share prevents that link from accessing both the document and its attachments.
Before sharing, check that the document does not include secrets, tokens, or internal-only URLs.
Comments
The document detail page supports comments. Select text in the body and click Quote to include that text in the comment. Comments can be sorted newest-first or oldest-first, and your comments can be edited or deleted.
Writing tips
- State the document purpose in the first paragraph.
- If the content belongs in a plan, report, or co-action, use that workflow instead.
- Add tags to documents that will be referenced repeatedly.
- Before public sharing, check for secrets, tokens, and internal URLs.
- When the reason for a change matters, leave context in the body or a comment.