Documentation Index
Fetch the complete documentation index at: https://docs.oktolabs.ai/llms.txt
Use this file to discover all available pages before exploring further.
Entities and states
This page maps the product concepts to the actual source entities in okto-pulse-core/src/okto_pulse/core/models/db.py and their API schemas in models/schemas.py. Use it when you need to know what Pulse stores, which lifecycle values are valid, and where each object is reachable.
Core delivery entities
| Entity | Source model | Primary routes | MCP surface | Purpose |
|---|
| Agent | Agent | /api/v1/agents | Board management tools | Actor that owns an API key, permissions, and board access. |
| Agent board grant | AgentBoard | /api/v1/agents/{agent_id}/boards/{board_id} | Agent access tools | Board-scoped access row with optional permission overrides. |
| Permission preset | PermissionPreset | /api/v1/presets | Permission and agent tools | Named permission set that can be attached to agents. |
| Board | Board | /api/v1/boards | okto_pulse_get_board, board CRUD tools | Workspace container for the SDLC graph. |
| Ideation | Ideation | /api/v1/boards/{board_id}/ideations, /api/v1/ideations/{ideation_id} | Ideation tools | Initial problem statement and ambiguity-killer workflow. |
| Refinement | Refinement | /api/v1/ideations/{ideation_id}/refinements, /api/v1/refinements/{refinement_id} | Refinement tools | Evidence-gathering phase between ideation and spec. |
| Spec | Spec | /api/v1/boards/{board_id}/specs, /api/v1/specs/{spec_id} | Spec tools | Delivery contract with requirements, criteria, scenarios, decisions, rules, contracts, and TRs. |
| Sprint | Sprint | /api/v1/boards/{board_id}/sprints, /api/v1/sprints/{sprint_id} | Sprint tools | Scope slice that groups cards and closes through sprint evaluation. |
| Card | Card | /api/v1/boards/{board_id}/cards, /api/v1/cards/{card_id} | Card and task tools | Execution unit: normal work, test task, or bug task. |
| Card dependency | CardDependency | /api/v1/cards/{card_id}/dependencies | Dependency tools | depends_on relationship between two cards. |
Evidence and collaboration entities
| Entity | Source model | Primary routes | Purpose |
|---|
| Q&A item | QAItem, IdeationQAItem, RefinementQAItem, SpecQAItem, SprintQAItem | /api/v1/qa/*, /{entity}/{id}/qa | Structured questions and answers on cards and SDLC artifacts. |
| Comment | Comment | /api/v1/comments/* | Text comments and single/multi-choice comment boards on cards. |
| Attachment | Attachment | /api/v1/attachments/{board_id}/{card_id} | Uploaded files attached to cards. |
| Guideline | Guideline, BoardGuideline | /api/v1/guidelines, /api/v1/boards/{board_id}/guidelines | Global or board-specific rules agents must read before work. |
| Activity log | ActivityLog | /api/v1/cards/{card_id}/activity | Audit trail for card-visible changes. |
| Seen marker | AgentSeenItem | /api/v1/cards/{card_id}/seen | Per-agent unread/seen state for mentions and changes. |
| Validation | JSON records on Card, Spec, and Sprint plus validation response schemas | Card/spec/sprint validation routes | Independent review and lifecycle gate evidence. |
Spec sub-objects
These are stored inside a spec payload, exposed through spec routes and MCP spec tools, and copied into card context when work starts.
| Object | Source schema/model | Purpose |
|---|
| Business rule | BusinessRule | Rule linked to one or more functional requirements and implementation cards. |
| API contract | ApiContract | Endpoint or integration contract with method, path, payload shape, and linked cards. |
| Technical requirement | TR object in Spec | Non-functional or implementation-level requirement linked to tasks. |
| Acceptance criterion | AC list in Spec | User-visible condition that must be covered by scenarios and tasks. |
| Test scenario | TestScenario payload | Testable scenario; must be linked to test cards before validation. |
| Decision | Decision payload in Spec | Explicit architecture/product choice; can be active, superseded, or revoked. |
| Screen mockup | ScreenMockup, MockupAnnotation | HTML mockup and annotations attached to ideations, refinements, specs, or cards. |
| Architecture design | ArchitectureDesign, ArchitectureDesignVersion, ArchitectureDiagram | Structured architecture payloads, diagrams, versions, and diffs. |
Knowledge entities
| Entity | Source model | Primary routes/tools | Purpose |
|---|
| Ideation knowledge | IdeationKnowledgeBase | /api/v1/ideations/{id}/knowledge, MCP knowledge tools | Evidence attached before refinement/spec derivation. |
| Refinement knowledge | RefinementKnowledgeBase | /api/v1/refinements/{id}/knowledge, MCP knowledge tools | Evidence gathered during refinement. |
| Spec knowledge | SpecKnowledgeBase | /api/v1/specs/{id}/knowledge, MCP knowledge tools | Source material attached to the delivery contract. |
| Card knowledge | JSON records on Card.knowledge_bases | /api/v1/cards/{id}/knowledge, MCP knowledge tools | Context copied or written directly onto a task. |
| Consolidation queue | ConsolidationQueue | /api/v1/kg/boards/{board_id}/pending | SQLite work queue that drains artifacts into the graph. |
| Consolidation dead letter | ConsolidationDeadLetter | /api/v1/kg/queue/dead-letter, KG DLQ MCP tools | Failed KG consolidation work that exhausted retries. |
| Consolidation audit | ConsolidationAudit | /api/v1/kg/boards/{board_id}/audit | System-of-record for committed KG sessions. |
| KG tick run | KGTickRun | /api/v1/kg/tick/run-now, KG health | Relevance decay tick execution record. |
| Domain event | DomainEventRow, DomainEventHandlerExecution | Event dispatcher internals | Durable event and handler execution tracking. |
Discovery and analytics entities
| Entity | Source model/schema | Route family | Purpose |
|---|
| Discovery intent | DiscoveryIntent | /api/v1/discovery/intents | Saved operator intent that maps to a tool-backed discovery action. |
| Saved search | DiscoverySavedSearch | /api/v1/discovery/boards/{board_id}/saved-searches | Reusable board search. |
| Search history | DiscoverySearchHistory | /api/v1/discovery/boards/{board_id}/search-history | History of executed discovery searches. |
| Analytics entity row | Analytics response schemas | /api/v1/boards/{board_id}/analytics/entities | Spec, ideation, card, sprint, agent, and board metrics for dashboards and exports. |
Status enums
| Enum | Values |
|---|
IdeationStatus | draft, review, approved, evaluating, done, cancelled |
IdeationComplexity | small, medium, large |
RefinementStatus | draft, review, approved, done, cancelled |
SpecStatus | draft, review, approved, validated, in_progress, done, cancelled |
SprintStatus | draft, active, review, closed, cancelled |
CardStatus | not_started, started, in_progress, validation, on_hold, done, cancelled |
CardPriority | critical, very_high, high, medium, low, none |
CardType | normal, bug, test |
BugSeverity | critical, major, minor |
CommentType | text, choice, multi_choice |
Lifecycle relationships
| Parent | Children |
|---|
| Board | Ideations, agents, guidelines, KG graph, queue, and audit rows |
| Ideation | Refinements and specs |
| Refinement | Specs, knowledge, mockups, architecture, Q&A, snapshots, and history |
| Spec | Sprints, cards, business rules, API contracts, test scenarios, decisions, knowledge, mockups, architecture, Q&A, validations, and history |
| Sprint | Assigned cards, evaluations, Q&A, and history |
| Card | Dependencies, knowledge, mockups, architecture, Q&A, comments, attachments, conclusions, validations, and activity |
- Cards should link to a spec; bug and test cards have additional scenario-link rules.
- A sprint closes only after sprint evaluation and test evidence checks pass.
- A normal card reaches
done through the task validation gate.
- Spec
approved to validated requires coverage validation; validated to in_progress requires spec evaluation.
- Deleting ideations or refinements can remove a full subtree; use archive/restore for reversible hiding.
See SDLC flow, Validation gates, and REST route catalog for the operational surfaces.
