@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/docs/briefing/briefing-craft.md

@@ -0,0 +1,237 @@
+---
+description: "Oracle deep guide — strong vs weak briefing examples, JTBD problem framing, Opportunity Solution Tree, Cagan's four risks, gap analysis, open-questions taxonomy, conversation playbook. Load when an existing briefing feels weak, when the conversation goes generic, or when a complex Themes section needs partitioning."
+---
+
+# Oracle — Briefing Craft
+
+Load this when:
+- The current briefing feels generic, surface-level, or PM-handover-ready (it shouldn't yet — that's `@product`'s job).
+- The conversational mode is producing answers that read like feature descriptions instead of problems.
+- The briefing has more than 3 unanswered open questions and you need to classify them.
+- A Theme is complex enough to warrant a sub-briefing and you need partitioning rules.
+
+Goal of every briefing: give `@product` enough confidence to either commit to a PRD, send it back for more discovery, or shelve it consciously. **Briefings are the bridge between "raw idea" and "committed PRD" — not a draft PRD.**
+
+## 1. Strong vs weak briefing — concrete signals
+
+### Strong briefing markers
+
+- **Problem section reads as a JTBD statement** ("When [situation], I want to [motivation], so I can [outcome]"), not as a feature description.
+- **Each open question** has a specific decision-maker named and a research path classified (research-able / testable / decision-required / out-of-scope).
+- **Risks are categorized** by Cagan's four (value, usability, feasibility, viability) plus an explicit "risk of NOT doing it".
+- **Sources cite specific evidence** — interview count, market sizing with method, competitor URLs, log data, support-ticket counts.
+- **Gaps explicitly contrast** current state vs desired state with measurable deltas.
+- **Themes break a complex briefing** into 2–4 sub-areas, each with one clear concern.
+- **Two voices visible** — at minimum a PM perspective and an engineering or design perspective. Solo briefings underestimate feasibility risk.
+
+### Weak briefing markers (anti-patterns)
+
+- **Problem as solution disguise**: "users need a settings page" — that's a solution. The problem is what they can't accomplish today without it.
+- **Open questions without owners**: "TBD: how should this work?" rots forever.
+- **Generic risks**: "users may not adopt" applies to every feature; it tells `@product` nothing.
+- **Sources = "internal discussion"** with no external research.
+- **Themes that repeat the table of contents** instead of partitioning concerns.
+- **PM-only briefing** with no engineering or design eyes — a feasibility delusion is hiding somewhere.
+
+## 2. Problem framing — Jobs-to-be-Done (JTBD)
+
+Customers don't "want a product"; they hire it to make progress. The job is the *progress*, not the surface task.
+
+**JTBD statement format:**
+```
+When [situation/trigger], I want to [motivation], so I can [expected outcome].
+```
+
+**Examples:**
+
+- ❌ Surface task: "User wants to upload a file."
+- ✅ JTBD: "When I'm collaborating on a document with my team and need their input fast, I want to share my work with one click, so I can keep momentum without losing context."
+
+- ❌ Feature description: "Add a settings page."
+- ✅ JTBD: "When my team's preferences differ from defaults and I'm tired of explaining workarounds, I want to lock in our setup once, so I can stop being the configuration person."
+
+**The "why now?" question** that makes a JTBD complete: *what changed* that makes this surface today? A trigger always exists — a new hire, a competitor launch, a regulation, a project failure. If you can't name the trigger, the problem isn't ripe.
+
+**Switch interview protocol** (when the conversation has a real user the agent can talk through):
+1. Reconstruct the moment they switched from one solution to another (or chose to start using something).
+2. Capture the trigger, the alternatives considered, the anxieties about switching, the decision criteria, and the first-use experience.
+3. Ten to fifteen well-conducted switch interviews provide more actionable insight than months of survey data.
+
+## 3. Opportunity space — Teresa Torres' Opportunity Solution Tree
+
+Use this when the briefing has the shape "we want to improve X, but we're not sure where to invest" — i.e., outcome-shaped problems with multiple possible doors in.
+
+```
+                        Outcome
+                  (measurable target)
+                          |
+        +-----------------+------------------+
+        |                 |                  |
+   Opportunity A     Opportunity B      Opportunity C
+   (customer pain)   (customer pain)   (customer pain)
+        |                 |                  |
+   +----+----+       +----+----+       +-----+
+   |    |    |       |    |    |       |     |
+  Sol  Sol  Sol     Sol  Sol  Sol     Sol   Sol
+   |    |    |       |    |    |       |     |
+  AT   AT   AT      AT   AT   AT      AT    AT
+       (assumption tests)
+```
+
+**Discipline:**
+- Outcome is **measurable** (e.g., "increase activation by 20%"), not an output ("ship feature X").
+- Opportunities are **customer pain points** that, if relieved, would move the outcome.
+- Decompose big opportunities into smaller, solvable ones. Smaller opportunities → smaller solutions → faster tests.
+- Each solution is broken into **assumption tests** — desirability ("will they want it?"), feasibility ("can we build it?"), viability ("does it make business sense?"), ethics. Most assumption tests run in 1–2 days; idea tests take weeks. **Test assumptions, not full ideas.**
+- The tree is *continuously updated* — the briefing captures a snapshot, not a final answer.
+
+When generating a briefing for an outcome-shaped problem, draw the tree (markdown nesting or a small mermaid diagram) and reference its branches in the Themes section.
+
+## 4. Risk classification — Marty Cagan's four
+
+Discovery exists to address four distinct risks before committing to a solution. Map every risk in the **Risks** section to one of these four buckets. If a risk doesn't map, it's probably an implementation detail (which is `@dev`'s problem, not `@briefing`'s).
+
+| Risk type | Question it answers | Owner to validate |
+|---|---|---|
+| **Value** | Will customers actually want it? Will they choose it over alternatives? | Product, user research |
+| **Usability** | Can they figure out how to use it? | Design, usability testing |
+| **Feasibility** | Can engineering build it given time, skills, tech, data? | Engineering |
+| **Viability** | Does it work for the business? Legal, ethics, P&L, brand, partnerships, support burden? | Stakeholders, ops, legal |
+
+**Always also ask:** *Risk of NOT doing it.* The cost of inaction is a forcing function — without it, "let's build everything" looks safe.
+
+**Anti-pattern:** "Risk: complexity." That's a feasibility hand-wave. Be specific: which dependency, which migration, which performance concern.
+
+## 5. Gap analysis discipline
+
+Every gap should be expressed as the **diff between current state and desired state** — and the diff should be measurable when possible.
+
+```markdown
+### Gap: Onboarding completion rate
+- Current state: 38% of signups complete the first task within 7 days (last 90 days).
+- Desired state: ≥ 60% within 7 days.
+- Delta: +22 pts.
+- Why this matters: aligns with the activation outcome (see Themes/Activation).
+```
+
+**Anti-patterns:**
+- "We don't have onboarding." (Too binary — what *is* there today?)
+- "Onboarding is bad." (Not measurable.)
+- "We need better onboarding." (That's a solution prefix, not a gap.)
+
+When the delta isn't directly measurable yet, name **what would have to be measured** before deciding ("we'd need to instrument event X to know").
+
+## 6. Open-questions taxonomy
+
+Every numbered open question must be classified by what kind of answer it needs:
+
+| Type | Resolution path | Owner |
+|---|---|---|
+| **Research-able** | Web search, data analysis, competitor scan in < 4 hours | `@orache` or `@sheldon`, or self |
+| **Testable** | An assumption validated by a 1–2 day experiment, prototype, or interview | Discovery experiment — design + product |
+| **Decision-required** | Judgment call between explicit alternatives — no more research will resolve it | Human decision-maker (founder, lead, stakeholder) |
+| **Out-of-scope** | Worth noting but not blocking | Park in a "later" section |
+
+**Format in the briefing:**
+```markdown
+1. [research-able] What's our weekly active user count for accounts older than 30 days?
+   - Owner: data team. Path: query analytics.
+2. [testable] Will a one-click share reduce time-to-second-export by ≥ 20%?
+   - Owner: design + dev. Path: prototype + 5-user test, 2 days.
+3. [decision-required] Do we ship with Slack-only or Slack+Teams at launch?
+   - Owner: founder. Path: trade-off doc, ship within 1 week.
+```
+
+**The 3-question quality gate:** if the briefing has more than 3 unclassified or vague open questions, it's not ready to be `approved`. Either classify them, or do another conversation pass to either resolve or scope-cut.
+
+## 7. Theme partitioning rules
+
+When a briefing has a complex problem space, partition into Themes. Each theme should:
+
+1. Have **one concern** (not "auth + billing"; pick one).
+2. Be **independently progressable** — could become its own briefing if scope expands.
+3. Have **its own** open questions, gaps, and risks reflecting that theme.
+4. Map to a single branch of an Opportunity Solution Tree if you've drawn one.
+
+**Heuristic:** if you can't name the theme without using "and", it's two themes.
+
+## 8. Conversation playbook (expanded)
+
+When in conversational mode (`plans/` empty or user wants to plan via chat), use this structure. Don't rush. Each topic gets a reflection ("So basically X is Y — is that right?") before advancing.
+
+### A — Context (the "why now?")
+> "Tell me about the context: what is the current situation, and **what changed recently** that made you think about this idea now? A trigger always exists."
+
+Follow-ups:
+- "What were you doing differently 3 months ago?"
+- "Who or what raised the issue first?"
+- "What broke or almost broke?"
+
+### B — Problem (JTBD framing)
+> "What specific pain point do you want to solve? For whom? What can't they accomplish today without working around it?"
+
+After the user answers, **try to convert their description into a JTBD statement and reflect**:
+> "Let me see if I got this: 'When [situation], I want to [motivation], so I can [outcome].' Is that right? What did I miss?"
+
+Watch for surface-level framings (file upload, settings page, dashboard) and probe for the underlying progress.
+
+### C — Proposed solution
+> "What direction are you considering? Multiple is fine — this is not a commitment yet, just hypotheses."
+
+Follow-ups:
+- "What's the cheapest version that would tell you if it works?"
+- "What would change if we did the opposite of what you're considering?"
+
+### D — Risks (Cagan's four + risk of inaction)
+> "Let's go through this in four passes:
+> 1. **Value** — will users actually want it?
+> 2. **Usability** — can they figure out how to use it?
+> 3. **Feasibility** — can we build it given what we know?
+> 4. **Viability** — does it work for the business (legal, ethics, P&L, support)?
+> And one more: **what's the cost if we don't do it?**"
+
+### E — Gaps (current vs desired state)
+> "What's still undefined that would need an answer before moving forward? For each thing, can we frame it as 'today we have X, we want Y, the delta is Z'?"
+
+### F — Open questions classification
+After the 5 topics, sweep all unresolved items and classify each:
+> "Of the questions still open, which are **research-able** (a few hours of digging), which are **testable** (1–2 day experiment), which are **decision-required** (someone has to choose), and which are **out-of-scope** (note but don't block)?"
+
+This is the gate before proposing a slug and writing the briefing.
+
+## 9. Switch interview script (when JTBD framing requires it)
+
+When the user has a real customer/user the agent can talk to (or the user is themselves the customer), use this script:
+
+1. **Reconstruct the timeline.** "Walk me through the day you switched / started using / decided you needed [thing]. What happened in the hours and days before?"
+2. **Identify the trigger.** "What was the specific moment that made you say 'I have to do something about this'?"
+3. **List alternatives considered.** "What else did you think about doing? What were you doing before?"
+4. **Surface anxieties.** "What worried you about switching? What almost stopped you?"
+5. **Capture decision criteria.** "How did you decide which option to go with? What made the final choice?"
+6. **Document first use.** "What was the first thing you did with [solution]? Did it work? How did it feel?"
+
+10–15 of these conversations are worth more than months of surveys. Each one takes 30–45 min.
+
+## 10. Reporting hooks
+
+In the briefing's frontmatter and Sources section, when a deep methodology was used:
+
+```markdown
+---
+slug: {slug}
+created_at: {ISO-date}
+updated_at: {ISO-date}
+source_plans: [...]
+methodology: opportunity-solution-tree | jtbd | cagan-discovery | switch-interview
+---
+
+## Sources
+- Switch interviews conducted: 7 (2026-04-30 to 2026-05-06)
+- Competitor scan: [Competitor A](url), [Competitor B](url)
+- Internal data: weekly_active_users.sql, churn_cohort_v3.sql
+- Market sizing: ARR estimate from public earnings reports + Crunchbase
+```
+
+## 11. References
+
+This document distills `researchs/oracle-briefing-craft-2026/summary.md`. See that file for the full source list and verdict.

package/template/.aioson/docs/dev/execution-discipline.md

@@ -0,0 +1,106 @@
+---
+description: "Dev execution discipline — semantic commits, learnings, task tracking, planning, atomic execution, verification gates, skeleton updates, and debugging."
+---
+
+# Dev Execution Discipline
+
+Load this module when the work is multi-file, ambiguous, near completion, or requires repeated verification.
+
+## Semantic commit format
+
+Use:
+
+- `feat(module): ...`
+- `fix(module): ...`
+- `refactor(module): ...`
+- `test(module): ...`
+- `docs(module): ...`
+- `chore(module): ...`
+
+## Session learnings
+
+At the end of productive sessions, look for:
+
+- user corrections
+- repeated successful patterns
+- new domain facts
+- quality failures or bugs
+
+Capture only the top 3 to 5 concise learnings in `spec.md` under session learnings.
+
+## Working memory
+
+Use task tooling when available:
+
+- `TaskCreate` — create slices
+- `TaskUpdate (in_progress)` — mark in-progress
+- `TaskUpdate (completed)` — mark completed with a one-line summary
+- `TaskList` — review before starting new slices
+
+`dev-state.md` is the persistent human-readable summary, not the live task board.
+
+## Self-directed planning
+
+Before ambiguous or multi-file work:
+
+1. declare planning mode
+2. list touched files and why
+3. sequence the implementation
+4. define verification criteria
+5. exit planning mode before coding
+
+Single-file, obvious changes do not need a full planning pass.
+
+## Working rules
+
+- reuse skills before reinventing patterns
+- load detailed skills and docs on demand
+- decide the minimum context package before coding
+- stop if a recurring pattern already exists in `.aioson/skills/static/` or `.aioson/installed-skills/`
+
+## Atomic execution
+
+Work in small validated steps:
+
+1. declare the next step
+2. write the test first when business logic is new
+3. implement only that slice
+4. verify with the actual command output
+5. commit the working slice
+6. repeat
+
+Unexpected output means stop and investigate. Do not stack speculative fixes.
+
+## Done gate
+
+Before marking any task or feature done:
+
+1. run the verification command
+2. read the complete output
+3. confirm exit code `0`
+4. only then mark done
+
+Update `skeleton-system.md` whenever files are created, deleted, or materially changed.
+
+## `*update-skeleton`
+
+If the user types `*update-skeleton`, rewrite `.aioson/context/skeleton-system.md` to reflect:
+
+- file map status
+- module status
+- key routes
+- update date
+
+## Debugging
+
+If a failing issue survives one attempt:
+
+- stop random fixing
+- load `.aioson/skills/static/debugging-protocol.md`
+- follow the protocol from root-cause analysis onward
+
+After 3 failed attempts on the same issue, question the architecture instead of pushing patches blindly.
+
+## Git worktrees
+
+For SMALL or MEDIUM work, consider `.aioson/skills/static/git-worktrees.md` if the user wants a cleaner parallel workflow.

package/template/.aioson/docs/dev/stack-conventions.md

@@ -0,0 +1,83 @@
+---
+description: "Dev stack conventions — Laravel, UI/UX, design skill, motion, Web3, and any-stack separation rules."
+---
+
+# Dev Stack Conventions
+
+Load this module when the active task touches framework-specific implementation details or user-facing UI.
+
+## Laravel conventions
+
+Respect this layout:
+
+- `app/Actions/`
+- `app/Http/Controllers/`
+- `app/Http/Requests/`
+- `app/Models/`
+- `app/Policies/`
+- `app/Events/` + `app/Listeners/`
+- `app/Jobs/`
+- `app/Livewire/`
+- `resources/views/<resource>/`
+
+Rules:
+
+- controllers orchestrate; they do not own business logic
+- use Form Requests for validation
+- use Policies for authorization
+- use Actions for business logic
+- use queued events/listeners for side effects
+- use Jobs for heavy processing
+- eager-load to avoid N+1 queries
+- implement `down()` in every migration
+
+## UI / UX conventions
+
+- use the project's component library when it exists
+- do not reinvent standard controls
+- mobile-responsive by default
+- always implement loading, empty, and error states
+- always provide visual feedback
+
+## Design skill conventions
+
+Read `design_skill` from `project.context.md` before implementing user-facing UI.
+
+If `design_skill` is set:
+
+- load `.aioson/skills/design/{design_skill}/SKILL.md`
+- load only the references needed for the current screen or component
+- treat it as the only active visual system
+
+If `design_skill` is blank and the task clearly depends on visual direction:
+
+- stop and ask whether to route through `@ux-ui` or proceed explicitly without a registered design skill
+
+## Motion and animation
+
+When the framework is React or Next.js and motion is relevant:
+
+- load `.aioson/skills/static/react-motion-patterns.md`
+- prefer Framer Motion
+- provide `prefers-reduced-motion` fallback
+- do not add heavy motion to admin/CRUD interfaces without a clear reason
+
+## Web3 conventions
+
+For `project_type=dapp`:
+
+- validate inputs on-chain and off-chain
+- never trust client-provided values for sensitive contract calls
+- use typed ABIs
+- test contract interactions before UI wiring
+- document gas implications for user-facing transactions
+
+## Any-stack conventions
+
+For stacks without a dedicated section:
+
+- separate business logic from request handlers
+- validate input at the boundary
+- follow the framework's conventions first
+- check `.aioson/skills/static/`, `.aioson/skills/dynamic/`, and `.aioson/skills/design/` before inventing patterns
+- document deviations in `architecture.md` when needed

package/template/.aioson/docs/deyvin/continuity-recovery.md

@@ -0,0 +1,57 @@
+---
+description: "Deyvin continuity recovery — session start order, resumption rules, brownfield guardrails, SDD bridge, and Git fallback."
+---
+
+# Deyvin Continuity Recovery
+
+Load this module at the start of every `@deyvin` session before touching code.
+
+## Session start order
+
+Build context in this order:
+
+1. If `aioson` is available, run `aioson memory:summary . --last=5` as the fast continuity bootstrap
+2. Read `.aioson/context/project.context.md`
+3. Check `.aioson/rules/`; load universal rules and rules targeted at `deyvin`
+4. Check `.aioson/docs/`; load docs referenced by rules or relevant to the task
+5. If the task is specific, run `aioson context:pack . --agent=deyvin --goal="<task>"` and read the generated pack
+6. Read `.aioson/context/memory-index.md` if present
+7. Read `.aioson/context/spec-current.md` and `.aioson/context/spec-history.md` if present
+8. Read `.aioson/context/spec.md` if present
+9. Read `.aioson/context/features.md` if present; if a feature is in progress, also read `prd-{slug}.md`, `requirements-{slug}.md`, and `spec-{slug}.md`
+10. Read `.aioson/context/skeleton-system.md`, `discovery.md`, and `architecture.md` as needed
+11. When the task matches procedural tags, run `aioson brain:query . --tags=<tags> --min-quality=4`
+12. Inspect recent runtime state in `.aioson/runtime/aios.sqlite` when memory summary is insufficient
+13. Use Git only as a fallback after memory + runtime + rules/docs
+
+If the user asks what happened recently, answer from memory and runtime first. Go to Git only if those sources are insufficient.
+
+## SDD bridge
+
+When continuation depends on spec or execution state:
+
+1. Load `.aioson/skills/process/aioson-spec-driven/SKILL.md`
+2. Then load only `references/deyvin.md`
+3. Follow that router to `maintenance-and-state.md` and `approval-gates.md` as needed
+4. Treat shared SDD references as read-only process sources used by multiple agents
+
+Do not duplicate or rewrite the shared SDD references inside `@deyvin`.
+
+## Brownfield guardrails
+
+If `framework_installed=true` in `project.context.md` and the task depends on existing system behavior:
+
+- prefer `discovery.md` + `spec.md` as the primary memory pair
+- use `skeleton-system.md` or `memory-index.md` first for faster orientation
+- if `discovery.md` is missing but scan artifacts exist, stop and hand off to `@analyst`
+- if broad architecture decisions are required, hand off to `@architect`
+
+## Git fallback
+
+Git is a fallback, not your first source of truth.
+
+Use Git only when:
+
+- AIOSON memory does not explain recent work well enough
+- runtime data is missing or too shallow
+- the user explicitly asks for commit-level history

package/template/.aioson/docs/deyvin/debugging-escalation.md

@@ -0,0 +1,30 @@
+---
+description: "Deyvin debugging and escalation — root-cause protocol, retry limits, and when to hand off."
+---
+
+# Deyvin Debugging and Escalation
+
+Load this module when the request is bug diagnosis, failing test repair, or when the first fix attempt fails.
+
+## Debugging protocol
+
+When a bug or failing test cannot be resolved in one attempt:
+
+1. STOP trying random fixes
+2. Load `.aioson/skills/static/debugging-protocol.md`
+3. Follow the protocol from step 1 (root cause investigation)
+
+## Retry threshold
+
+After 3 failed fix attempts on the same issue:
+
+- question the architecture, not the code
+- decide whether the issue still fits pair mode
+- hand off when structural redesign, broader planning, or formal QA is needed
+
+## Escalation hints
+
+- `@dev` -> larger structured implementation batch once root cause is known
+- `@architect` -> structural or system-level flaw
+- `@analyst` -> missing domain rules or unclear brownfield behavior
+- `@qa` -> formal risk review, regression sweep, or broader test design

package/template/.aioson/docs/deyvin/pair-execution.md

@@ -0,0 +1,44 @@
+---
+description: "Deyvin pair execution — working mode, small-slice loop, memory updates, and implementation governance."
+---
+
+# Deyvin Pair Execution
+
+Load this module when `@deyvin` is about to inspect, explain, fix, or implement a small continuity slice.
+
+## Pair working style
+
+- summarize the latest confirmed context first
+- ask what the user wants to do now if the next step is unclear
+- propose the smallest sensible next step
+- implement, inspect, or fix one small batch at a time
+- validate before moving on
+
+## Implementation governance
+
+Before changing code:
+
+1. load the relevant project rules and docs already discovered during recovery
+2. if `.aioson/design-docs/` contains implementation governance docs, load the relevant ones for the touched area
+3. if a recurring pattern already exists in `.aioson/skills/static/` or `.aioson/installed-skills/`, reuse it instead of improvising
+
+## Small-slice loop
+
+Work in this order:
+
+1. define the immediate slice
+2. inspect the relevant files and runtime context
+3. implement only that slice
+4. verify with the real command or observable behavior
+5. summarize what changed
+6. decide whether the next slice still fits pair mode
+
+If the work stops being small, validated, and reviewable, hand off.
+
+## Memory update rules
+
+- update `spec.md` when the session changes project-wide engineering knowledge, decisions, or current state
+- in feature mode, update `spec-{slug}.md` for feature-specific progress and decisions
+- treat `spec-current.md` and `spec-history.md` as read-optimized derivatives; prefer updating `spec.md` / `spec-{slug}.md`
+- update `skeleton-system.md` when files, routes, or module status change materially
+- if the task becomes broad and context starts to sprawl, suggest or regenerate `context:pack`

package/template/.aioson/docs/deyvin/runtime-handoffs.md

@@ -0,0 +1,36 @@
+---
+description: "Deyvin runtime and handoffs — tracked session behavior, live milestones, direct sessions, and dashboard visibility."
+---
+
+# Deyvin Runtime and Handoffs
+
+Load this module when the session is tracked or when the user asks about runtime visibility.
+
+## Runtime principle
+
+The AIOSON execution gateway records tasks, runs, and events in the project runtime automatically. Focus on accurate step summaries, clean handoffs, and updated memory.
+
+## Live-session behavior
+
+If the user entered through `aioson live:start`, do not open a parallel `runtime:session:*` session. Reuse the live session and emit compact milestones instead:
+
+1. When clearly starting a new user-visible slice, run `aioson runtime:emit . --agent=deyvin --type=task_started --title="<short slice title>"`
+2. After each completed user-visible task, run `aioson runtime:emit . --agent=deyvin --type=task_completed --summary="<what was just completed>" --refs="<files>"`
+3. When the session is linked to a plan and you complete a named step, run `aioson runtime:emit . --agent=deyvin --type=plan_checkpoint --plan-step="<step-id>" --summary="<what was completed>"`
+4. For meaningful progress or risk, run `aioson runtime:emit . --agent=deyvin --type=milestone|correction|block --summary="<what changed>"`
+5. If the request clearly belongs to another AIOSON agent, hand the same live session over with `aioson live:handoff . --agent=deyvin --to=<next-agent> --reason="<why the handoff is needed>"`
+6. If the user wants to monitor the session in another terminal, recommend `aioson live:status . --agent=deyvin --watch=2`
+7. Let the session owner close it with `aioson live:close . --agent=<active-agent> --summary="<one-line summary>"`
+
+## Direct-session behavior
+
+If the user did not enter through `aioson live:start`, keep one direct session open while the pair session is active:
+
+1. At session start or when resuming work, run `aioson runtime:session:start . --agent=deyvin --title="<current focus>"`
+2. After each completed user-visible task, run `aioson runtime:session:log . --agent=deyvin --message="<what was just completed>"`
+3. On handoff, explicit pause, or session end, run `aioson runtime:session:finish . --agent=deyvin --summary="<one-line summary>"`
+4. If the user wants to monitor the session in another terminal, recommend `aioson runtime:session:status . --agent=deyvin --watch=2`
+
+## Dashboard visibility
+
+Plain natural-language agent activation in an external client does not create runtime records by itself. If the user wants tracked dashboard visibility, they must enter through `aioson workflow:next`, `aioson agent:prompt`, or `aioson live:start` first.