Repository navigation
2026 11 14 docs round
History. Done 2026-11-14, the docs round of the cleanup round. It turned the dated designs into a living spec and rewrote the docs around it. The designs moved from
specs/toplans/with their names unchanged and each has a History header pointing at the area that holds what it asked for. The spec isdocs/superpowers/specs/: Specification.md (the area index, ids, glossary and architecture) and fourteen area files of numbered requirements. README.md is the short advertisement, CONTRIBUTING.md holds the contributor rules, AGENTS.md holds what an agent needs, and the hand-written wiki pages are plain English for a user and link to the spec. The generated tool pages are untouched anddocs/saga/is frozen. The area map and the Drift section below are the record of how the areas were drawn and where a design and the code disagreed.
| Doc | Before | After |
|---|---|---|
docs/superpowers/specs/ |
12,327 lines of dated designs | 4,852 lines in 15 files, 790 numbered requirements (25 of them proposed) |
README.md |
430 | 174 |
CONTRIBUTING.md |
272 | 344 |
AGENTS.md |
1,498 | 86 |
| Hand-written wiki pages (ten) | 1,586 | 1,296 |
docs/notes/ (inputs to the generated pages) |
313 | 274 |
The ten pages are Home, Actions, Administration, Configuration, Deployment, Files, Flows,
Installing, Secrets and Workspaces. Before is origin/master; the specs' before is the designs
that moved to plans/. CONTRIBUTING grew because the rules that were scattered through README.md
and AGENTS.md live there now.
Fourteen areas. The plan named twelve (D2 to D13). D1 changed it:
- D2's workspaces area split in two:
session-settings.md(D2b) takes the settings cascade, which is three designs and 1,227 lines on its own. -
files.mdadded asworkspace-files.md(D10b): no area covered downloads, screenshots, kept files or signed links, and recordings are a file section, so they move here from capture. -
http-and-headers.mdrenamedsurfaces.md: it also holds the MCP surface, resources andshow, which are not HTTP. - The session monitor moves from the admin UI to workspaces and sessions: it is the browser's lifecycle, and the admin's live list is one of its readers.
-
package-restructuremoves from the plugin to surfaces (its "one way to answer a request") and to the README's architecture. -
actions.md,flows.md,secrets.mdandconfiguration.mdwere renamed, because a GitHub wiki page answers to its basename in any folder and any case, and those four would shadow the top-level pagesActions,Flows,SecretsandConfiguration.
Designs and plans are in docs/superpowers/plans/. Code paths are under kubed/selenium_flow/
unless they start with a top-level folder. Also lists designs whose main area is elsewhere.
- Designs:
2026-10-09-workspaces-rename-design,2026-10-09-workspaces-and-observability-design(the programme: R1 to R7, E1, E2),2026-10-09-session-monitor-design,2026-10-29-session-uris-design,2026-11-14-reopen-notice-keep-alive-design. Proposed, for D14:2026-11-13-multiplayer-sessions-design. - Plans:
2026-10-09-workspaces-rename,2026-10-09-workspaces-and-observability,2026-10-09-session-monitor,2026-10-29-session-uris,2026-11-14-reopen-notice-keep-alive. - Code:
workspace/workspaces.py,workspace/store.py,workspace/locks.py,workspace/calls.py,monitor/,mcp/resources.py,mcp/clients.py,names.py,core/browser.py(the Grid client). - Tests:
test_workspaces,test_workspace_monitor,test_monitor,test_monitor_events,test_locks,test_session_open,test_node_lost,test_grid_listing,test_grid_connections,test_resources,test_names,test_shutdown. - Wiki:
Workspaces,current_workspace,open_session,end_browser.
- Designs:
2026-10-26-session-capabilities-design,2026-10-27-session-touch-ups-design,2026-10-28-headless-design. - Plans: the three of the same names.
- Code:
workspace/settings.py,core/session_caps.py,core/defaults.py, the open path incore/browser.py. - Tests:
test_session_caps,test_browser_choice,test_script_timeout,test_untrusted_certificate,test_session_open(shared with D2). - Wiki:
open_session,notes/open_session.notes.md.
- Designs:
2026-10-04-oidc-groundwork-design,2026-10-09-admin-oidc-design. Also: the programme's E6 (ownership and per-surface roles), never built. - Plans:
2026-10-04-oidc-groundwork,2026-10-09-admin-oidc. - Code:
http/auth.py,principal.py,http/links.py,http/admin/signed.py, theauthandoidcsections ofconfig.py. - Tests:
test_auth,test_oidc_http,test_principal,test_config_oidc,jwks.py. - Wiki:
Administration(The token),Installing.
- Designs:
2026-09-16-package-restructure-design,2026-10-29-sf-headers-design,2026-11-12-x-workspace-alias-design,2026-10-04-show-design,2026-10-09-show-everything-design. Also:2026-10-29-session-uris-design(the URI schemes). - Plans: the five of the same names.
- Code:
core/capabilities.py,core/annotations.py,mcp/tools.py,routes.py,http/answer.py,spec/,mcp/mirror.py,mcp/show.py,mcp/apps.py,mcp/failures.py,mcp/completions.py,mcp/progress.py,errors.py,faults.py,http/slashes.py,http/access_log.py,openapi.yaml. - Tests:
test_surfaces,test_routes,test_openapi,test_http_answer,test_show,test_show_inventory,test_discoverability,test_errors,test_failures,test_goldenwithgolden/,test_tasks_contract. - Wiki:
Installing(the URL and headers),Actions, the generated tool pages.
- Designs:
2026-10-27-live-view-design,2026-10-27-live-control-design. - Plans: the two of the same names.
- Code:
live/,http/admin/live.py,mcp/control.py,mcp/waiting.py. - Tests:
test_live_audit,test_live_control,test_live_pages,test_live_rfb,test_live_tunnel,test_live_tunnels,test_admin_live,test_await_control,test_control_hosts,test_control_notice,test_paste. - Wiki:
Administration,await_control,notes/await_control.notes.md.
- Designs:
2026-10-02-optimal-shape-design,2026-11-13-click-matches-design. Also:2026-11-13-hash-routes-design(url=moves between screens). - Plans:
2026-10-02-optimal-shape,2026-11-13-click-matches. - Code:
core/actions.py,core/recipe.py,core/probe.py,core/pointer.py,core/keys.py,core/assertion.py,core/coerce.py,core/js.pywithjs/,core/guidance.py,core/cancel.py,urls.py. - Tests:
test_actions_contract,test_matches,test_probe,test_probe_js,test_pointer,test_assert,test_outline,test_coercion,test_js,test_js_behaviour,tests/js/,test_guidance,test_urls,test_unresolved_host. - Wiki:
Actions, the generated tool pages,notes/extract.notes.md.
- Designs:
2026-11-12-flow-sites-paths-design,2026-11-13-hash-routes-design. - Plans: the two of the same names.
- Code:
flows/(all but the files half ofstore.py). - Tests:
test_flows,test_flowapi,test_flowdoc,test_flowrun,test_flowshape,test_places,test_run_progress. - Wiki:
Flows,save_flow,run_flow,get_flow,list_flows,delete_flow,flow_schema.
- Designs:
2026-11-14-secret-scope-design(rulings 25 to 27 are in it). Also:2026-09-26-configuration-design(secrets in the config file). - Plans:
2026-11-14-secret-scope. - Code:
secrets.py,binding.py,redaction.py,flows/redact.py,workspace/scrub.py,workspace/origins.py,mcp/scrubbed.py,capture/masking.py. - Tests:
test_secrets,test_secret_scope,test_binding,test_redaction,test_scrub_coverage,test_config_secrets,test_admin_secrets. - Wiki:
Secrets,write,list_secrets.
- Designs:
2026-09-30-site-data-design. Also:2026-11-14-reopen-notice-keep-alive-design(what a reopen restores and says). - Plans:
2026-09-30-site-data. - Code:
site_data/,http/admin/site_data.py. - Tests:
test_site_data,test_site_data_restore,test_site_data_save,test_site_data_surface,test_site_data_views,test_site_data_workspaces,test_spare_tab,test_history,test_admin_site_data,site_data_fakes.py. - Wiki:
save_site_data,notes/save_site_data.notes.md,get_site_data,list_site_data.
- Designs:
2026-10-10-capture-design. Also: the programme's R8 to R11 and E3. - Plans:
2026-10-10-capture. - Code:
capture/,bidi/,http/admin/capture.py, the hint inworkspace/calls.py. - Tests:
test_capture_align,test_capture_hint,test_capture_masking,test_capture_merge,test_capture_open,test_capture_resources,test_capture_store,test_capture_views,test_bidi_channel,test_bidi_connection,test_monitor_capture,test_network_body,test_admin_capture,capture_events.py,bidi_fakes.py. - Wiki:
network_body,notes/network_body.notes.md,Actions(Console and network).
- Designs:
2026-10-08-recordings-design. The Hangar has no design here; its decisions are indocs/saga/Chapter_4_The_Hangar.md. - Plans:
2026-10-08-recordings,2026-09-24-the-hangar,2026-10-22-flows-panel-at-picked-row(its file media types). - Code: the files half of
flows/store.py,http/files.py,http/links.py,http/admin/files.py,recordings/,core/naming.py. - Tests:
test_files_and_admin,test_file_caller_order,test_file_folders,test_file_sections,test_file_surfaces,test_kept_files,test_screenshot_saving,test_recording_collector,test_recording_mounts,test_recording_mp4,test_recording_open,test_recording_store,test_recording_surfaces,test_admin_files. - Wiki:
Files,keep_file,notes/keep_file.notes.md,upload_file,list_files,list_downloads,list_screenshots,list_recordings,screenshot,notes/screenshot.notes.md,print.
- Designs:
2026-09-25-svelte-admin-ui-design. Also:2026-10-09-admin-oidc-design(the login view),2026-10-26-session-capabilities-design(the Session tab),2026-09-26-configuration-design(the Settings tab),2026-10-09-session-monitor-design(the live list). - Plans:
2026-09-25-svelte-admin-ui,2026-09-25-svelte-admin-ui-traceability,2026-09-24-the-hangar,2026-10-22-flows-panel-at-picked-row. - Code:
ui/src/,http/admin/__init__.py,http/admin/page.py,http/admin/workspaces.py,http/admin/flows.py, the app shell inmcp/apps.py. - Tests:
test_admin_routes,test_admin_events,test_admin_settings,test_admin_flows,test_ui_serving, the UI's own tests (ui/src/**/*.test.ts),tests/integration/test_admin_ui.py. - Wiki:
Administration.
- Designs:
2026-09-26-configuration-design. - Plans:
2026-09-26-configuration. - Code:
config.py,main.py, the Configuration page inscripts/generate_wiki.py. - Tests:
test_config_load,test_config_schema,test_config_wiring,test_main. - Wiki:
Configuration(generated),notes/Configuration.notes.md,Deployment.
- Designs:
2026-10-05-skills-extension-design,2026-11-12-plugin-agents-design(the file restored on this branch),2026-11-13-explorer-agent-design. - Plans: the three of the same names.
- Code:
mcp/skill.py,mcp/skill_extension.py,mcp/agents.py,mcp/prompts.py,mcp/frontmatter.py,plugin/. - Tests:
test_skill,test_skills_extension,test_agents_extension,test_explorer,test_prompts,test_packaging. - Wiki:
Installing(Claude Code).
- The architecture section of
specs/Specification.mddraws on2026-09-16-package-restructure-designand2026-10-02-optimal-shape-design, and is held bytest_boundaries. - Never built, so no area holds them yet: the programme's E4 (telemetry,
/metricsand traces) and E6 (ownership). Each is a candidate for (proposed) if Dr K wants it in the spec. - Tests that check docs and CI, for D15 and D17:
test_wiki,test_readme,test_pr_report.tests/bench/andtests/integration/(Grid-only) are read by whichever area they exercise.
Lines that named superpowers/specs/2026- before the move. All of them now point at the file in
plans/.
| File | Lines |
|---|---|
AGENTS.md |
6, and line 8 links the folder docs/superpowers/specs/ as the home of designs |
kubed/selenium_flow/monitor/__init__.py |
1 (module docstring) |
docs/saga/Chapter_4_The_Hangar.md |
2 (the saga is frozen) |
plans/2026-10-08-recordings.md, plans/2026-10-10-capture.md
|
4 each |
plans/2026-09-25-svelte-admin-ui.md, 2026-09-30-site-data.md, 2026-10-09-session-monitor.md, 2026-10-09-show-everything.md, 2026-10-09-workspaces-and-observability.md, 2026-10-28-headless.md
|
2 each |
| The other 22 plans | 1 each |
No test, script or sidebar reads these paths: tests/test_wiki.py checks only top-level pages
and basename clashes, scripts/generate_wiki.py reads docs/notes/, and _Sidebar.md does not
link superpowers/. Designs link each other by bare file name, which still resolves, since they
moved together.
Outside this repo, plugins/ultrapowers/commands/spec-draft.md in kubed-io/skills tells the spec
agent to write a draft design under docs/superpowers/specs/ (D17).
Where a design and the code disagree. The spec follows the code; a pair where the code looks wrong is flagged for Dr K. Every area has the same shape, in this order, and leaves out a part that is empty: Design says one thing, code does another, Designed, not found, In the code with no design, or stale in the design, Likely bugs, for Dr K, Wiki and comments to fix and, where a sibling spec exists, Differs from mcp-kb. An italic line under a heading is the heading the item was first written under.
Designs: plans/2026-10-09-workspaces-rename-design.md, 2026-10-09-workspaces-and-observability-design.md
(R1 to R7, E1, E2), 2026-10-09-session-monitor-design.md, 2026-10-29-session-uris-design.md,
2026-11-14-reopen-notice-keep-alive-design.md. The multiplayer design was not read (D14).
| Area | Design and ruling | The code | Flag for Dr K |
|---|---|---|---|
| WS | Rename, ruling 1: X-Session-Key and ?session= are refused with a 400 naming the new spelling |
Both are ignored: alone the request is unnamed, beside a name they drop out (test_a_session_name_is_no_name, sf-headers ruling 10). Spec: WS-4 |
No |
| WS | Rename, ruling 3: DATA_DIR/sessions/ moves to workspaces/ once |
Also leaves a flat-layout sessions folder (flows, files or screenshots directly in it) alone, as a workspace (flows/store._move_old_folder). Spec: WS-46 |
No |
| WS | Monitor, rulings 1 and 2, §1 and §4: monitor/bidi.py holds a BidiSocket; Watch.socket; socket_held
|
The connection is bidi.Connection in its own package; Watch.connection; Monitor.capturing asks whether capture is among the reasons heard. Spec: WS-33, the rest in capture.md |
No |
| WS | Monitor, ruling 8: call.finished is declared, not emitted; Monitor.touch at each host |
Calls.end publishes it once per call at every host, and Calls.begin/end touch through calling/called. Nothing subscribes to it. Spec: WS-28, WS-33 |
Yes, mildly: an event published to nobody until E4 exists |
| WS | Monitor, ruling 11: the record keeps nothing about what ended a session |
Workspace.ended = {"at", "by": "caller" | "admin"}, written by end_browser, cleared by the next bind; a reap writes nothing. Spec: WS-18 |
No |
| WS | Monitor, ruling 15 and §7: only owed sessions are watched, so a server with nothing owed asks the Grid nothing; consumers are the collector and the admin page | With session.keep_alive on (the default, 900) every open session owes keepalive, so the listing runs while any session is open. session.ended is also heard by the live tunnels and the secret scrub. Spec: WS-29, WS-36 |
No (the reopen design ruled it) |
| WS | Reopen, ruling 21: Grid.ping is sent once |
Grid._alive(..., retry=True) sends it again once when the pooled connection had been dropped by the Grid. Spec: WS-41 |
No |
| WS | Monitor, Next round: workspace://current's live asks Grid.is_alive
|
Still so, and Workspaces.browser (file listings, paste, hand-back) asks it too. GET /session/{id}/url is activity, so a reader polling the status keeps a browser alive past the keep-alive window. Spec: WS-43 |
Yes: see Likely bugs, 3 |
Likely bugs (not specced as intended behaviour)
-
A failed quit leaves the keep-alive pinging an orphan.
Workspaces.end_browserdetaches the record even whenGrid.quitraises (a Grid error other than 404), and then announces nothing, so the session's watch stays. With the keep-alive on, the monitor goes on pinging that browser for the rest of its window (up tosession.keep_alive, 15 minutes by default), holding a Grid slot for a browser no record names; a capture connection to it stays too. The racing loser thatWorkspaces.rememberfails to quit is in the same state. A fix:Monitor.release(id, "keepalive")(or every reason) after a failed quit. -
A reap can be called
lost.Workspaces._causejudges againstmax(grid_timeout, keep_alive)whether or not the keep-alive actually ran. When the watch was lost in a restart and no call came since, or every ping failed, the Grid reaps at its own timeout (300 s), and a call between 300 s and 900 s later is told the browser "ended while this workspace was in use". The design's Out of scope accepts the unkept session; the wording it then gets is the issue. -
Reading the status is activity.
workspace://current(andGET /browser) sendsGET /session/{id}/urlwhenever a session is attached. The MCP App's context view, or an agent that polls the status, keeps the browser alive indefinitely. The admin list avoids this withwindow_seen; the status could answerlivefrom the monitor's listing for a watched session, as the monitor design's Next round proposed.
Wiki notes for D16
-
Workspaces.mdrepeats the spec: the naming rules and their refusals (WS-1 to WS-4), the 200/500/404 liveness table (WS-19), the URI refusals paragraph (WS-45) and the "How long things last" table (WS-9, WS-35). -
Workspaces.md: "Nothing runs a cleanup loop, and nothing should" is out of date: the monitor's task pings kept browsers. -
Workspaces.md: the heading "A workspace is not a browser" is the writing skill's own example of a heading to rewrite ("Workspaces outlive browsers"). -
Workspaces.md: "you are never told 'your browser was taken'" reads against WS-22: a reopened browser's first result says it was replaced and why. -
current_workspace.md,open_session.mdandend_browser.mdare generated; nothing to note beyond whatWorkspaces.mdrepeats.
-
Header names. Capabilities design (rulings 10, 21 table) and touch-ups ruling 4 say
X-Browser,X-Version; code readsSf-Browser,Sf-Version,Sf-Window-Width/Height,Sf-Page-Load-Timeout,Sf-Script-Timeout(workspace/settings.pySETTINGS), and refuses theX-names (workspaces.OLD_HEADERS). The sf-headers design overtook it. SET-3. -
MCP
browseris case-sensitive.mcp/tools.pyBrowser = Literal[BROWSERS]with only_blank_is_unset;Firefoxis refused by the schema on MCP, whilenormalize_browseraccepts it on HTTP and in headers. Other enum arguments use_lowered. Minor inconsistency; SET-5 says the tool takes lowercase. -
settingsin the open result vsworkspace://current. Design says the result'ssettings"gains" version and capabilities and thatworkspace://currentshows "what is remembered". Code: the result'ssettingsis built inActions._set_up(measured width/height, true flags only); the record stores the resolved cascade (width as asked,falseflags kept). SET-45, SET-46. - Headless ruling 8 (window not capped by screen): withdrawn in the design, and not in the code or docstring. Not specced. Ruling 9 (error on a display-less node): never measured, no code. Designed, not found.
-
Capabilities ruling 12, "wait as long as the Grid does": code passes no timeout to
webdriver.Remote(Grid.open) and sets no default socket timeout. Whether Selenium's ownClientConfigdefault is unbounded was not checked (Selenium is not installed here). SET-36 says only that the open sets none. -
Touch-ups rulings 7, 8, 9, 10 and the pills of 15 (INSECURE row, CAPTURE
off,1400×1000, per-workspace fold, source pills): UI work inui/src; not read, left to admin-ui.md. The payload fields they need were checked (SET-47). -
Touch-ups ruling 5 puts "whether the Grid listing answered" "at the top level or on each
row"; code puts
grid_listedon each row (http/admin/workspaces.py). -
Unbounded values. Designs never state bounds; code has none for width, height or timeouts
(config
SessionSettingshas plainint | None). SET-4 records that. A width of 0 is stored but sets nothing (if width or height).
-
Insecure and saved site data (likely bug, for Dr K). Docstring and touch-ups ruling 6 say "an
insecure browser gets no saved site data". Code only skips the restore into an insecure browser
(
Actions._set_up,INSECURE_SKIP). Nothing refusessave_site_datafrom one, so a bad-cert sign-in can be saved and restored into the next normal browser. Capabilities ruling 23 gives the reason for the rule as "an insecure Firefox browser still got saved site data". Not specced beyond SET-26's restore.
-
Wiki repeats the spec.
open_session.mdis generated;notes/open_session.notes.mdrepeats the version/capabilities rules, the owned-key list and the 400/503 rule, and namesSf-Browsercorrectly. D16 to trim.
Designs: plans/2026-10-04-oidc-groundwork-design.md, plans/2026-10-09-admin-oidc-design.md.
Also: the programme's E6 (ownership and per-surface roles), never built, left out of the spec.
- Naming. Groundwork:
session://current, theX-Session-Keyheader, a "session" as the thing named. Code:workspace://current,Sf-Workspace. Spec: AUTH-19. In both History headers. - Groundwork non-goals ("no admin role from a JWT", admin API and admin UI token-only). Overtaken by the admin-OIDC design: the admin door admits an admin-UI JWT. Spec: AUTH-15, AUTH-16.
- JWKS refresh. Groundwork: cached an hour, refetch for an unknown
kidat most once a minute, both FastMCP's. Code: FastMCP's own floor is switched off (jwks_refresh_interval=0) andOidcVerifier._fetch_jwksis the one 60 second floor, with its own shielding and reuse of a good body. The one-hour cache is FastMCP's and is not in this repo, so the spec holds only the floor. Spec: AUTH-14. - Extra token checks. Groundwork lists signature,
iss,aud,exp, role. Code (verify_jwt) also refuses a token with no numericexp, and one whosenbfis not a number or is more than 60 seconds ahead. Spec: AUTH-11. - The principal's
opener()is not in the groundwork'sPrincipalsketch; the admin-OIDC design addsopened_by(ruling 11). Spec: AUTH-20. - Live view links. Neither design mentions links bound to a viewer (
by, 60 seconds exact) or the socket's 4401 close; they come from the live-view and live-control designs. Written in the spec fromlinks.sign(by=...)andhttp/admin/live.py. Spec: AUTH-30 to AUTH-32. - Admin-OIDC "Next round" lists "the principal in logs". Code: the principal's name reaches the
live view's audit lines (
audit.viewer_of) and nowhere else. Spec: AUTH-22.
- Groundwork "Documentation": README, AGENTS.md rules, CHANGELOG lines and the wiki's Configuration and Deployment text are outside this area's code; not checked.
- Groundwork "The cluster install" (gateway route, policy,
config.yaml,.mcp.json): lives in the cluster repo, not here. Not in the spec. - Groundwork "Settings:
oidc.*section description" foroidc.audienceand the table of env names: the config area's. The spec holds only the cross-field rules.
Likely bugs, flagged for Dr K
- Audit and control names collide.
audit.viewer_ofnames the tokenadminand an OIDC admin bypreferred_username. A Keycloak user calledadminoropentherefore has the same viewer name as the token holder or as an open server. The live view's control and its audit lines (live/control.pycontrolling(key, who)) are keyed by that string, so two different people are one controller and one name in the log. Both hold the admin door, so it is not an escalation, but the audit line cannot tell them apart. Not specced as a rule; AUTH-22 states what the code does. - Low:
http/admin/live.pyadmit: for an expired bound link the log line namesbyas given. It is safe because only a correct signature yieldsexpired, sobywas minted by this server. Noted because the other branch usessomeone.
Wiki repeats or contradicts the spec (D16)
-
Administration.md, The token: "GET /healthandGET /openapi.yamlare always open". The open set is larger:/started,/ready,/info,/openapi.json, the page,/live.js, the/adminredirect (AUTH-5). -
Administration.md, The admin UI: "There are no accounts" and the sign-in card's own text ("The server's token is the whole credential") inui/src/admin/Login.svelteread as false onceoidc.client_idadds the OIDC button. The admin-OIDC design called the card "unchanged". -
Administration.md, Sharing one: repeats AUTH-23 to AUTH-27 in plain words; fine, but it names one route per section and the live view's bound link is not mentioned. -
Administration.md, The token: the bare token as the whole header works on/admin/*too, not only "the HTTP endpoints"; on/mcpit is a 401 (AUTH-7).
Stale comments for the code round (R3)
-
http/auth.pymodule docstring: "It used to be answered by two hand-rolled copies...", a spec citation and "The split is deliberate". -
http/admin/signed.pydocstrings say "three routes" for a factory that mounts four, and cite "Copilot, PR #41";http/links.pycites§F1.10,http/answer.pycites "Copilot, #36", "§F4.19". -
principal.pymodule docstring: "nothing decides anything from it yet (spec 2026-10-04)" is out of date;opener()cites a ruling.
Design vs code
- package-restructure: a shared route mounter
http/mount.py. Not found.routes.py,flows/api.pyandhttp/files.pyeach mount their own table;routes.mountonly normalises the prefix. - package-restructure: "one wrapper replaces all four" request wrappers.
http.answer.answerserves browser, flows, files and site-data, butGET /secrets(secrets.secrets_route) builds its own response by hand (no body read, noADMINprincipal), and the admin door keeps its ownguardeddecorator. Spec says what exists (SURF-37). - package-restructure:
errors.as_response,mcp/annotations.py,mcp/guidance.py,session/. Code:http.answer.as_response,core/annotations.py,core/guidance.py,workspace/. - package-restructure: one shape for guidance (
{"read", "section", "prompt"}). Not found.core/guidance.pyshares only the URI builder; a run'shintis an object, the status'sguidancea string (its docstring says so). - package-restructure: guidance at the first
open_sessionand in the "no browser yet" refusal. Designed, not found: the refusal (Workspaces.resolved) namesopen_sessionand no skill URI. - package-restructure: "x-mcp extensions rejected". Code publishes
x-mcp-toolandx-mcp-resourceon every operation (spec/builder.py); sf-headers later lists them as unchanged. Spec follows the code (SURF-36). - package-restructure: "the published spec contains no MCP-only vocabulary". Designed, not found
as a test; operation descriptions are the tool descriptions verbatim. (
press_keynamesexecute_script, which is also an HTTP operation.) - package-restructure:
openapi.yaml"gitignored, untracked". True. The D4 entry lists it as code to read: the file on disk is a stale build (Oct 2): it has/files/downloads, lacks/browser/downloads,/files/recordings,/browser/await-control,/browser/network-body. Spec links the served document andtests/golden/openapi.jsoninstead. - sf-headers ruling 2: "
X-Workspacerefused, no aliases". Overtaken by the alias design;OLD_HEADERSholds six names. Ruling 6: gateway stops readingx-workspace. The wiki (Deployment.md187-195) says the gateway reads the caller'sX-Workspace. Outside this repo, not checked. - sf-headers ruling 11: generic old names refused. Code agrees. The design's "today the value is silently read" is history.
- show-design: six showable URIs,
session://names,session_filesremoved. Code: 13 components,workspace://names.session_filesis gone. Done, history only. - show-everything: "25 URI forms" and the research counts. Overtaken by capture (console,
network, request),
session://downloadsandworkspace://site-datatemplates. - show-everything ruling 2 (screenshot from its signed link), 3, 4, 6, 10 to 14, 16 (shell
behaviour). Not read in code: they are
ui/and belong to admin-ui.md. - show-design:
show"listed only for a client that renders apps, assession_fileswas; elsewhere still answers". Code agrees (HideMirrors), andshow.registerreturns{show}as an app tool whether or not apps are enabled, so withmcp.appsoff it is hidden from everyone.
Code vs code, or surprises
-
http.answer.read_bodyturns an unparseable JSON body into{}.POST /browserthen opens with defaults andPUT /flows/{name}complains about missing steps. Written as is (SURF-35). - MCP logs a failure with status 503 at ERROR with a traceback (
QuietCallerMistakes: anything not a 4xx), HTTP logs it at WARNING with the message (as_response). SURF-24 and SURF-42 say each as it is. -
tests/golden/openapi.jsonserverscarries an in-cluster service hostname (selenium-flow.flow...svc.cluster.local). It is in a public repo and inspec/builder.py. -
GET /browserbuilds itsCallerasCaller(name, "request", ...), dropping the client and flags: MCP'sworkspace://currentreportsnamed_byasheader,queryorstdio, HTTP alwaysrequest. Written as is (SURF-33).
Likely bug for Dr K
- Item 15: a malformed JSON body is read as empty rather than refused. For
POST /browserthat silently opens a browser with the defaults.
Wiki repeats the spec (for D16)
-
Installing.md21-25: the header and parameter table (SURF-8, SURF-12, SURF-13). -
Actions.md88 andDeployment.md187-195: naming, alias, gateway (SURF-9). - Generated tool pages and README 103: Claude.ai row (SURF-9).
Designs: plans/2026-10-27-live-view-design.md (872 lines) and plans/2026-10-27-live-control-design.md
(620 lines). Both got History headers. Code read: live/ (all), http/admin/live.py,
mcp/control.py, mcp/waiting.py, workspace/locks.py, workspace/calls.py, and the hosts
(Workspaces._said, paste, handed_back, _refuse, secrets.perform_write, flows/api.run_for,
flows/engine._drive, core/actions _at, screenshot, paste).
- Granting with no call running. Control design ruling 1 says control is "granted at once" with no
call running. Code (
Controls.ask): the viewer is always toldrequestedfirst, even with no call in flight, because the grant waits to follow the person's pages (up to 15 s).test_live_controlsays so in a comment. Spec: LIVE-17. - Live view ruling 35 (nothing refused or paused; a notice as a text block, with words "took control
of this browser at 01:42 UTC and may be typing in it") is overtaken by the control design: calls are
refused (409) and the notice is a
controlfield plus a text hint with different words. Spec: LIVE-21 to LIVE-27. The live view header says so. - Private header. Control design ruling 31:
x-selenium-flow-workspace. Code (mcp/clients.CARRIED):sf-carried-workspace. The spec says only "a private header". -
may_control. Live view design: the tunnel takes amay_controlcheck that always says yes. Code:Tunnel.on_askandControls.ask; no check exists. Spec: LIVE-18 states control is never refused. - Mint 404 reasons. Design lists three (
switched off,no browser,no live view). Code addsthis browser is headless: it has no live view(HEADLESS, after the headless design), checked third. Spec: LIVE-2. - Paste cap. Design: "capped at 10 000 characters" and the popover's
maxlength. Code (Actions.paste): cuts toPASTE_CAPafter dropping a trailing newline, never refuses an oversize text, and answerstypedas the length after the cut. Spec: LIVE-37. - Audit lines. Design shows three lines. Code adds
asked for control of <ws> (<session>)(written when a request is made) andswitched to watchas well as to control;leftnames the mode. Spec: LIVE-39. - A tunnel's ending is corrected to
4001when the Grid no longer lists the browser (Tunnel._checked, 3 s, only for a viewer leaving or the hub closing). The design's close table lacks it. Spec: LIVE-14. -
dialandopen_socket. Design:bidi/connection.py's_connectbecomes publicdial(url, *, max_size). Code:dialexists andopen_socketwraps it with a 5 s timeout and is what the live socket calls. No behaviour differs (max_size defaults to the 16 MiBMAX_MESSAGE). - Control design ruling 12 puts the 409
responsesentry inspec/. Present (spec/builder.CONTROLLED). No drift; listed because the sentence there ("Call POST /browser/await-control, then retry.") differs from the refusal's own. - Hand-back summary can carry
reopenedandsite_data(Workspaces.handed_backcopies them fromsettle). Not in the design. Not specced, because a hand-back never reopens a browser, so it should never appear (see likely bugs).
- Live view "The UI" section (noVNC lazy load, channel wrapper, presence timing in the page,
fullscreen, the paste popover, states,
liveUnavailable, the renames) and "Bundle and CI" (size budgets, workflow file lists, the LICENSE file):ui/and CI, UI's file (D11). Only the server routes are in LIVE. - "The Grid side, and the ingress" (ESO generator, chart values, ingress refusing
/se/vnc): not in this repo. - Control design "Docs" (SKILL.md routing line,
references/WORKSPACES.md, AGENTS.md, CHANGELOG): not checked here; SKILL.md is PLG's. - Control design "Done when" and the live checks on the cluster: not code.
Design is stale but still true of the code (kept out of the spec)
- Live view says the page "learns
gracefrom the mint answer" and the heartbeat is "fixed at 10 s". True; the spec says it (LIVE-3). - Control design says
Notices"appends a TextContent". It builds a newToolResult. Same effect.
None found that I would call a bug. Two things to look at:
-
Workspaces.handed_backcopiesreopenedandsite_datafromsettleinto the summary. With no reopen in a hand-back they never appear, so it is harmless, but a reaped browser read at the wrong moment could attach a reopen notice to a hand-back that the agent then reads as the person's work. - A request withdrawn before the grant leaves an unsaid hand-back, so the agent's next result says "control of this browser was handed back ... the page may have changed" although nothing was ever held (ruling 23 chose this, because the in-flight call was already told control was asked for). Worth a second look at the wording only.
Wiki and docs repeat the spec or are stale (for D15/D16, not fixed here)
-
docs/Administration.md(the list table) calls the pilllive/idle; the live view design renamed itopen/idle. The payload key is stilllive. - README.md:407,
docs/Home.md:58,docs/Deployment.md:61and:85,plugin/skills/selenium-flow/references/CONFIGURATION.md:43say the Grid's noVNC is onlocalhost:7900.docker-compose.yamlno longer publishes 7900 and setsSE_VNC_NO_PASSWORD, as the live view design (ruling 33) says. Deployment.md:85 still shows a7900:7900port in an example. -
docs/notes/await_control.notes.mdrepeats LIVE-28, LIVE-29 and LIVE-34 (cap, tasks, progress every 15 s, answer meaning). D16 should link instead.
Spec: docs/superpowers/specs/browser-actions.md, 42 requirements, 299 lines. Every requirement was
checked against the function named in its sentence. Designs consumed (History headers added):
2026-11-13-click-matches-design.md, 2026-10-02-optimal-shape-design.md. 2026-11-13-hash-routes-design.md
is Also: D7 gives it its header; ACT-14, ACT-16 and ACT-15 hold what it says about url=.
- optimal-shape, The core abstraction: "Recipe is the one place a per-session lock, a per-call
deadline, or the spare-tab time budget can attach." The lock is there (
locks.driving). No per-call deadline exists:Recipe.runonly takeswait_timeoutper element wait. Thecore/recipe.pymodule docstring repeats the claim ("a deadline per call"). Spec: nothing about a deadline. - optimal-shape, Known, for the next round: "
core/recipe.pyimportssession.locks(pass the lock in)." Still so, asworkspace.locks;Recipe.runtakes the turn itself. Spec: ACT-2 names the turn and points at WS-39. - optimal-shape, Pure modules: "
core... with fastmcp, starlette and selenium blocked".core/imports selenium by design, andcore/actions.pyimportsbidi,capture,site_data,faults,names,redaction. Only the framework half of the claim holds. - optimal-shape status line ("Task 26 in progress") and counts ("fourteen browser actions") are
stale:
Actionshas sixteen page actions run through the recipe plusopen_session,end_browser,network_body. - click-matches Research and Design cite
core/browser.py:595-604,core/actions.py:614-646,js/helpers.js:158-213and similar. None of those lines still hold; the wait isbrowser._FirstUsable. History header says so. - click-matches, Design,
_FirstUsablestep 2: "Shown mode, one match: Found(it, 0, 1) at once." Code: same, but onlyif not clickable and len(found) == 1; a clickable wait with one match asksis_displayedandis_enabledas ruling 5 says. No disagreement, noted because the sentence reads as if it applied to both. - click-matches Out of scope: "
execute_script(url=...)not navigating on a hash-only change... File it separately if it is real." Code: an anchor (non-route fragment) is not part of a page (urls.same_page), so no navigation is correct; a route change does navigate. Not a bug.
- optimal-shape Q2: "
end_browserraising the existing cancel so a 900 sassertends". Found, inworkspace.locks/core.cancel(Ended); it is WS-40's. Listed here because ACT-5 states the effect. - optimal-shape ruling 4: "a later round may let
navigateshow a kept file". Not built; not in the spec. - click-matches Where it lands: the AGENTS.md section "A selector may match several" and the skill
edits (
READING_PAGES.md,TROUBLESHOOTING.md) were not opened. If they restate ACT-9 to ACT-11 they are D15's to trim.
In the code with no design
The following have no design file; the spec follows the code and the commit named.
- Title wait after a same-document route change (
browser.landed,screen,TITLE_SETTLE): commit1bd10c5(#139, #145). ACT-14. -
press_keywith no selector presses at the active element:c6c8833(#136). ACT-27. - Script timeout worded as the caller's:
4d8b9d7(#125). ACT-36. - A host that does not resolve (
Unresolved) and an untrusted certificate (Untrusted):e5607da(#75). ACT-18. -
settledafter Enter: no design; measured in its docstring. ACT-13. -
outline's naming rule (own text only for non-controls) and chrome-after-content order:035adc7(#38) and #138. ACT-33, ACT-34.
Likely bugs, for Dr K (not specced)
-
frame(action="switch", index="abc")or any unreadableindexswitches to frame 0 (Actions.frame:driver.switch_to.frame(as_int(index, 0))).coerce.secondsrefuses for exactly this reason (a fallback that changes what the call does);indexshould be refused. -
screenshot(width=..., height=...)resizes the window and leaves it, butreshapesis true forresizeonly, so the record never learns the size: a reopened browser goes back to the old size, whilefull_pagerestores its own. Either restore after the shot or make itreshape. ACT-35 says "leave it so", which is what the code does. -
upload_file(text="")is refused as "the file is required": the source test isif v, so an empty file cannot be uploaded fromtext. - A negative
wait_timeoutis clamped to 0 forassert(coerce/assertion.window) but passed as it is to the element waits (Recipe.run:as_int), where Selenium'sWebDriverWaittakes it as an immediate timeout. Two behaviours for one argument. -
Actions.writetypes the stringNoneif called withtext=None; both surfaces guard it before (tools.py: "needs text, or a secret"), but the method itself does not. Not reachable from a surface as far as read; a flow step was not traced.
Wiki, to fix in D16
-
Actions.md(generated from the spec): "Every action is an MCP tool and an HTTP endpoint with the same parameters... A test fails the build" repeats SURF-39 and SURF-44. -
notes/extract.notes.md: sayshtmlisinnerHTMLand says nothing of the passwordvaluestripping (ACT-31); its "nothing from hidden elements" iselement.text(true). - The generated
docs/<tool>.mdpages carry the argument and result descriptions the spec links to; not compared line by line.
Designs: plans/2026-11-12-flow-sites-paths-design.md, plans/2026-11-13-hash-routes-design.md.
Code read: all of flows/ but the files half of store.py, workspace/workspaces.py (Caller,
settle, _touch, _hinted), urls.py (route_of, page_key), names.py, mcp/progress.py.
- Cache and catalogue names. Sites-paths rulings 5 and 24:
store.version()keys the cache andFlowStore.catalogue(workspace)builds it. Code:FlowStore.revision(name, inode, size, mtime) keysFlowStore._placed; there is noversion()and noFlowStore.catalogue.flows.api.catalogueis the listing and does not feed the hint. Spec: FLOW-25. - Ruling 22, "its reason is logged once per version". Code logs when
_placedrebuilds a library, so it repeats if the 256-library LRU evicts the entry. Spec says only that the log names the flow and no value (FLOW-24). - Rulings 10, 18, 21, 23 of the 11-12 design (query and fragment ignored, page is host/port/path, a
path with
#refused, fragment never read). Overtaken by hash-routes: the code matches a route. The History headers say so. Spec: FLOW-21 to FLOW-24, FLOW-27. - Ruling 19, a silent reopen "does not hint by itself". Not checked against
resolve; the spec says nothing about it. - Ruling 25 names
GET /browseras carryingflows_here. Code and tests confirm it only forworkspace://currentand the OpenAPI response ofcurrent_workspace; the spec saysworkspace://current(FLOW-28).
- Sites-paths ruling 14:
references/FLOWS.mdteachessitesandpaths. That is the plugin's skill (PLG), not read here. - Ruling 4 (an agent runs a hinted flow only when it fits the task) is skill text, not server behaviour. Left out of the spec; the History header says where it lives.
- The admin save (
flows.api.save_text) validates but never refuses an unknown top-level key, andflowdoc.validateignores them. A typo such asparameter:orstep:in the editor saves clean and is ignored at run. The agent paths cannot reach it (the MCP signature and the HTTP save pickDOCUMENT_KEYS), so only the editor can store one. - The admin save does not drop
workspaceorsharedfrom the YAML assave_onedoes, so a pastedGET /flows/{name}body stores them in the file. Harmless to a run, noise in the editor. - A run's order is: browser resolved, flow read, params checked. A missing flow in a workspace with
no browser answers
no session is open, notno flow called. Spec FLOW-30 states the order. -
status: okwith a failedonError: continuestep is tested as intended (test_the_run_status_and_a_step_status_are_different_questions). A run where every step failed and continued reportsok. Spec FLOW-32 states it; say if it should change.
Wiki (note, D16 fixes)
-
Flows.mdexamples writeargs: {css: "#email", text: ...}. Save refuses that:write has no parameter 'css'; it goes inside selector. The step needsselector: {css: ...}. -
Flows.mdsays a secret's step line readstext=<hidden>. The line readstext=[secret:<name>/<key>](redaction.marker,report.summarise). -
Flows.mdtable row "unnamed, or namedglobal":globalcannot be named (valid_workspace_namerefuses it).stdiois listed correctly. -
Flows.mddoes not mentionsites,paths,timeout,warnings,flows_here, the 120 s default budget oronError: continueleavingstatus: ok. -
save_flow.mdsays "workspaceis required in practice"; true, an unnamed caller is refused (FLOW-16).
Code comments out of date (not edited here)
-
flows/document.pymodule docstring: "it does not store flows, that isflows.py" and "running them, which is E3". The store isflows/store.pyand the run isflows/engine.py. Also cites the saga's section numbers throughout. -
flows/store.pycarriesPENDING_DIR, a files-half constant.
The spec follows the code.
- Resources: design says binary contents pass and text is scrubbed; code (
mcp/scrubbed.py) also scrubs bytes with a text media type (.txt,.csv, JSON, XML, YAML, JS, SVG) as UTF-8 and rescans JSON by value. (SEC-57) - Applied set: design says the sets of the origins before and after, plus kept; code
(
Scrubber._forms,_Entry.held) applies every set built for the browser plus kept. (SEC-37) - Scrubber state: design says an entry for another browser is replaced; code has a slot per workspace
(
opened,carry,ended, retired, parked, stale browsers scrubbed with everything held plus every leashed secret).Originshas the same slot rules and an unknown-frame default. (SEC-35, SEC-36, SEC-39) - Revision: design hashes key-file stamps; code also hashes each usable secret's leash. (SEC-33)
-
scrub_error: code adds a finalstr()check raisingUnscrubbed, not in the design. (SEC-43) - Forms: design lists "today's 13", CR/LF-stripped, repr, hex, reversed, base64; code also adds
LF-normalised, whitespace-collapsed, whole
upper(), and the whole padded base64. (SEC-48) - Short forms: design says values under 4 characters stand alone; code tests each form's width, so a short value's hex or base64 forms are not held to it. (SEC-50)
- Capture holds: code adds
QUEUE_BYTESandCONTEXTSbounds. (SEC-63) - Extract: code also strips password values inside
<template>content. (SEC-65)
None. Every design requirement I looked for is in the code.
Possible footgun, not a bug: a leash line with an explicit default port (https://host:443) never
matches a page Chrome reports as https://host. (SEC-10)
Likely bug: none found.
Wiki (D16): Secrets.md is stale. It says .meta.yaml (code: _description, _allowed_urls),
restricted: false means usable anywhere (code: refused), and a flow step line reads text=<hidden>
(code: text=[secret:name/key]). It lacks the marker, refused and the scrub. docs/saga was not read.
Design: plans/2026-09-30-site-data-design.md. Also read: plans/2026-11-14-reopen-notice-keep-alive-design.md
(its site-data parts only).
- Naming throughout. Design:
SessionRecord,session.ttl,session://site-data,session://current,/admin/sessions/{key}/...,Grid.bidi. Code:Workspace,workspace.ttl,workspace://site-data,workspace://current,/admin/workspaces/{key}/..., thebidi/package'sChannel. The spec follows the code. The design's History header lists it. - History URL below the top entry. Design: origin and path only. Code (
urls.page_of, used byWorkspace.pruned): origin, path and a hash route, never the route's query; a route containing=is dropped. Spec: SITE-44. - Reopen with nothing saved. Design (and
plans/2026-09-30line "reopen says nothing unless site data came back"): silent. Code: a reopen always setsreopenedon the first result (the reopen design overtook it);site_datarides beside it only when the restore said something. Spec: SITE-38. - Size cap order. Design: origins visited longest ago go first. Code adds the order after that: the page's localStorage last of the origins, and the page's sessionStorage only when no origin is left. Spec: SITE-8.
- Snapshot cookie shape. Design example lacks
value_type; code stores it (transfer.capture) and sends it back tostorage.setCookie. Spec: SITE-5. - Failed-step history. Design's last "Known" bullet says only steps that moved the page enter the
history. Code (
flows/api.run_for): every step withokand aurl, so a step that stays on a page still enters, but a failed one never does. Spec: SITE-42 states what the code does. - Design "Behind them" says the history_rev is "every entry's origin and URL, in order". Matches;
no drift. Listed because
site_data_revandhistory_revlive inhttp/admin/workspaces.py, nothttp/admin/site_data.py.
- The design's skill change (
SITE_DATA.md: one save covers every site, no arrival hint). Not checked: the plugin's skill belongs to PLG's file. - The design's drawing and tab copy ("Nowhere yet.", "Nothing saved - an agent calls
save_site_dataafter signing in.", the Forget and Clear confirm text, folding rows, the "saved 2m ago" pill). The UI lives inui/, which is UI's file; SITE covers only the routes behind them.
Design is stale but still true of the code (kept in spec as a limit)
- No overall time budget on the spare-tab loops (SITE-27). Each BiDi command waits 5 s
(
bidi/connection.REPLY_TIMEOUT). - Every touch rewrites a record that can hold up to 1 MB of site data (not specced).
- History's secrets are joined per request, so a catalogue change shows on the next fetch, not via
history_rev(not specced).
Likely bugs (flagged, not specced)
- A save can drop a newly visited origin's earlier storage.
snapshot.snapshotbuildsoriginsfrom the history at write time, butkeptholds only origins that were attempted and failed. An origin that entered the history afterWorkspaces.visitedwas read (a call landing during the save) is neither inreadnor inkept, so its previous storage is lost. The design lists it as "Next". The fix is to keep previous storage for every history origin the save did not attempt. - An
http/httpsfilter intransfer.capture(wanted) means a history origin with another scheme (for examplefile://,chrome://) is never read and never named inskipped, so its earlier storage is dropped silently. Low impact; no such origin can be restored either. -
open_browserdeletes the snapshot only when it isrestorable. A snapshot that holds onlysaved_at(reachable only from a hand-edited record) survivesrestore_site_data=false. Harmless; noted for completeness. - The admin
GET .../site-dataandGET .../historyreturn non-httpOnly cookie values and storage values unscrubbed (they go throughguarded, not the scrub that the agent resources get). Probably intended for an admin; worth Dr K's confirmation against the secrets area.
Wiki repeats the spec (for D16, not fixed here)
-
save_site_data.notes.md(and the generatedsave_site_data.md) state the restore order, the hidden tab, the limits (IndexedDB, one tab's sessionStorage, 100 sites, service worker fallback, httpOnly•••, Redis durability) that SITE-6, SITE-8, SITE-15, SITE-29, SITE-50, SITE-62 and SITE-63 hold. -
get_site_data.md,list_site_data.mdrepeat SITE-47 to SITE-50.
Design: plans/2026-10-10-capture-design.md. The spec follows the code in each pair.
- Section 7 says
network_bodyisGET /browser/network/{id}/body. The code (core/capabilities.py) isPOST /browser/network-body, tool and route. CAP-67. - Ruling 11 says the body is fetched "through the session's connection" and capped at 100 kB. The code fetches on a private channel (
Channels.open_channel(private=True)), refuses a text body over 8,000,000 bytes (BODY_FETCH_LIMIT), and cuts at 100,000 bytes after the scrub (cut_body). The design's own section 7 and final-review notes say the same as the code. CAP-70 to CAP-73. - Section 4 says
Capture.mark(workspace) -> seqandcaused(workspace, since_seq). The code'smarkreturnsMark(errors_total, failed_total), andcausedsubtracts the totals. CAP-54. - Ruling 10 says "at most 32 headers of 4 kB each". The code also caps each side at 16,384 bytes of names and values, and a name at 256 characters (
HEADER_BYTES,HEADER_NAME_CAP). The design's final-review notes agree. CAP-65. - Ruling 13 says
request.cookies[].valuebecome•••. The code keeps no cookie list in a row: BiDi cookies are only learned for masking (Masker.cookies), and theCookieheader shows•••. CAP-59, CAP-61. - Ruling 13 says arguments are masked. The code never keeps console
args(merge.console_entry). CAP-19. - Section 5 says the open path is awaited for
POST /browser {"capture": true}. The code has the same path for both surfaces (Workspaces._opened); the HTTP body field was not opened in this area.
- Designed, not found: ruling 17 (the deadline close counts as Grid activity) and ruling 18 (Chrome reports a fetch failure only once its body is read). Both describe the Grid's or the browser's behaviour; nothing in the code asserts them. Not in the spec.
- Designed, not found:
references/TROUBLESHOOTING.mdgains "a call failed and the page said why" (section 7). Not checked, and plugin content isplugin.md's.
- The admin's
POST /admin/workspaces/{key}/network/{id}/bodyreturns the masked and cut body but skips the workspace scrub (http/admin/capture.py,admin_request_body), while thenetwork_bodytool scrubs with every leashed secret (Workspaces._scrubbedfornetwork_body). A secret in scope on an origin the browser never bound is masked in one and not the other. The route's docstring says "Not scrubbed (ruling 17)", which cites no ruling in the capture design. Written into CAP-78 as it is, and not as a requirement to keep. - The first call after
capture.ttlof quiet has no hint:Calls._markgets None fromCapture.markwhen the buffer expired, soendskips the count even though capture is held again for the call (CAP-55).
| Source | Says | Code does | Spec | Bug? |
|---|---|---|---|---|
| recordings design, ruling 6 and section 1 | data.dir/sessions/<name>/... |
data.dir/workspaces/<name>/...; an old sessions/ is renamed once at boot (flows/store._move_old_folder) |
FILE-2, FILE-51 | No |
| recordings design, section 4 | session://files/recordings[/{name}] |
workspace://files/recordings[/{name}]; session://files/... is refused with the new spelling (names.MOVED) |
FILE-25, FILE-28 | No |
| recordings design, section 1 | retired-name message says session folders live under DATA_DIR/sessions/
|
workspace folders live under DATA_DIR/workspaces/ (config.RETIRED_FLOW) |
FILE-51 | No |
| recordings design, section 3 | skips names ending .partial or .part
|
also skips .tmp and any name starting with a dot (collector.PARTIAL_SUFFIXES, _inbox_files) |
FILE-56 | No |
| recordings design, section 1 | network filesystems nfs, nfs4, cifs, smb3, 9p, ceph, glusterfs, fuse.*
|
also smbfs, and any type starting fuse (recordings/mounts.py) |
FILE-52 | No |
| recordings design, section 3 | the collector reads the Grid's /status once per tick to learn a browser is gone |
the monitor says so (session.ended on the bus, Collector.ended); the collector reads no Grid listing |
FILE-54, FILE-58 | No |
| recordings design, section 3 | "missing" warning reads recording for session S (opened 14:03) never reached RECORDING_DIR
|
recording for workspace %s (opened %s UTC) never reached ... |
FILE-60 | No |
| recordings design, section 3 | filing moves the file then deletes the note | the note is marked filed or dropped first, then deleted; a failed delete is retried alone and never refiles |
FILE-59 | No |
| recordings design, section 2 |
se:videoName is the session name |
it is the workspace name (Workspaces._recorded) |
FILE-45 | No |
| recordings design, section 4 | reading a recording answers its entry; nothing about Files | a Files entry whose type starts video/ answers its entry as JSON too (files._item_resource) |
FILE-29 | No |
| recordings design, section 4 | a video link gets "the image treatment: no sandbox, nosniff, a no-script CSP that still lets the media document load" |
video/* and audio/* get default-src 'none'; media-src 'self'; style-src 'unsafe-inline', not the raster policy (signed.MEDIA_ONLY) |
FILE-41 | No |
| recordings design, section 4 | admin keep and REST keep for a recording are a plain move | a strict move: if the source cannot be removed the Files copy is removed and the call fails; a source swapped for another file is left alone (FileStore.move_in, _release) |
FILE-33 | No |
| recordings design, section 6 | a failed note write leaves the result with recording: true and recording_error
|
same (Workspaces.open) |
FILE-48 | No |
http/files.py docstring, files.sections and admin_files docstrings |
"three sections" | four sections are returned, Recordings included | FILE-2 | Stale comment |
http/files.py keep_route docstring |
keeps "a screenshot or a download" | also a recording | FILE-33 | Stale comment |
http/files.py module docstring |
"Screenshots and Files belong to the workspace"; Recordings not named in the ownership paragraph | Recordings are the workspace's, like Screenshots | FILE-2 | Stale comment |
| the Hangar plan and saga chapter 4 | not read, as briefed | n/a | n/a | n/a |
| recordings design, ruling 5 and 7 | no per-recording delete | none (admin delete is Files only, clear is wholesale) | FILE-43 | No |
| (designed, not found) | recordings design, section 3: "a startup scan of the inbox" for a restart | no separate scan; the notes are reloaded and the first sweep matches them (Collector.start, sweep) |
none | No |
- A kept download replaces a same-named file in Files without a word (
FileStore.write_file), while a screenshot, a recording and a print never overwrite (name (1)). A person who keptreport.pdffrom a print loses it when a later download is namedreport.pdfand kept. Thekeep_filedocstring says so, so it is specified (FILE-33), but the two rules differ for the same destination. - The admin's keep route passes the record's browser id without asking the Grid whether it is alive
(
http/admin/files.pyadmin_keep_file), unlike the listing, which asksis_alive. Keeping a download of a reaped browser returns the Grid's error, where the tool saysno session is open .... Minor. - A signed Downloads link carries the Grid session id in its path (
/files/<session_id>/<name>). Nothing else in this area exposes a Grid id, and the recording rules say the id stays on disk. Not a bug for downloads, but worth a ruling if the id is meant to stay private.
- Secrets tab. Design (svelte-admin-ui S1): each card has USED BY rows (flow pill, steps,
session →link or shared marker, "No flow uses it.") and a "Named by a flow, not defined" section. Code:SecretCard.svelteandSecretsPane.sveltehave neither. Spec: UI-51 lists what the card shows. Designed, not found. - Sessions became workspaces. Design: Files and Flows subtabs under
#/sessions/<k>, three Files accordions. Code: eight workspace tabs,#/workspaces/<key>/..., four Files sections with Clear recordings. Spec: UI-18, UI-28. - Design D3 "End browser asks through native confirm". Code agrees, but the confirm text now says the workspace and context are kept. Spec: UI-27 (no exact text).
- Design A4/F9: "UI-2 pure refactor, no new CSP". Code sends
frame-ancestors,nosniff,Referrer-Policyon the page. Spec: UI-11. - Design R3 says the console tab is hidden when its URL is the page; code does the same, but both the top Grid console tab and the workspace Console tab use the id
tabConsole. Spec: silent. Likely bug (duplicate DOM id; only matters for selectors). - Design F8/F9/F3: Clear downloads confirm and the lightbox Keep/Delete wording: code matches; the lightbox itself (
lib/Lightbox.svelte) was not specced here (FILE area). - Design "UI copy is terse, no helper lines" (house rule, memory): code has helper sentences in Settings ("How this server was started. Read-only.") and Secrets ("What flows can type without anyone seeing it..."). Spec: UI-48 does not claim their absence.
- Design 4.1 Admin-OIDC "Penpot Admin UI -> Admin -> login": the Penpot file is not in the repo, so the drawing/code match (UI-62, UI-63) could not be checked. "Code is the truth" (UI-63) is the brief's rule, not a ruling found in a design. Designed, not found.
- Design MCP App P1: only
fileSections. Code:App.sveltedraws thirteen views bycomponentname. Spec: UI-60. - Design: "Cookie/History/Site data row opens first". Code: the first row opens once, then the fold is the reader's (
folds). Spec: UI-46. - Design: live badge texts "connecting… / live / reconnecting… / polling". Code: live is a dot with no text (
WorkspacesView). Spec: UI-33. - Design L3: card meta line. Code adds
by <opener>and capture/rec pills. Spec: UI-25, UI-26.
Design: plans/2026-09-26-configuration-design.md. Plan: plans/2026-09-26-configuration.md
(not read beyond its opening).
- Validation passes. Design: "validates once" after merging the three dicts. Code (
config.load): the file is validated alone first (a malformedredis: brokenwould otherwise be overwritten byREDIS_HOSTand accepted), then the merged result, thenoidc_problemandrecording_problem. Spec: CFG-25. - Help text. Design:
(env: SESSION_TTL · file: session.ttl · default: 86400). Code (config.parser):(env: ... · config: session.ttl · default: ...), andunsetfor an empty default. Spec: not restated; the wiki's intro says "config". -
session.storeandsession.ttl. Design: they are the session's settings. Code: they areworkspace.storeandworkspace.ttl, and the old names are refused (_retired_session), which the design's "no aliases" implies but never specified. Spec: CFG-24. -
FLOW_DATA_DIR. Design says nothing about refusing it. Code refuses it and aflowfile section with a message (_retired). Spec: CFG-24. -
session.keep_alive,live.*,recording.*,capture.ttl,security.frame_ancestors,link_ttl,public_base_url,mcp.*,oidc.*anddata.dirpost-date the design's settings table. The design's table is not the settings;config.leaves()is. Spec: CFG-1 maps each to its area. - Sensitive set. Design:
auth.token,redis.url,redis.password. Code: the same three, andtests/test_config_schema.pyholds it. No drift; listed becauseoidc.*has no sensitive field and the design's cluster install passed the token throughAUTH_TOKEN. - Description rule. Design: "one-sentence description". Code adds a test: at most 100 characters,
ending in a full stop (
test_every_leaf_has_a_one_sentence_description). Spec: CFG-46. -
log_leveldescription. Code's field says "DEBUG, INFO, WARNING or ERROR." and theLiteralalso acceptsCRITICAL. Spec follows theLiteral(CFG-35).
- Design "Documentation" (README stays high level, wiki gets the full breakdown): the wiki half is generated (CFG-47); the README's text was not read.
- Design "The cluster install" (gateway route, policy,
config.yaml,.mcp.json): lives in the cluster repo. - Design "The Settings tab" header link to the wiki, the legend, the tooltip and the order of the
top tabs: drawn in
ui/, not config's code. admin-ui.md holds them. - Design "The Secrets tab changes" (
origins,key_sources, warn pills): secrets-and-scope.md and admin-ui.md. - Design "Penpot": a drawing, not code.
Likely bugs or soft spots for Dr K
- Redis unreachable at start ends in a traceback, not
selenium-flow: <reason>.StoreUnavailableis aRuntimeError,maincatches onlyConfigError, andstore.from_settingsdocuments that it is left to propagate. The message is good (host without userinfo) and the exit is non-zero, but a config mistake the operator can fix reads as a crash. Spec: CFG-34 states what happens. - The Settings tab shows
session.capabilitiesunmasked (describestrips userinfo only from the fiveURL_LEAVES). W3C capabilities can carry a proxy with credentials (proxy.httpProxy: http://user:pass@host, or--proxy-server=ingoog:chromeOptions.args). An admin sees it. Not specced as a feature; CFG-51 states the five. -
port,workspace.ttl,session.width/height/timeouts have no bound. A negative port or a zero ttl loads and fails later. Not flagged as wrong, noted because the bounded keys are deliberate (ge,le) and these are not. -
--config-file ""falls through toCONFIG_FILE, because a blank flag counts as not set (CFG-10). Consistent with the rule; noted because an operator might read it as "no file".
Wiki repeats or contradicts the spec (D16)
-
Configuration.md(generated) intro andnotes/Configuration.notes.mdboth state the precedence; the notes' "A boolean setting accepts true/false, 1/0, yes/no and on/off" is pydantic's rule and is in no code of ours. Not in the spec. -
notes/Configuration.notes.md: "enableServiceLinks: falseon the pod" is deployment advice for theREDIS_PORTtrap (CFG-23). Spec states the trap, not the remedy. -
Deploymentwas not read.
Compared with mcp-kb/docs/superpowers/specs/config-and-sources.md. Not changed; listed only.
- File discovery. mcp-kb:
--configorCONFIG, default/etc/mcp-kb/config.yaml. selenium-flow:--config-fileorCONFIG_FILE, no default and no search, so no file is a valid start. Spec: CFG-16. - What the file may hold. mcp-kb: the file says what to serve, flags and environment say how to
run, and no setting is in both (CFG-2). selenium-flow: every setting but
secrets.entriesis in all three places and the highest layer wins. Spec: CFG-8. - Environment overrides. mcp-kb has two variables (
CONFIG,CACHE_DIR). selenium-flow has one per setting, derived from the path, case-insensitive, with unknown names dropped. Spec: CFG-3, CFG-22. - Schema publication. mcp-kb:
mcp-kb schemaprints the JSON Schema andconfig.schema.jsonis in the repository (CFG-3). selenium-flow: no JSON Schema of the config is generated or published; the models are the schema and the wiki page is generated from them. Spec: CFG-45. - Credential references. mcp-kb: a source's
auth.passwordmust be{env: NAME}, resolved when a backend connects, and an unset variable fails only that fetch. selenium-flow: a secret key is{file},{env}or an inline{value}, resolved when the value is bound, and an unresolved key is listed and refused at bind. An ordinary setting,auth.tokenincluded, takes a plain value in any layer and has no reference form. Spec: CFG-41, CFG-42. - Validation errors. mcp-kb: exit code 2,
mcp-kb: <reason>, a URL's userinfo masked as***@, and exit code 3 for a refused fetch credential. selenium-flow: exit code 1 throughSystemExit("selenium-flow: <reason>"), every problem listed with where it came from (file, variable, flag), no input ever echoed, and argparse's code 2 only for an unknown flag. Spec: CFG-26, CFG-27, CFG-32. - Unknown keys. Both refuse them in the file. selenium-flow also drops unknown environment names by design (Kubernetes service links); mcp-kb has no per-setting environment names to filter. Spec: CFG-21, CFG-22.
- Validation scope. mcp-kb: the whole config is validated before anything is fetched. selenium-flow:
the file alone, then the merged result, then cross-field rules; checks that touch the machine
(the recording inbox, the data directory, Redis) run while the server is built and Redis is not a
ConfigError. Spec: CFG-25, CFG-33, CFG-34. - Reload. Neither reloads the config file. mcp-kb refreshes its sources on a timer and on
POST /reindex; selenium-flow re-reads only secret directories (30 s cache), secret key files and variables at bind, and the live-view password file. Spec: CFG-53, CFG-54. - Retired names. selenium-flow refuses a few old names (
FLOW_DATA_DIR,session.store,session.ttl) with the new name; mcp-kb's spec names none.
The two that matter most: 4 (no published schema, so no editor completion or CI check of a config file) and 2 (one precedence model against a split by purpose), which decides how a deployment composes a file and variables.
The spec follows the code.
- Skills-extension Ruling 1 says "no conditional declaration". The code (and the design's own
registertext) declares the extension only when the skill conforms (PLG-18). The ruling means the gateway, so this is wording, but the two read as opposed. - Skills-extension The entry says the frontmatter is "the YAML between the first two
---lines".frontmatter.splitneeds the first line to be---and ends at a line that is---afterrstrip(PLG-35). A file with a blank line before the first---has no entry. -
pyproject.toml's comment says a wheel withoutplugin/"serves none of it and says nothing".skill.loadlogsno packaged skill at <path>(PLG-13). -
prompts.pycarries its own_split, and the plugin-agents design says one header parse is shared by both extensions (mcp/frontmatter.py). The prompts loader is not one of its users (PLG-26). Behaviour differs, see the likely bugs. - Explorer design, test list: it names five tests;
test_explorer.pyhas twelve, including the turn budget. Not a requirement drift; recorded so the plan is not read as the whole suite.
None.
-
prompts._splittakestext.startswith("---")andpartition("\n---"). A first line of----or---xopens a header, and any later line that merely begins with---closes it, including one inside a multi-linedescription.frontmatter.splitrequires a line that is exactly---. A CRLF prompt keeps a\rat the start of its body. No shipped prompt trips it. -
test_the_format_matches_the_one_skills_mcp_servesonly checks the shape of the shipped files. It does not compare the loader with skills-mcp's, so the "copy must not drift" rule has no test.
Wiki: Installing.md mentions the skill and the mirror tools in prose that repeats PLG-54, PLG-55
and PLG-58. Not fixed (D16).
mcp-kb specs read: skills.md, agents.md, prompts.md (head), scoping-and-instructions.md (INS).
Skills and the Skills extension:
- Address space: mcp-kb serves libraries,
skill://<library>/<folder>/<name>/..., plus_index.md,_files.md, library files and plugin-root fallbacks. selenium-flow has one skill atskill://selenium-flow/..., no_index.md, no_files.md, no folder or library segment. - Who serves the resources: mcp-kb implements its own listing, read and template
(
skill://{library}/{+path}). selenium-flow hands the folder to FastMCP'sSkillProvider, with every file listed as a resource and no template.resources/listis a row per file here, an index row per library there (alisting=fullsetting adds skills). -
_manifest: mcp-kb's is{"skill", "files": [{path, size, hash}]}of the disk bytes, nested skills included. selenium-flow's is FastMCP's own shape. - Placeholders: mcp-kb rewrites
${CLAUDE_PLUGIN_ROOT},${CLAUDE_SKILL_DIR}and qualifiedplugin:skillnames inSKILL.md(SKL-25, SKL-52, SKL-55) and prefixesskill://for a gateway (SKL-41). selenium-flow serves every file as written and has no prefix. - Entry digests: both digest the bytes a read returns. In kb that includes its substitutions and prefix; here only FastMCP's newline normalisation (PLG-20).
- Conformance: kb needs
SKILL.mdto start with---and a newline; selenium-flow usesfrontmatter.split, which also rejects an unterminated header. Both check JSON survival, the name and a 1 to 1024 description. kb treats a nested-too-deep or non-string-key header as absent; selenium-flow treats a non-string key as a JSON-survival failure (the entry is dropped, the skill is still served). - Scope: kb filters every method by library, category and tag, and a scope can be refused (SKL-50). selenium-flow has no scope and the entry is the same for every caller.
- Declaration: kb declares the Skills extension always; selenium-flow only when the skill conforms
(PLG-18). Both declare on
server/discoverand oninitialize, whether or not the client did. In selenium-flow theinitializedeclaration comes from theAdvertiseSkillsmiddleware. -
resources/directory/read: kb answers-32601; selenium-flow does not mention it (FastMCP's answer). - Paging: the same on both:
cursorfails with-32602Invalid skills cursor; the result envelope (resultType,ttlMs: 0,cacheScope: "private") is the same.skills/getrefusals match (Skill not found).
Agents and the Agents extension:
-
_metakey: kbio.kubed.mcp-kb/agentwithplugin,library,path,frontmatter,serversandskills; selenium-flowio.kubed/agentwithfrontmatterandskillsonly. kb plans to add the shared key beside its own. - Sources: kb reads agents from Claude-format plugins,
agents/with subfolders, or a manifest list. selenium-flow reads*.mddirectly inplugin/agents/, no subfolders, no manifest list. - Names: kb prefixes the card name with the library and subfolders
(
<library>_<subfolder>_<name>) and renames a clash to<name>@<plugin>. selenium-flow serves the bare name and skips a duplicate (the first by file name wins). -
instructions: kb rewrites qualified skill names and${CLAUDE_PLUGIN_ROOT}and applies the prefix (AGT-17); selenium-flow serves the stripped body as written (PLG-41). -
_metaskills: kb accepts a list or a comma string, resolves qualified and bare names, trims entries and keys by the entry as written. selenium-flow accepts a list of strings only and resolves only the served skill's own name. - Freshness: kb re-reads a live-fetch agent on
agents/get; selenium-flow reads once at build. - Capability: both declare
{"listChanged": false}and send no list-changed. selenium-flow gates the extension on the skill being served; kb's is not gated on a skill. - Errors:
Invalid agents cursor,Agent not foundwithdata.reasonand the-32602code match; kb adds a refused-scope failure and/healthreporting, selenium-flow neither. - Model hint: kb's and selenium-flow's are alike (first of opus, sonnet, haiku by position). kb also
omits
inheritexplicitly; selenium-flow omits it as a word that is none of the three.
Prompts:
- Dialects: kb reads three (
mcp-kb,claude,copilot) and picks one by rule; selenium-flow reads one, themcp-kb/skills-mcp format, and skips a file that does not fit. - Title and name: kb publishes a
titleand names a prompt<library>_<name>; selenium-flow takes the file stem and publishes no title. - Rendering: kb also renders
${CLAUDE_PLUGIN_ROOT}, qualified names and the gateway prefix; selenium-flow renders only{{ }}. A value ofNoneor""counts as not given on both. - Parsing: kb's header parse treats a non-string key as a skip with a reason in
/health; selenium-flow's_splitskips with a log line and has the weaknesses listed above. - Listing: kb lists prompts by scope and also offers
list_promptsandget_promptmirror tools; selenium-flow lists them the same to every caller and has no prompt mirror (its mirror is two resource tools).
Instructions:
- kb builds its instructions per request from the catalogue, scope, whether the client reads resources and whether it declared the Skills extension (INS-2, INS-3), and names libraries and skill names. selenium-flow's are one fixed text with a skill pointer, chosen by whether the skill is served and whether the client reads resources. Neither mentions agents or prompts.
- Capability test: selenium-flow decides "reads resources" from a table of client names (
Visual Studio Code) and a flag (clients.reads_resources). Not compared with kb's test (http-and-tools.md, not read).
The two that matter most: (4) kb rewrites plugin:skill names and plugin-root placeholders in skills,
agents and prompts and selenium-flow rewrites nothing, so a skill or agent written for one does not
carry to the other as written; and (11) the _meta shapes differ, so a host reading both servers
reads io.kubed/agent from selenium-flow and io.kubed.mcp-kb/agent from kb.
The first pass left four things, done here.
- The spec against a rebuild. A cold read asked whether the server could be rebuilt from the spec alone. Behaviour held; a cross-cutting layer was written nowhere. Four area files close it: protocol, errors and logging, grid and runtime. The glossary gained nine terms. Every cross-reference between area files resolved (194 of 194).
- The plugin's skill. Its references lost fourteen false or unverified claims.
- The plans folder. The ledger replaces 33 implementation plans and the four saga chapters: 55,981 lines in 67 files became 16,796 in 37.
- The next features. Flow tags and the workspace config have designs and proposed requirements.
| What | After the first pass | After the second |
|---|---|---|
| Spec | 15 files, 4,864 lines, 792 requirements | 19 files, 5,980 lines, 926 requirements, 36 of them proposed |
| Plans and saga | 71 files, 61,627 lines | 37 files, 16,796 lines |
| The plugin's markdown | 2,314 lines | 2,064 lines |
- An unreachable Grid logs differently by surface. Over MCP every 5xx, a 503 from an unreachable Grid included, logs an ERROR with a traceback. Over HTTP the same 503 is one WARNING line.
-
A failed keep on
printloses the rendered file. It raises a 500, wherescreenshotreturns the image with afile_error. -
Some log calls skip the safe formatter. Several
log.debug(..., exc_info=True),log.errorandlog.warningcalls incore/actions.py,core/probe.py,core/pointer.pyandcore/naming.pydon't go throughfaults.formatted. A Grid URL carrying userinfo that reached one could appear in a log. -
Cancelledhas no status mapping and would answer 500 if it ever escaped. -
Two readers of the VNC capability disagree.
Grid.sessions()readsse:vnc, and the record'sranreadsse:vncEnabled. -
One cap is written in two requirements. FILE-22 repeats SURF-35's body caps. The limits table in
runtime.mdnames SURF-35 as the owner.
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network