Skip to content

feat: let any crewmate guide users to the control on their screen - #18301

Merged
buluoray merged 1 commit into
feat/mate-first-crewmatefrom
feat/guide-platform
Oct 9, 2026
Merged

buluoray merged 1 commit into
feat/mate-first-crewmatefrom
feat/guide-platform

Conversation

@buluoray

@buluoray buluoray commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let any crewmate answer "where is X?" and "how do I do Y?" about Kiro Crew by pointing at the real control on the user's screen, with every click still the user's.

Today a crewmate asked "where do I turn on the terminal?" can only describe the dashboard from memory or tell the user to search Settings and the docs. It cannot see where a control lives on this build or show it on the live page, where the control is often behind a collapsed sidebar, a closed menu or a phone layout. The decision is recorded in docs/request-for-change/rfc-crewmate-guides-and-mate.md (accepted, merged in #18326). This is the second of three PRs that ship it: Mate (#18406, the base of this PR), then guided tours (this one), then change cards.

Why it matters

The long tail of Kiro Crew settings is where people get stuck, new and existing users alike. A crewmate that finds the exact control and walks the user to it on their own screen turns a docs search into a one-message request.

Not a goal

  • Changing anything for the user. A guide only highlights and explains; every click is the user's, and prepared changes are the next PR.
  • A path around approvals, governance or the security policy. Trust-root controls (security policy, approvals, the approval-mode picker, a crewmate's permission picker, computer use, secrets) get no guide and are answered in words.
  • Letting the model drive the page or send a route, selector or markup.
  • Changing where a new user lands on first open.

What changed (motivation → approach → change)

Approach: extend the kirocrew-guide server from #18406 with tools that can only read or offer. Pointing at the UI uses an index generated from the dashboard source and the live page, not a remembered map; the gateway owns every guide's state.

  • Tools (src/kiro_crew/mcp_guide.py): find_ui (search or browse the location index, labels in the user's dashboard language), search_docs (packaged user docs), guide_list_actions / guide_start / guide_status / guide_cancel. Trust-root and caution rules travel in each tool's text and each result's next line. All seven tools are exact allowedTools grants (agent._GUIDE_AUTO_GRANTS, config/defaults.json), through the governance ceiling.
  • Location index (ui_index.py, website/scripts/gen-ui-index.mjs, website/src/uiLocations): curated plus auto-stamped controls in 12 languages, generated into src/kiro_crew/docs/ui-index.generated.json and guidePlans.gen.ts; CI checks it is current. GUIDE_DENY_IDS marks the approval-mode picker and a crewmate's permission picker deny.
  • Guide runs (guide_catalog.py, dashboard/guide_runs.py, dashboard/guide_observe.py, dashboard/handlers/guide.py): registered actions (settings.show, crewmate.create, mcp.open_add, ui.show, ui.find), claim/progress/lease per tab, reveal, select and gate steps, viewport re-planning, and a bounded live observation of one tab. Starting a guide uses feat: welcome users with Mate, a first crewmate they get to name #18406's admission: only a turn the user sent from the dashboard.
  • Dashboard (website/src/guide, GuideLayer.tsx, GuideOfferCard.tsx): the offer is a card in the chat; after Start, the layer opens the page and outlines the control beside a step panel, and a press on the target finishes the step. Each offer is a card row of the conversation (dashboard/chat_cards.py, cards/ConversationCard.tsx) and a guide/* crew-log entry, so it stays where it was offered across a reload.
  • Crewmates page (MembersPage.tsx, MeetCrewmatesFlow.tsx): New crewmate and a crewmate's create link open the embedded flow in place of the chat; Advanced opens the full form.

Smaller pieces: crew_log/emit.py, crew_log/entry_types.py, crew_log/schema.py and history_projection.py add the guide/* entries and the display-only card role; chat_runner.py reads past a card row; security_posture.py lists the guide-row redaction sink and the gate-side catalog; validation.py holds the argument schemas; dashboard/server.py, server_runtime/mcp_routes.py, dashboard/state.py, chat_handlers.py, ws_event_scope.py and agent_admin/crew_records.py wire the routes, the sending tab and the crewmate-create hook; src/kiro_crew/apps and website/src/apps mark delete buttons guideCaution; website/src/api, website/src/store, website/src/hooks, website/src/components, website/src/shell, website/src/surfaces, website/src/lib, website/src/pages, website/src/app-sdk, App.tsx and vite-env.d.ts carry the markers and wiring; src/kiro_crew/agent.py and src/kiro_crew/agent_materialization (service agents) grant the new tools and keep them off background agents; website/src/i18n holds the strings; .github, .gitignore and src/kiro_crew/builtin_skills run the index check; src/kiro_crew/docs and docs/ cover MCP, crew log, crew mode, history, config and the feature map; test/gui_user adds scenarios.

Backwards compatibility

Compatible: agents that do not mount the server behave as before, and the new routes refuse callers they cannot attribute to a dashboard turn; they accept nothing main accepted before.

Reader: website/src/pages/members/MembersPage.tsx:meet_crewmates -- crew page -- the empty-roster Meet CrewMates button and its locale keys are removed; the empty state's New crewmate hero opens the same flow (MembersPage.test.tsx)

Tests

  • Backend: test_find_ui*.py, test_guide_*.py (routes, runs, observation, reveal/select/gate steps, re-plan, the approval-mode and permission pickers never guided), test_guide_admission.py (real admission for start and reads: channel turns and non-user turns refused, reads still answer), test_guide_server.py (mount, per-tool grants, off-dashboard wording, offer hints), test_search_docs.py, plus updated composition, spec-byte, crew-log and MCP contracts.
  • Frontend: src/guide/*.test.tsx, src/uiLocations/*.test.ts, cards/ConversationCard.test.tsx, ChatPane.cardColumn.test.tsx, TurnBlock.cardRow.test.tsx, chatSlice.cardRow.test.ts, MeetCrewmatesFlow.test.tsx, Members page cases.
  • Mutation checks from the earlier rounds still hold: removing the channel-origin or not_user_turn check, the trust-root route check or a GUIDE_DENY_IDS entry reddens a named test.
  • Test volume: the change-card tests moved to the next PR, and the overlapping admission and server tests were merged into one file each.

Manual verification

Earlier heads, live on a preview gateway with real model turns: "where do I change the theme?" → find_ui + guide_start, and Start opened Settings → Display and outlined Theme; "How do I delete a schedule myself? Show me." → a two-step guide ending on the outlined Delete with its caution line, nothing deleted; at 390px the card and step render as a bottom sheet. Gates on this head: black, subprocess-encoding, isort, flake8, mypy, docs-lint, harness parity, tsc, npm run build (with the index check), i18n against origin/main, eslint on changed files; related pytest (about 18.8k tests; the only reds, test_agent_template_skills.py reorder cases, also fail on origin/main on this host) and vitest (881 targeted; the wider run's other reds also fail on the #18406 branch on this host). Not exercised: Windows and macOS hosts.

Screenshots / video

All frames from an earlier head of this branch.

a-guide-card

b-guide-outline-popover

c-multistep-1-select-row

c-multistep-2-delete-step

e-phone-guide-card

e-phone-guide-step

Related Issues

Closes #18300

Part of the RFC in #18326; based on #18406 (Mate); followed by a change-cards PR.

Pattern harvest

Not generalizable: a feature PR.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners October 9, 2026 02:18
@buluoray
buluoray requested a review from chenmingwei23 October 9, 2026 02:18
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/security_posture.py

  • No reasoning template for 40c156a yet.

How to clear this check:

  1. The PR author posts the template below as a PR comment, with
    every field filled (N/A needs a reason). Keep the
    Head commit line: it must name the current head SHA.
  2. The check turns green within a minute, with no push.
  3. A new push resets this check: post it again for the new head.

Only the author's comment counts this way. A reviewer can instead
paste the filled template into an "Approve" review on this head.
Merging still needs a reviewer's approval.

## Sensitive change review
- Head commit: 40c156a2a96bcbbc34ef1b7673191a10c640348b
- What rule changed:
- Before -> after (what was allowed/blocked, now):
- Worst case if wrong (breaks commands / leaks secret / locks user out):
- Evidence checked (which sandbox result proves it):
- No regression:
  - Tools still work (which tools/commands were run, result):
  - Backward compatible (old config / old data / old callers still work, how checked):
  - Existing tests (which suites passed on this head):
- How to undo:

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging 40c156a2a96bcbbc34ef1b7673191a10c640348b. Adjudication upheld 2 of 2 blocking finding(s); those must be resolved before merging.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/guide_catalog.py:832 -- Load guide catalogs off the gateway event loop

payload = json.loads(_UI_INDEX_PATH.read_text(encoding="utf-8"))
First valid ui.show request → api_guide_agent_start → start_superseding → validate_actions reads and parses the 697 KB index in both ui_show_plans and ui_build_manifest, blocking chat and heartbeat tasks during those operations; caching does not protect first use.
Anchor: no-blocking-call-on-event-loop
Fix: Load the required catalogs off-loop before the loop-owned guide mutation, and do the same before observation validation.

BLOCKING -- docs/feature-map/README.md:412 -- Preserve the active automatic first-run flow in the feature map

no fullscreen chapter, no auto-open / crewmates_onboarded ... no longer gates anything
Completed onboarding with an unseen crewmate flow and no pending Mate welcome → first Crewmates-page visit → the shell’s useMeetCrewmatesGate({ explicit: false }) retains automatic entry → FirstRunChapters opens the modal flow, contradicting this row; crewmatesOnboarded also still gates the tour-end trigger.
Anchor: feature-map-correctness
Fix: Describe explicit embedded creation alongside the retained automatic modal flow and its onboarding gates.

[BLOCK-MERGE] 40c156a
[GPT-REVIEWED] 40c156a

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1: Both the file and the rule check out. src/kiro_crew/guide_catalog.py:832 does a synchronous read_text plus json.loads inside ui_show_plans. The _CachedOnSources cache (:175-181) only helps after the first call, so the first call still blocks. The finding cites no-blocking-call-on-event-loop, which is marked blocking: true in .review-base-rules/AUTOSDE.yaml:102-103. That flag overrides any harm-versus-cost weighing.

F2: Both the file and the rule check out. The Meet CrewMates row at docs/feature-map/README.md:412 says "no fullscreen chapter, no auto-open". The finding cites feature-map-correctness, which is marked blocking: true in .review-base-rules/AUTOSDE.yaml:12-13. That flag overrides the weighing, and the fix is a one-line docs edit.

[ADJUDICATION] 40c156a2a96bcbbc34ef1b7673191a10c640348b total=2 uphold=2 downgrade=0
UPHOLD F1 src/kiro_crew/guide_catalog.py:832 reason=autosde-blocking-rule
UPHOLD F2 docs/feature-map/README.md:412 reason=autosde-blocking-rule
[GPT-ADJUDICATED] 40c156a2a96bcbbc34ef1b7673191a10c640348b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 40c156a2a96bcbbc34ef1b7673191a10c640348b: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 40c156a2a96bcbbc34ef1b7673191a10c640348b — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The Crewmates page rework replaces what New crewmate opens and removes the on-demand Meet CrewMates entry. That is outside the Goal, and the RFC doesn't cover it.

Not justified as shipped

  • Item 6 — oversized: the Goal is "pointing at the real control… every click still the user's". This item instead changes what the header "+" New crewmate and the empty-roster hero open: they now open the embedded MeetCrewmatesFlow in place of the chat, and the form moves behind a new Advanced link. The accepted RFC's Part 1 doesn't mention this. A guide can point at the existing NewCrewmateDialog without it.
    Subtraction: keep New crewmate opening NewCrewmateDialog. Drop openGuided and the hero's crewmate-empty-advanced link, and point crewmate.create at the existing form.
    Clears when: the rewiring is removed, or a human amends the Goal.
  • Item 7 — inherited: this removes the empty-roster Meet CrewMates button and its hint keys. The RFC's own amendment says "The on-demand entry and the explicit create path stay."
    Subtraction: restore meet_crewmates in MembersPage.tsx.
    Clears when: the button is restored, or an RFC on the base records its removal.
  • Item 8 — oversized: CREATED_RECEIPTS_KEY adds a sessionStorage record of crewmate-created receipts. It is new persisted state that no guide behaviour needs.
    Subtraction: delete readCreatedReceipts, writeCreatedReceipts and createdReceipts.
    Clears when: they are removed, or a human amends the Goal.

What this change ships

Inventory (10 items) — 7 justified

Intent: let a crewmate show a user where a Kiro Crew control is on their own screen. ADDITION.

  1. Crewmates can search a generated index of dashboard controls (find_ui) — justified
  2. Crewmates can search the packaged user docs (search_docs) — justified
  3. A guide offer card appears in chat; Start opens the page and outlines the control — justified
  4. Guides hold back on trust-root controls (approval mode, crewmate permissions) — justified
  5. Only a dashboard turn the user sent can start a guide — justified
  6. New crewmate opens the guided flow in place of the chat; the form moves behind Advanced — oversized
  7. The empty-roster Meet CrewMates button is removed — inherited
  8. Created-crewmate receipts persist per tab in sessionStorage — oversized
  9. Guide offers persist as card rows and guide/* crew-log entries across a reload — justified
  10. CI fails when the generated UI index is out of date — justified

[FIRST-PRINCIPLES-REVIEWED] 40c156a

Description read

[DESCRIPTION-READ] 74efb9138088993f496b9b527355fef545c1d2d69be7c7bd3a6a8ed3a2c34ae9

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

const key = prefix ? `${prefix}.${k}` : k
if (typeof v === 'string') {
if (v.includes('{{')) {
const parts = v.replace(TAG_RE, '').split(/\{\{[^}]*\}\}/).map(noSpace)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rebutted: not an HTML sanitizer.

flatten in findTargetPolicy.ts reads the packaged translation catalog and strips <Trans> tags only to derive comparison parts for templateMatches. Those parts are used by startsWith / endsWith / indexOf to resolve catalog keys and are never inserted into the DOM, so a residual <script fragment stays comparison data. Rendering of untrusted content goes through untrustedContent.ts (DOMParser, no HTML assignment) and DOMPurify.

Comment thread src/kiro_crew/guide_catalog.py Fixed
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 9, 2026
buluoray added a commit that referenced this pull request Oct 9, 2026
Record the product owner's 2026-10-08 decision, taken after the team
review, so the First Principles lane can read it from the base branch
when #18301 and #18317 change default mounts and first-visit landing.

Part 1: one read-or-offer MCP server, kirocrew-guide, mounted for the
kirocrew template, its crewmates, worker and dashboard sessions. Guides
highlight the real control and change cards apply only on the user's
press, from a dashboard turn the user sent; trust-root areas are
answered in words only.

Part 2: Kiro Crew creates one ordinary crewmate, Mate, once. It opens
first on the Crewmates page while never chatted with, writes its own
welcome, and renames itself through rename_self. default stays the
shared fallback crew.

The document amends sections of rfc-crewmates-launch,
rfc-crewmate-greeting and rfc-crewmates-chatted-list rather than
editing those accepted documents. The index gains its row and audit
note.
@buluoray
buluoray force-pushed the feat/guide-platform branch from 3637e85 to 639dc8c Compare October 9, 2026 04:24
@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=eedbba1f4b42 Failed body capture bypasses whole-request JSON validation -- fixed

The manual owner route now returns 400 invalid_body on failed body capture before invoking any handler. test_failed_chunk_capture_never_forwards_valid_suffix exercises seventeen malformed 64 KiB chunks followed by valid JSON; the reverting mutation fails with HTTP 200 instead of 400. The parameterized HTTP regression covers malformed and oversized chunked bodies.
Fix commit: 639dc8c.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=734fcd7dc02b Replace wall-clock barriers and timestamp-separation sleeps -- fixed

GuideLayer uses virtual timer ticks and awaited query state, including a parked pending-read latch for the slow-response case. test_no_probe_writes_to_disk ages each file explicitly with os.utime. Probe cancellation waits for isProbing to clear; autouse fixtures own their patches. The 403 test now waits for the pending query error state before asserting no notice.
Fix commit: 639dc8c.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=6ca4bd63ab6e Remove prohibited HTML-assignment sinks -- fixed

stripGuideMarkers parses in an inert DOMParser document, removes reserved attributes, and reads serialization without assigning HTML. Registry fixtures use createElementNS/React and replaceChildren. strips guide markers without assigning HTML to an element spies on the forbidden setter; the settings-only marker case also reddens on the old implementation.
Fix commit: 639dc8c.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=f61793315788 Meet CrewMates automatic entry contradicts the accepted timing -- fixed

The first-run host again opens Meet CrewMates at tour completion or the first Crewmates visit, under the base eligibility gates. Its hook ignores explicit creation events, while the page-owned embedded hook ignores automatic entry. Restored tour-end and first-page tests redden when auto-open is removed; keeps automatic and explicit hosts disjoint pins the two hosts.
Fix commit: 639dc8c.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=45c3866637d3 Meet CrewMates auto-open removed -- fixed

The removed first-run host is restored alongside the embedded explicit-open page path. The frozen Not-a-goal remains unchanged, and the description no longer claims automatic entry was removed. The restored hook tests exercise both automatic triggers and a workspace that already saw the flow.
Fix commit: 639dc8c.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 9, 2026
@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=ac129e1db692 Dismissal must persist crewmates_onboarded -- fixed

Both onDone outcomes persist the seen flag again; closing remains immediate and a failed write stays visible at the next entry. a persist refused at exit still closes at once; the refusal is shown on the next entry, until a write succeeds reddens when the completed-only condition is restored.
Fix commit: 639dc8c.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 9, 2026
@buluoray
buluoray enabled auto-merge (squash) October 9, 2026 05:28
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 9, 2026
@buluoray
buluoray force-pushed the feat/guide-platform branch from 357d004 to 8eb25f3 Compare October 9, 2026 07:04
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 9, 2026
@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=33c13c9a89f9 is_assistant_member matches on the key alone -- rebutted

The UI uses the key only for a label fallback and the first-visit landing; a user's own row under mate keeps its own display name and never owes a welcome (the welcome needs the marker only the first-crewmate step writes, test_welcome_owed.py), and its memory binding is left alone (first_crewmate_was_created gate, test_assistant_agent.py). Carrying the marker to the browser would add an API field for a case with no loss beyond a one-time landing; not proportional here.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=859cce2c1c66 Mate is visible even with the preview off -- fixed in 8eb25f3

With the Crewmates preview off, hideMateWithoutPreview (lib/assistantMember.ts) drops Mate from every list that offers crew records: the pickers fed by useAgents (choices, agents, displayAgents), Customize (KiroCrewAgentsPage) and a template's crew list. useAgents.hideMate.test.tsx pins both states and reddens when the filter is removed. Live check on this head: the chat agent picker lists no Mate with the preview off. Mate is still created in the background, as the RFC records.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=0b893f810aa2 Walkthrough aborts waiting for a nonexistent welcome card -- fixed in 8eb25f3

website/scripts/verify-crewmate-assistant.mjs was a stale manual walkthrough for the removed static welcome card; nothing references it (no package script, workflow or doc). It is deleted. The live Mate flow is evidenced by a real preview-gateway run on this head (PR body, Manual verification).

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=7b2f6ae2e8b9 Mate appears with the Crewmates preview off -- fixed in 8eb25f3

The agent pickers, Customize and a template's crew list leave Mate out while the preview is off (hideMateWithoutPreview, pinned by useAgents.hideMate.test.tsx); the new screenshot shows the chat agent picker on this head with no Mate. The remaining case in shot-06 is a hand-typed /members URL, which follows main's ordinary landing (the route is not preview-gated on main either); the owner chose to keep that as on main.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=8c7abd769f17 Two names after a rename -- fixed in 8eb25f3

The kickoff asks the renaming reply to say plainly that Mate goes by the new name from then on (pinned in test_mates_first_welcome_asks_for_a_name_for_mate). Live on this head the reply to "Call you Pebble" is "I'm Pebble now." under the Pebble header; the earlier welcome bubble stays as history.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=9f1a172599c5 Mate's welcome asks for the wrong name -- fixed in 8eb25f3

The frame the lane read came from an older head. The kickoff (FIRST_WELCOME) asks only what the user would like to call Mate and never the user's own name (test_mates_first_welcome_asks_for_a_name_for_mate). Live on this head the welcome ends "What would you like to call me?" (new screenshot).

@buluoray
buluoray force-pushed the feat/guide-platform branch from 8eb25f3 to a038c93 Compare October 9, 2026 07:19
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 9, 2026
A crewmate asked "where is X?" or "how do I do Y?" about Kiro Crew can
now answer from the dashboard itself instead of from memory. The
kirocrew-guide server gains find_ui (a search over a location index
generated from the dashboard source, in 12 languages), search_docs
(the packaged user docs) and guide_start / guide_status / guide_cancel.

A guide is an offer card in the chat. Nothing moves until the user
presses Start; then the dashboard opens the page and outlines the real
control, step by step, and every click is the user's. Only a turn the
user sent from the dashboard may offer one. Trust-root controls (the
security policy, approvals, the approval-mode picker, a crewmate's
permission picker, computer use, secrets) get no guide and are answered
in words.

Each offer is also a card row of the conversation and a guide/* entry
in the crew log, so it stays where it was offered across a reload.
@buluoray
buluoray force-pushed the feat/guide-platform branch from a038c93 to 40c156a Compare October 9, 2026 10:13
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 9, 2026
@buluoray buluoray changed the title feat: guide users with any crewmate and welcome them with Mate feat: let any crewmate guide users to the control on their screen Oct 9, 2026
@buluoray
buluoray changed the base branch from main to feat/mate-first-crewmate October 9, 2026 10:16
@buluoray
buluoray merged commit ed5b74c into feat/mate-first-crewmate Oct 9, 2026
55 of 66 checks passed
@buluoray
buluoray deleted the feat/guide-platform branch October 9, 2026 10:16
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 9, 2026
@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author

Scope change, at the owner's request (@buluoray): this PR is now split into three, merged in order.

  1. feat: welcome users with Mate, a first crewmate they get to name #18406: Mate, plus the kirocrew-guide server base (registration, one-time grant, dashboard-turn admission) and rename_self.
  2. This PR, based on feat: welcome users with Mate, a first crewmate they get to name #18406: guided tours only (find_ui, search_docs, guide_*, the location index, the guide layer). The Goal, Why and Not-a-goal sections were rewritten for that scope.
  3. A follow-up change-cards PR based on this one: propose_change and the card kinds, find_setting, diagnose_settings, get_member_capabilities.

The change-card code and its tests moved out of this diff; the card row in the conversation stays, because a guide offer is drawn the same way.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author

This PR was merged into feat/mate-first-crewmate by its earlier auto-merge as soon as its base was switched to that branch, which folded guides into the Mate PR. To keep the order the owner asked for (Mate first, then guides, then cards), feat/mate-first-crewmate was restored to the Mate commit alone (the merged tree is kept on backup/mate-plus-guides-ed5b74c1d9 locally and is identical to the guides head), and the guides work continues in #18443 with no auto-merge. Change cards are #18448.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Welcome new users with Mate, a first crewmate they name Let any crewmate guide users to a control and propose changes as cards

2 participants