Documents & Editor
Draft, edit, version, and publish product documents with structured blocks and AI-powered refinement.
Overview
Documents are the final output of the Praxiom AI product loop. The AI agent drafts complete product documents — PRDs, technical specs, decision memos, user stories, roadmap updates, and release notes — grounded in your research insights with inline citations, direct quotes, and evidence. Documents are composed of typed blocks and editable in a rich TipTap editor with a full PM IDE experience.
Supported Document Types
| Type Key | Label | Description |
|---|---|---|
prd | Product Requirements Document | 8-section PRD with problem statement, user stories, requirements, and success metrics |
spec | Technical Specification | 7-section spec covering architecture, data models, APIs, and implementation plan |
memo | Decision Memo | 6-section memo for leadership alignment on strategic product decisions |
user_story | User Stories | Structured epics and user stories with acceptance criteria |
roadmap_update | Roadmap Update | Quarterly roadmap update summarizing what shipped and what is planned |
release_notes | Release Notes | Customer-facing release notes for new features and improvements |
How It Works
Choose a recommendation
Select an accepted recommendation to base the document on. The agent uses the recommendation's linked insights, quotes, and rationale as grounding context. You can also draft without a recommendation by providing user_instructions directly.
Draft the document
Call POST /api/documents/draft:
| Field | Type | Description |
|---|---|---|
workspace_id | UUID | Target workspace |
document_type | String | One of: prd, spec, memo, user_story, roadmap_update, release_notes |
recommendation_id | UUID | Optional — the recommendation to base the document on |
user_instructions | String | Optional — additional guidance for the agent |
The agent fetches the recommendation, linked insights, workspace context, and applies the document template. Drafting takes 20-45 seconds. The result is saved with status draft.
Edit in the rich editor
Documents render in a TipTap-based rich text editor with full formatting support:
- Formatting — Bold, italic, code, headings (H1-H6), blockquotes
- Lists — Bullet lists, numbered lists, task lists
- Tables — Full table support with add/remove rows and columns
- Code blocks — Syntax-highlighted code with language detection
- Images — Inline image attachments
- Keyboard shortcuts — ⌘B (bold), ⌘I (italic), ⌘S (save), ⌘K (command palette)
- Slash commands — Type
/for quick insertion of headings, lists, tables, code blocks - Floating toolbar — Select text to see formatting options
- Autosave — Changes are saved automatically with a 2-second debounce
Structure into blocks (PM IDE)
Open the document in the PM IDE view to work with structured blocks. Each block has a type that defines its purpose and the AI's approach to refining it:
| Block Type | Description |
|---|---|
problem | Problem statement with user impact and scope |
persona | User persona with demographics, goals, and pain points |
solution | Proposed solution with approach and trade-offs |
metrics | Success metrics with baselines and targets |
user_story | User stories with acceptance criteria |
edge_case | Edge cases and boundary conditions |
risk | Risks with likelihood, impact, and mitigation |
timeline | Timeline with milestones and dependencies |
free_text | Freeform content for anything else |
Blocks can be reordered via drag-and-drop and support CRUD operations via the API.
Block Actions
Each block supports three AI-powered actions that help you refine content:
Expand
POST /api/blocks/{block_id}/expand
Fleshes out a block with deeper detail using its type-specific contract. For example, expanding a user_story block generates detailed acceptance criteria, while expanding a metrics block adds baseline values and measurement methodology.
Challenge
POST /api/blocks/{block_id}/challenge
Provides an adversarial critique of the block content. Returns:
- Strengths — What the block does well
- Weaknesses — Gaps, assumptions, or logical issues
- Questions — Open questions that should be answered
- Suggestions — Specific improvements
Simulate
POST /api/blocks/{block_id}/simulate
Explores the real-world implications of a block. For a solution block, this might simulate user reactions, engineering challenges, or market dynamics. For a risk block, it models cascading failure scenarios.
Block actions use surrounding blocks (up to 8) as context, so the AI understands how each block fits into the larger document.
Intent Parser
Convert raw text input into a structured document skeleton:
POST /api/intent/parse
{
"raw_input": "We need to fix the onboarding drop-off. Users are abandoning at step 3...",
"workspace_id": "your-workspace-uuid"
}The intent parser decomposes your input into typed blocks automatically, giving you a starting structure that you can refine in the PM IDE.
Block Extraction
Extract block structure from an existing document:
POST /api/blocks/extract
{
"workspace_id": "your-workspace-uuid",
"document_id": "doc-uuid"
}This analyses the document's Markdown content and creates typed blocks from its sections. Useful for converting legacy documents into the structured block format.
Block Annotations
Add comments and feedback to specific blocks:
Annotations support collaborative review workflows where team members can leave targeted feedback on individual sections of a document rather than commenting on the whole document at once.
Version History
Praxiom tracks every meaningful change to a document as an immutable revision.
Save a Version
POST /api/documents/{document_id}/versions
{
"change_summary": "Revised success metrics based on stakeholder feedback"
}List Versions
GET /api/documents/{document_id}/versions?limit=50
Returns revisions sorted newest-first, each with revision_number, title, content, change_type, change_summary, word_count, and changed_by.
Compare Versions
GET /api/documents/{document_id}/diff?from_revision=1&to_revision=3
Returns a line-level diff with additions, deletions, and changes counts, along with the full content of both revisions.
Restore a Version
POST /api/documents/{document_id}/versions/{revision_id}/restore
Rolls back the document to a previous state. The current state is saved as a revision before restoring, so nothing is lost.
Review Workflow
Documents progress through a review pipeline:
draft → review → approved → published
Transition status with POST /api/documents/{document_id}/status:
{
"target_status": "review",
"change_summary": "Ready for stakeholder review"
}Valid transitions:
| From | To | Action |
|---|---|---|
draft | review | Submit for review |
review | approved | Approve |
review | draft | Request changes |
approved | published | Publish |
approved | draft | Revert to draft |
published is a terminal state. Once published, a document cannot be transitioned further. You can still edit it and save new versions.
Editor Intelligence
The TipTap editor includes an Intelligence Panel with five AI-powered tabs:
| Tab | Description |
|---|---|
| Proofread | Grammar, clarity, and consistency checks |
| Verify | Citation and evidence verification |
| Citations | Source attribution and quote accuracy |
| Gaps | Missing sections, unanswered questions |
| Summary | Auto-generated executive summary |
Additional AI features:
- AI Rewrite — Select text and rewrite with AI assistance
- Continue Writing — AI extends content from where you left off
CRUD Operations
| Operation | Endpoint |
|---|---|
| List | GET /api/documents?workspace_id={id}&document_type=prd&status=draft |
| Get | GET /api/documents/{id} |
| Create | POST /api/documents |
| Update | PATCH /api/documents/{id} |
| Delete | DELETE /api/documents/{id} |
What's Next
Learn about the chat agent and how it ties all these workflows together in the Chat Agent guide. For block-level API details, see the Blocks API reference.
Was this helpful?