Community publications
Canonical Octonode repository documentation.
Community publications
Octonode has four deliberately separate content authorities:
| Content | Authority | Recovery |
|---|---|---|
| Official Playbook and product documentation | reviewed Markdown in this repository | Git history and normal repository backup |
| Private drafts and editorial comments | Design Docs in the source workspace | workspace social backup plus the DESIGN_DOCS bucket |
| Published guide, blog, or paper revisions | marketplace D1 metadata and immutable COMMUNITY_CONTENT R2 objects | D1 point-in-time recovery plus versioned R2 retention |
| Keyword and assistant indexes | derived D1 FTS5 / community retrieval data | rebuild from published revisions |
Publishing copies one exact Markdown Design Doc revision. It does not publish the source document, comments, workspace membership, or later edits. Public revisions are immutable and addressed by publication and revision IDs.
Public discussion is a separate flat comment stream on the published revision. Reads are public; writes require a verified user session, accept at most 2,000 characters, are idempotent, and are limited to 20 comments per user per hour. Private Design Doc review threads and user IDs are never copied into public comments. Workflow-template discussion reuses its linked publication stream.
Lifecycle and permissions
The lifecycle is draft → in_review → published | changes_requested | rejected; changed drafts may
be submitted again, and any non-draft state may be archived where the schema permits. All mutations
use an expected version, and create/revision writes use an idempotency key.
content:read and content:write are ordinary member permissions. content:publish and
content:moderate default only to owners, administrators, and team leads. Personal workspaces can
author drafts but cannot moderate their own submissions. Public routes expose only published
revisions and return 404 for private or inaccessible identifiers.
The product header links to the repository-owned Playbook and public API reference. Playbook is a
publication surface only; Architecture data never creates a Playbook entity or relationship. Private drafts
remain visible only to their author; administrative review states and moderation queues require
content:moderate. Neither is projected into public navigation.
Metadata and relationships
Kinds are guide, blog, and paper. Publications carry bounded titles, summaries, licenses,
topics, ordered authors, and optional CSL-JSON citations. Relationships are typed: OpenAPI
operationId, official repository document path, publication ID, plugin ID, workflow-template ID,
or external URL. API prose is never copied into the publication record; the current OpenAPI document
is the reference authority.
Search and retrieval
Public search, filters, ordering, visibility, and keyset pagination execute in marketplace D1. The
browser only presents returned pages. Community content never enters OCTONODE_KNOWLEDGE. Only a
moderator-approved, published revision with assistantEligible may enter the separately labelled
community retrieval source, and archive/rejection removes it from active discovery.
Retention and deletion
R2 is written before D1. A failed metadata transaction deletes the newly written object. Revision keys are never reused. Archive removes active FTS and retrieval entries but retains the immutable revision and append-only moderation record for audit and recovery. Permanent erasure is an operator procedure that records the decision, exports required audit data, removes derived indexes, deletes R2 revisions, and finally deletes metadata.