> ## 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.
# Quickstart
> From idea to your first validated card in 5 minutes
**Prerequisites**
* Pulse installed and serving? If not → [Install](/install)
* Agent connected via MCP? If not → [MCP Setup](/mcp-setup)
This walkthrough uses a concrete example — adding user authentication — so every step has a visible output. The CLI path uses Claude Code; the UI path works for any browser.
***
`okto-pulse init` already created a default board when you installed. Verify it's there:
**Via MCP (Claude Code):**
```text theme={null}
> list my boards
```
Claude Code calls `okto_pulse_list_my_boards` and returns:
```json theme={null}
[
{
"id": "a1b2c3d4-...",
"name": "My Project",
"created_at": "2026-05-07T10:00:00Z"
}
]
```
**Via UI:**
Open [localhost:8100](http://localhost:8100). The board is already selected in the sidebar. You don't need to create one.
If you want a dedicated board for this project:
```bash theme={null}
# From Claude Code:
> create a board called "Auth Project"
# From UI:
# Settings → Boards → New Board
```
Ideations are where raw requests land before anything gets built.
**Via MCP (Claude Code):**
```text theme={null}
> create an ideation: "I want to add user authentication to my app"
```
Pulse calls `okto_pulse_create_ideation` and returns:
```json theme={null}
{
"id": "9c64cdac-...",
"title": "Add user authentication",
"raw_request": "I want to add user authentication to my app",
"status": "draft",
"scope_assessment": null
}
```
**Via UI:**
Ideations tab → **New Ideation** → paste your raw request → Save.
The ideation is now in `draft` state. Pulse has not made any decisions yet.
This is the step that makes Pulse different from a rules file.
Pulse analyzes your ideation and surfaces every material gap before you write a line of spec. Ask it to evaluate:
```text theme={null}
> evaluate ideation 9c64cdac
```
Pulse runs `okto_pulse_evaluate_ideation` and returns a scope assessment:
```json theme={null}
{
"domains": 3,
"ambiguity": 4,
"dependencies": 2,
"ambiguity_notes": "Auth strategy unspecified (OAuth, password, passkey); session management approach unclear; email verification scope undefined"
}
```
Ambiguity is 4/5 — Pulse won't let this become a spec yet. It asks:
```text theme={null}
> ask ideation questions
```
Pulse calls `okto_pulse_ask_ideation_choice_question`:
```text theme={null}
Q1 (choice): Which authentication strategy should we use?
A. Email + password with bcrypt hashing
B. OAuth only (Google, GitHub)
C. Both: password-based with optional OAuth link
D. Passkeys / WebAuthn (passwordless)
```
You (or the agent) answers:
```text theme={null}
> answer: A — email + password with bcrypt
```
Pulse records the answer via `okto_pulse_answer_ideation_question`:
```json theme={null}
{
"question_id": "q-001",
"answer": "Email + password with bcrypt hashing",
"answered_by": "agent:claude-code",
"timestamp": "2026-05-07T10:03:41Z"
}
```
Pulse continues for each gap. When ambiguity drops below the threshold, it marks the ideation `ready_for_refinement`.
You can ask all the questions in one shot:
`> run the ambiguity-killer protocol on ideation 9c64cdac`
Pulse will call `ask_ideation_question` for each gap, accept your answers, and re-evaluate. Typical ideation takes 4–7 questions.
Once the ideation is evaluated, derive the spec. Pulse builds it from your answers — you don't type a spec from scratch.
```text theme={null}
> derive spec from ideation 9c64cdac
```
Pulse calls `okto_pulse_derive_spec_from_ideation` and returns a populated spec:
```json theme={null}
{
"id": "spec-8a3f...",
"title": "User Authentication — Email + Password",
"problem_statement": "The application has no authentication layer. Users cannot register, log in, or maintain sessions.",
"acceptance_criteria": [
"User can register with email and password",
"Password is stored as bcrypt hash (cost factor ≥ 12)",
"User can log in and receive a session token",
"Invalid credentials return 401 with no information leakage",
"Session expires after 30 days of inactivity"
],
"functional_requirements": ["..."],
"test_scenarios": [],
"business_rules": [],
"status": "draft"
}
```
The spec is pre-populated from your ideation answers. The acceptance criteria came from your answer to Q1 and Pulse's domain knowledge. You didn't write them.
Review and refine in the UI (Specs tab → open spec → edit inline), or via MCP:
```text theme={null}
> add acceptance criterion: "Password reset via email link with 1-hour expiry"
```
When the spec looks right:
```text theme={null}
> submit spec evaluation
```
Pulse calls `okto_pulse_submit_spec_evaluation`. If coverage meets thresholds (acceptance criteria ≥ 80%, test scenarios linked), the spec moves to `approved`.
Cards are execution units. Each one traces back to the spec you just created.
```text theme={null}
> suggest sprints for spec spec-8a3f
```
Pulse calls `okto_pulse_suggest_sprints` and proposes a sprint slice. Accept it:
```text theme={null}
> create sprint "Auth Sprint 1" with objective "Ship registration and login endpoints"
```
Then create the first card:
```text theme={null}
> create card: "Implement POST /auth/register endpoint"
type: task
description: "Register endpoint: accept email + password, validate format, hash with bcrypt (cost 12), store user, return 201 + user ID. Return 409 on duplicate email."
sprint: Auth Sprint 1
```
Pulse calls `okto_pulse_create_card`. The card is created in `pending` state, linked to the spec and sprint.
Move it to active work:
```text theme={null}
> move card to in_progress
```
**Via UI:**
Drag the card from the **Pending** column to **In Progress** on the board.
The board now shows one active card, a sprint, a spec, and an ideation — all connected.
***
## What just happened
You went from a vague idea to a tracked, traceable card in 5 minutes. Here's what Pulse actually did:
* **The KG now contains a Decision node.** The answer "email + password with bcrypt" was written to the knowledge graph as a `Decision` with type `AuthStrategy`. Any future ideation about login, session management, or password reset will surface this decision automatically — before a new agent accidentally decides something contradictory.
* **Your agent can query that decision mid-task.** At any point during implementation, Claude Code (or Cursor, or Cline) can call `okto_pulse_kg_query_natural("What auth approach did we decide?")` and get the answer back from the graph — not from context window memory. The answer is there whether the session is 2 minutes old or 2 months old.
* **Everything survives the next session.** The ideation, Q\&A, spec, sprint, and KG decision nodes are stored in SQLite + the embedded graph at `~/.okto-pulse/boards/{id}/graph.lbug`. Start a new Claude Code session tomorrow, point it at the same board, and it has full context — without you re-explaining anything.
***
What Pulse wrote to the graph just now, and how your agent queries it mid-task.
Full agent configuration for Claude Code, Cursor, Cline, Windsurf, Goose, and Codex.