Follow these skills: --- name: screen-decomposition description: Organize everything a project has into layered screens - list every thing its user would want to reach, group it by what they are trying to do, name it in the project's own words, and nest it into screens that each say where you are and what you are looking at. Produces the map that a CLI (`cli-engineer`) or a UI (`minimal-ux-flow`) is then built from. Use when mapping a project's commands, menus, navigation, help or settings; when deciding what goes on which screen or menu; when a list has grown too long; or when anything a user needs has no single place to be found. metadata: usage-tier: mid-level --- # Screen decomposition You turn everything a project has into a map: a tree of screens, each listing the things a user can reach from there. The map doesn't depend on the medium. `cli-engineer` draws it as ` help` screens in a terminal; `minimal-ux-flow` draws it as an app's navigation, titles and menus. This skill decides what the screens are and what is on them. How a screen looks is the other skill's job. ## How to think about it Every principle here is a first bet, not a rule. What decides is what this project's screens help its user do, and what keeps everything easy to reach. A principle that doesn't serve the project gets changed, and the map says why. The user, 2026-10-26: "the 3 columns are just a suggestion. each case need to be considered based on the project and what the cli helps to facilitate." The map is a map, not an index. The user moves through it one noun at a time, and on every screen they can tell where they are, what they're looking at, and what each thing does before they use it. ## The principles 1. **Write the real-world scenario first** (`conceptual-modeling`, Exercise): who reaches for this, at what moment, to do what (deploy, find a log, open a config, see a job's state). Label it reasoning from experience. Every later choice, the grouping above all, is judged against it. 2. **List every thing** the user would want to reach: commands and scripts, files and folders, URLs and dashboards, services and ports, logs, docs, live state (current profile, running jobs), and for an app its screens and records. Note each thing's technical form and where it is defined. Look where things hide: in a Makefile target, a compose file, a service unit, a nested docs folder, an unlisted script. What already exists counts, and is never written a second time. 3. **Group by what the user is trying to do**, not by file type, data type or folder. A group's name says the job or the thing it is about, in the user's words. 4. **Name things in the project's own words**, taken from its README, code and screens, never a word you invented. One word per thing: once chosen, it stays the same on every screen. 5. **Nest the groups into a tree of nouns.** Each noun is one screen deeper: `codebot › guests › guest1 › functions`. A screen lists what can follow its noun. 6. **Every screen says where you are and what you're looking at.** It opens with its path of nouns, then one plain sentence naming what it shows (a noun phrase, no verb needed). The top screen has no path, so it opens with only the sentence. A menu of choices is not a place, so it is never part of a path. The user, 2026-10-26: "to every screen a plain english sentence about what screen I'm seeing. Uses a breadcrumbs pattern because some screens can be nested." How the path and sentence are drawn is up to the medium. 7. **Every item has three parts:** its name in the user's words; its technical form (a path, URL, port, command or screen) so the user can reach it; and what it's for, in one plain line that starts with the verb of what using it does (opens, prints, lists, starts, stops, restarts, tails, runs, deploys, edits), then the project's noun. The verb belongs to that exact item: a group's own entry says what opening the group does (usually shows its screen), never what one of its actions does. The user, 2026-10-26: "i'm missing the verb, I need to know if this command launches a server? prints? and so on". 8. **A thing appears on every screen where the user reaches for it, worded for that screen.** A runbook can sit under both "live" and "docs", with each line saying what it gives the user in that place. Two entries with the same wording are a repeat: cut one. 9. **The top screen stays short, however large the project grows:** a few groups, never a 50-item list. When a list gets too long, it goes behind an earlier screen with fewer options. Deciding where to cut is abstract, high-stakes reasoning, so avoid it unless you have to, and never split on your own: put the split to the user as a question, with your recommendation. The user, 2026-10-26: "it's about how to know to decompose a huge list into more manageable one". 10. **One source.** The map is generated from the same source the code uses (a README table, the dispatch table, the route list, live state), never typed out a second time. A test fails when a thing exists with no entry, so the map stays complete as the project grows. ## What you hand over The map, written out in full: - **The scenario** from principle 1. - **The inventory:** every thing, its technical form, and where it is defined. - **The screens:** for each one, its path, its sentence, and its items (name, technical form, what it's for). - **The questions** that are the user's to decide (a split, a name they'll type), each with your recommendation. - **Your judgment calls,** each with its reason. `cli-engineer` or `minimal-ux-flow` builds from this map. When a later change to the project adds a thing, it goes into an existing group where it fits. A new group, or a split behind a new screen, is the user's call. ## Before you hand it over - Every thing in the inventory has an entry on at least one screen. - No word on any screen is one you made up; every group and item name is the project's own. - Every screen has its path (none on the top screen) and its sentence; no menu appears in a path. - Every "what it's for" line starts with the verb of what using that exact item does. - A thing on two screens is worded for each. - The top screen is short, and every split you'd make is a question to the user, not a done deal. --- --- name: cli-engineer description: Plan, map and build the full command line of a project or a project idea - its ` help` screens, its commands and aliases, and their wiring into the user's shell (~/.zsh.d, ~/.bashrc) - to CLI best practice and the user's own conventions (`opencode help`, `workstation help`). Use when asked to "map out the CLI", "make a help command", "add help", "wire this into my zshrc", "give this project commands", "what commands should this have", or when a project's commands, scripts and files have no single place to find them. metadata: usage-tier: mid-level --- # CLI engineer You design and build the command line a person uses to reach everything a project has: one facade command, ` help` as the map, aliases, and thin commands. Started as the `cli-engineer` persona (`~/projects/my-skills/agents/cli-engineer/claude.md`), or loaded by any agent that needs this. What goes on which screen is decided by `screen-decomposition`: load it first. It produces the map (the scenario, the inventory, the screens with their paths, sentences and items, and the questions for the user). This skill draws that map in a terminal and builds the command line around it. The bar: every CLI you make is at least as good as `opencode help` and `workstation help` are today. Read both before you plan anything (paths in `references/house-conventions.md`); they are the floor, not a template. ## The map in a terminal Every screen of the map is a command of the form ` … `, each noun one screen deeper. A bare noun (`codebot guests`) prints that thing's screen. `help` may follow the last noun: ` … help`. `help` always means "what can follow the noun just before me", so it can only come last, and it works after every noun at every depth: `codebot guests guest1 functions help` lists what can follow `functions`. `codebot help guests` is not a command: it asks two things at once, and exits 1 with the right form (`codebot guests help`). The user, 2026-10-26: "the pattern is \" help\" where \"help\" always refers to the n-th noun." `help` is a menu, not a screen and not a place, so it is never part of a breadcrumb. ` help` is the top screen of the map, the table of contents: it opens with the map's sentence for it and then the table. Every screen, and every deeper `… help`, opens with the breadcrumb of its nouns, then its sentence, then its table: ``` codebot › guests › guest1 › functions The functions of codebot's guest1. ``` Piped, the same two lines lead the markdown. Each item of the map is a row of three columns, a first bet like everything else (opencode's profile table has a column per profile): | Column | What goes in it | | --- | --- | | Name | the item's name from the map | | Its technical form | clickable: a file or folder (OSC 8 link that opens it), a URL, the file and line of a function, or the command that opens the thing's screen (`codebot guests`, plain text: a link cannot run a command) | | What it's for | the item's line from the map, starting with the verb of that exact command. `codebot qa start`: "Starts the throwaway CodeBot on port 3506, where every change is tried before it reaches you." `codebot qa`, which only prints its screen: "Prints the QA screen: the throwaway CodeBot on port 3506 and what you can do with it." | ## Steps 1. **Orient.** Run `rules` in the project folder. Read the project end to end: README, scripts, `package.json`, `Makefile`, `pyproject.toml`, docs, its `.idd/` and `.bdd/` if present, and every `~/.zsh.d/*.zsh` that already touches it. Read `~/.zsh.d/workstation.zsh`, `~/.zsh.d/opencode-profiles.zsh` and the scripts they call. 2. **Decompose** by `screen-decomposition`: the scenario, the inventory, the screens and the questions. For the inventory, commands that already exist count; never write a second one for the same job (grep `~/.zsh.d`, the project, and `whence -a ` in zsh and bash). 3. **Name the commands.** Pick the facade name, a short alias, and `-help` forms (`ws`, `ws-help`, `workstation-help`; the user likes many aliases). Check every name for clashes: `zsh -ic 'whence -a '`, `bash -ic 'type -a '`, every `~/.zsh.d` file, the PATH. 4. **Write the plan** in the project's `docs/plans/-cli/plan.md` and open it with `review-open`: the map from step 2, the help screens drawn as markdown tables exactly as they will print, the command tree with aliases, the wiring, what you build yourself and what goes to a worker, the clashes found, and every judgment call you made with its reason. 5. **Short grill.** Ask only what is the user's to decide, one question at a time, each with your recommendation: the names they will type, any split of a list behind a new screen (the map's questions), any clash with an existing command. Usually 1 to 3 questions. Every other call you make yourself, and it is already in the plan. Then ask "build this?". Nothing is written before the yes. 6. **Build the CLI layer** (after the yes): - the script (Python, run with `python3 -I`, a docstring listing its commands, `fail()` writing `: ` to stderr and exiting 1 with the valid choices); - `help` drawn on a terminal, plain markdown when piped, reusing `~/projects/workstation/workstation-cli/terminal_links.py` (`draw_table`, `path_text`, `markdown_cell`) rather than new drawing code; - thin commands that only reach what exists (run a script, open a file with `review-open`, tail a log); - `zsh.d/.zsh` in the project repo: a header comment (what it is, that zsh and bash source it, where the help is), the facade intercepting `help` before anything else, the aliases; - the wiring: copy it to `~/.zsh.d/` (back up any file there first with `cp`), add one `[ -f "$HOME/.zsh.d/.zsh" ] && . "$HOME/.zsh.d/.zsh"` line to `~/.bashrc` (backup first); never edit `~/.zshrc`, its loop already sources `~/.zsh.d/*.zsh`. A command that needs new logic is not yours to write: write it up as a task for a worker (what, why, the intent row) and list it in your report. Write the script by `coding-guidelines`. 7. **Prove it** (`tank--bulletproof`): an intent at `.idd/modules/-cli/INTENT.md` with constraints and a Given / When / Then table naming each test; tests written first and seen failing, then passing. At least: every alias prints the table of contents, opening with its sentence and no breadcrumb; `help` after every noun, at every depth, prints that noun's menu, opening with the breadcrumb of its nouns and a sentence; `help` anywhere but last exits 1 and names the right form; every screen starts with its breadcrumb and sentence; every "what it's for" cell starts with a verb; piped output is plain markdown; on a terminal every path is a link to something that exists; an unknown command or category exits 1 and lists the valid ones; every thing in the inventory has a row (a new script, folder or command fails the test until it gets one). Then run the real thing in `zsh -ic` and `bash -ic` and paste what it printed. 8. **Record and ship.** A dated entry in `~/projects/workstation/README.md`, "System-wide changes" (what was wired, the backups, red and green). Commit and push as the git policy in the rules says, and give the hashes. For a project that is only an idea: steps 1 to 5 only. The plan is the map and the help as they will be; it is built once the project exists. When the project grows later, re-run steps 1 to 8 against the existing CLI: new things go into an existing group where they fit. A new group, or a split behind a new screen, is the user's call (step 5). ## Before you say it is done - `screen-decomposition`'s own checks pass on the map. - ` help` on a terminal and piped, side by side with `workstation help`: is it at least as clear? - Each name you added: `whence -a` shows only yours. - Each function you added: grep its noun again across `~/.zsh.d` and the project (the duplicate check, second run). - Every path on screen opens. - `help` after every noun prints its menu; `help` is never part of a breadcrumb; ` help` opens with only its sentence; `help` before a noun is an error that names the right form. ## References | File | Read it when | | --- | --- | | `references/house-conventions.md` | before step 4: what the two examples do, where, and why | | `references/cli-best-practices.md` | step 3 and step 6: naming, help, errors, output, exit codes | You are given a project (below, as a dump of its files; you cannot read anything else or run commands). Task: organize everything this project's user would want to reach into screens, the map a command line's help screens will be built from. Do the planning only: build nothing, and don't wait for answers. Where a decision is the user's to make, put it in "questions" with your recommendation. End your answer with the map as ONE fenced ```json block, in exactly this shape: {"screens": [{"path": ["noun", "..."], "sentence": "...", "rows": [{"name": "...", "form": "...", "what": "..."}]}], "questions": ["..."]} - "path": the nouns that lead to the screen, [] for the top screen. - "sentence": what the screen shows, in plain words. - "rows": what can be reached from that screen: "name" in plain words, "form" its technical form (a path, URL, port, command, or the screen it opens), "what" what it is for. # Project: workstation ## File tree (git ls-files) ``` ./: .gitconfig, .gitignore, README.md, cpu-min-power.sh, cpu-normal-power.sh, fix_old_monitor_hdmi.sh, linux-internet-recovery.sh, recover-tailscale-remote-terminal.sh .bdd/features/agent-framework/: agent-framework.feature .bdd/features/codex-browser/: real-browsing.feature .bdd/features/review-pane/: review-pane.feature .bdd/features/rules/: say-the-thing.feature .bdd/features/session-types/: session-types.feature .bdd/features/skills-sync-windows/: sync.feature .bdd/features/usage-guard/: usage-refresh.feature .bdd/features/usb-mouse/: acceptance.feature .bdd/qa/findings/: 2026-10-25-074028-say-the-thing-with_the_rule_no_reply_uses_a_code.md, 2026-10-25-074056-say-the-thing-without_the_rule_the_same_case_brings_out_a_code.md, 2026-10-25-112220-say-the-thing-with_the_rule_no_reply_uses_a_code.md, 2026-10-25-112244-say-the-thing-without_the_rule_the_same_case_brings_out_a_code.md .bdd/steps/: test_rules.py .idd/: project.intent.md .idd/modules/agent-framework/: INTENT.md .idd/modules/codex-browser/: INTENT.md .idd/modules/dashboard/: INTENT.md .idd/modules/dashboard-concepts/: INTENT.md .idd/modules/review-pane/: INTENT.md .idd/modules/rules/: INTENT.md .idd/modules/session-types/: INTENT.md .idd/modules/skills-sync-windows/: INTENT.md .idd/modules/usage-guard/: INTENT.md .idd/modules/usb-mouse/: INTENT.md agent-framework/: README.md, agent, agentkit.py, test_agentkit.py, test_server.py agent-framework/fixtures/: run-prd-writer-qa-agent.json agent-framework/sandbox/: index.html, server.py browser/: .gitignore, README.md, browser.sh, cli.mjs, open-logged-in.mjs, package-lock.json, ... (11 files) case-studies/blume-astryx/2026-09-16-signal-garden/: README.md case-studies/conceptual-modeling/2026-09-15-codebot-return/: README.md, provenance.json case-studies/conceptual-modeling/2026-09-15-codebot-return/images/: with-skill-return.png, with-skill-success.png, without-explicit-skill-return.png, without-explicit-skill-success.png case-studies/conceptual-modeling/2026-09-15-codebot-return/runs/: with-skill-image-requests.md, with-skill.md, without-explicit-skill-image-requests.md, without-explicit-skill.md case-studies/conceptual-modeling/2026-09-15-codebot-return/skill-snapshot/: SKILL.md, skills.json case-studies/conceptual-modeling/2026-09-15-codebot-return/skill-snapshot/references/: canonical-example.md, evaluation-scenarios.md, foundations.md chrome/: README.md, chrome.sh, flags, install.sh claude/: AGENTS.md, CLAUDE.md, communication-framework.md, settings.json, skills-shortlist.md claude/backups/: README.md claude/backups/desktop-v1-2026/: .gitattributes, AGENTS.md, CLAUDE.md, README.md claude/backups/desktop-v2-2026/: .gitattributes, AGENTS.md, CLAUDE.md, README.md, manifest.json claude/backups/desktop-v2-2026/docs/: coding.md, environment.md, projects.md, tools.md claude/backups/desktop-v2-2026/skills/tank--bulletproof/: SKILL.md, skills.json claude/backups/desktop-v2-2026/skills/tank--bulletproof/references/: behavioral-protocol.md, orchestration-workflow.md claude/backups/desktop-v2-2026/skills/volatility-based-skill-design/: SKILL.md claude/backups/desktop-v2-2026/skills/volatility-based-skill-design/agents/: openai.yaml claude/backups/linux-v1-2026-10-03/: .gitattributes, AGENTS.md, CLAUDE.md, README.md, manifest.json, supporting-files-before.json claude/hooks/: core-rules.sh, local-server-guard.py, machine-history.sh, proof-reminder.sh, team-activity.sh, test_core_rules.sh claude/linux-global/: AGENTS.md, CLAUDE.md, README.md, manifest.json claude/linux-global/docs/: coding.md, environment.md, projects.md, tools.md claude/linux-global/skills/tank--bulletproof/: SKILL.md, skills.json claude/linux-global/skills/tank--bulletproof/references/: behavioral-protocol.md, orchestration-workflow.md claude/linux-global/skills/volatility-based-skill-design/: SKILL.md claude/linux-global/skills/volatility-based-skill-design/agents/: openai.yaml claude/mods/changelog-pane/: README.md, tsconfig.json claude/mods/changelog-pane/.claude-plugin/: plugin.json claude/mods/changelog-pane/.claude-plugin/types/: .gitignore claude/mods/changelog-pane/hooks/: hooks.json, register.tsx claude/mods/changelog-pane/tests/: changelog.test.tsx claude/mods/changelog-pane/types/: index.d.ts claude/mods/review-pane/: README.md, tsconfig.json claude/mods/review-pane/.claude-plugin/: plugin.json claude/mods/review-pane/docs/design/2026-10-18-review-pane/: pitches.md, recommendation.md, research.md claude/mods/review-pane/docs/flows/2026-10-18/: flow-card.md claude/mods/review-pane/hooks/: doc.test.ts, doc.ts, editor.tsx, hooks.json, pane.test.tsx, register.tsx claude/mods/review-pane/types/: index.d.ts claude/mods/scratchpad-playground/: tsconfig.json claude/mods/scratchpad-playground/.claude-plugin/: plugin.json claude/mods/scratchpad-playground/hooks/: hooks.json, register.tsx claude/mods/scratchpad-playground/types/: index.d.ts claude/mods/team-board/.claude-plugin/: plugin.json claude/mods/team-board/hooks/: board.test.tsx, hooks.json, register.tsx claude/mods/team-board/types/: index.d.ts claude/session-types/: README.md, main-sessions.py, session-types.sh claude/session-types/docs/design/2026-10-21-changelog-on-timeline/: changelog_items.py, make-protos.py, pitch-a.md, pitch-b.md, pitch-c.md, proto-a.py, ... (12 files) claude/session-types/docs/design/2026-10-21-changelog-on-timeline/shots/: a-1-135x30.txt, a-1-210x58.txt, a-2-135x30.txt, a-2-210x58.txt, a-3-135x30.txt, a-3-210x58.txt, ... (26 files) claude/session-types/docs/design/2026-10-21-picker-views/: pitch-a.md, pitch-b.md, pitch-c.md, recommendation.md, render-mockups.py, research.md claude/session-types/tests/: run.sh claude/skills/: tech-ledger claude/skills/api-key-creation/: SKILL.md claude/skills/api-key-creation/references/providers/: nvidia.md claude/skills/clone-website/: SKILL.md claude/skills/contextual-value-product-thinking/: SKILL.md claude/skills/elad12390--web-research-assistant/: README.md, SETUP-NOTES.md, SKILL.md, pyproject.toml, tank.json claude/skills/elad12390--web-research-assistant/docs/: README.md claude/skills/elad12390--web-research-assistant/docs/new-features/: README.md claude/skills/elad12390--web-research-assistant/src/searxng_mcp/: __init__.py, api_docs.py, cache.py, changelog.py, comparison.py, config.py, ... (18 files) claude/skills/epic-fanout-planning/: SKILL.md claude/skills/impeccable/: SKILL.md claude/skills/impeccable/reference/: adapt.md, adapt.native.md, android.md, animate.md, audit.md, audit.native.md, ... (41 files) claude/skills/impeccable/reference/degraded/: asset-producer.md, documenter.md, finish-reviewer.md, manual-edit-applier.md claude/skills/impeccable/scripts/: VERSION, command-metadata.json, impeccable, impeccable.cmd, live-browser-dom.js, live-browser-ignores.js, ... (9 files) claude/skills/impeccable/scripts/data/: font-index-failures.json, font-index.json claude/skills/iterative-action-review/: SKILL.md claude/skills/lab-experiment/: SKILL.md claude/skills/mentor-mode/: SKILL.md claude/skills/mentor-mode/agents/: openai.yaml claude/skills/mentor-mode/assets/: mentor-runtime.css, mentor-runtime.js claude/skills/mentor-mode/references/: runtime.md, teaching.md claude/skills/mentor-mode/scripts/: prepare_mentor_page.py, serve_mentor.py claude/skills/post-feature-cleanup/: SKILL.md, skills.json claude/skills/post-feature-cleanup/references/: widget-pane-case.md claude/skills/powershell-launching/: SKILL.md claude/skills/reboot-resume/: SKILL.md claude/skills/resume-project/: SKILL.md claude/skills/resume-project/agents/: openai.yaml claude/skills/resume-project/assets/: mentor-report.css claude/skills/resume-project/references/: cli.md claude/skills/resume-project/scripts/: resume_project.py claude/skills/solaraai-content-calendar/: SKILL.md claude/skills/solaraai-deployment/: SKILL.md claude/skills/solaraai-deployment/references/: commands.md, services.md, workflows.md claude/skills/solaraai-design/: SKILL.md claude/skills/solaraai-design/references/: components.md, design-system.md claude/skills/solaraai-forms/: SKILL.md claude/skills/supabase/: CHANGELOG.md, SKILL.md claude/skills/supabase-postgres-best-practices/: CHANGELOG.md, SKILL.md claude/skills/supabase-postgres-best-practices/references/: _contributing.md, _sections.md, _template.md, advanced-full-text-search.md, advanced-jsonb-indexing.md, conn-idle-timeout.md, ... (34 files) claude/skills/supabase/assets/: feedback-issue-template.md claude/skills/supabase/references/: skill-feedback.md claude/skills/tank--communication-engineering/: SKILL.md claude/skills/tank--communication-engineering/references/: communication-smells.md, core-model.md, examples.md, information-gap-prioritization.md, software-engineering-principles.md claude/skills/tank--skill-creator/: SKILL.md, skills.json claude/skills/tank--skill-creator/references/: ecosystem-patterns.md, evaluation-workflow.md, quality-agents.md, research-workflow.md, skill-design-patterns.md, writing-conventions.md claude/skills/tank--skill-creator/scripts/: quick_validate.py claude/skills/tech-cv-writer/: SKILL.md, tank.json claude/skills/tech-cv-writer/references/: ats-architecture.md, bullet-formulas.md, keyword-strategy.md, latex-templates.md, linkedin-optimization.md, role-templates.md claude/team-park/: README.md, team_park.py, test_team_park.py claude/usage-guard/: .gitignore, Install-Windows.cmd, Install-Windows.ps1, Launcher.cs, README.md, claude, install.sh claude/usage-guard/.bdd/qa/resolutions/: 2026-10-03-stale-usage.md, 2026-10-04-request-budget.md claude/usage-guard/plugin/: .gitignore claude/usage-guard/plugin/.claude-plugin/: plugin.json claude/usage-guard/plugin/hooks/: hooks.json, register.js, shared-usage.py claude/usage-guard/tests/: live-refresh.py, test_request_budget.py claude/windows-global/: .gitattributes, CLAUDE.md claude/windows-global/docs/: coding.md, environment.md, projects.md, tools.md clipstack/: install.sh, picker.py, server.py, test_server.py, watcher.py clipstack/units/: clipstack-server.service, clipstack-watcher.service clipstack/windows/: INTENT.md, clipstack.ahk, clipstack.feature, install.ps1, uninstall.ps1, verify.ps1 clipstack/windows/tests/: run-tests.ps1 codex/: config.toml codex/browser/: README.md, tab-recorder.mjs, tab-recorder.test.mjs codex/browser/tab-recorder-extension/: README.md, extension.test.mjs, manifest.json, offscreen.html, offscreen.js, recording-store.mjs, ... (11 files) codex/chrome-bridge/: Install-CodexChromeBridge.cmd, Install-CodexChromeBridge.ps1, README.md, codex-chrome-bridge.path, codex-chrome-bridge.service, codex-chrome-bridge.timer, install.sh, repair.mjs codex/playwright-mcp/: README.md copy/: 1-today.webp, 2-subsystems.webp, 3-reviews.webp cv/: .gitignore, README.md, WORKFLOW.md, cv-ai-full-stack.pdf, cv-ai-full-stack.tex, cv-ai-integrations.pdf, ... (16 files) cv/design/: build-design.py, cv-ai-full-stack.html, cv-ai-full-stack.pdf cv/text/: build-full.sh, cv-ai-full-stack.full.txt, cv-ai-full-stack.variables.txt, cv-ai-integrations.full.txt, cv-ai-integrations.variables.txt, cv-full-stack.full.txt, cv-full-stack.variables.txt, make-text.py cv/versions/2026-10-04/: Liel-Ben-Or-CV-2026-10-04.pdf, Liel-Ben-Or-CV-2026-10-04.txt, Liel-Ben-Or-CV-2026-10-04.variables.txt cv/versions/2026-10-04-v2/: Liel-Ben-Or-CV-2026-10-04-v2.pdf, Liel-Ben-Or-CV-2026-10-04-v2.txt, Liel-Ben-Or-CV-2026-10-04-v2.variables.txt dashboard/: README.md, index.html, server.py, snapshot.py, test_dashboard.py, test_page.py dashboard-concepts/: README.md, index.html, server.py, test_concepts.py dashboard/fonts/: IBMPlexMono-Medium.ttf, IBMPlexMono-Regular.ttf, IBMPlexSans-Medium.ttf, IBMPlexSans-Regular.ttf, IBMPlexSans-SemiBold.ttf, IBMPlexSansHebrew-Regular.ttf, IBMPlexSansHebrew-SemiBold.ttf, OFL.txt dashboard/shots/: areas.webp, reviews-checks.webp, reviews-codebot-v1-verdicts.webp, reviews-fixes.webp, reviews-timeline.webp, reviews-verdicts.webp, reviews.webp, today.webp deskflow/: .gitignore, NETWORK-AUDIT.md, README.md, deskflow-lockdown.nft, deskflow.service, linux.conf, ... (9 files) deskflow/deskflow.service.d/: keyboard-layout.conf deskflow/usb-mouse/: .gitignore, 70-deskflow-focus.rules, README.md, VERIFICATION.md, deskflow-focus.service, deskflow-usb-mouse.service, ... (26 files) docs/changelog/: 2026-10-17-patch-10.17.md, 2026-10-17-sample-patch.md docs/changelog/assets/: admin.svg, banner.svg, researcher.svg, spawner.svg, supervisor.svg, worker.svg docs/design-references/: 2026-10-13-dashboard-polish.html docs/design-references/2026-10-13/pitch-a/: mock.html docs/design-references/2026-10-13/pitch-a/screens/: 1-today.png, 2-subsystems.png, 3-reviews.png, 4-today-panel.png docs/design-references/2026-10-13/pitch-b/: mock.html docs/design-references/2026-10-13/pitch-b/screens/: 1-today.png, 2-subsystems.png, 3-reviews.png, 4-subsystems-panel.png docs/design-references/2026-10-13/pitch-c/: mock.html docs/design-references/2026-10-13/pitch-c/screens/: 1-today.png, 2-subsystems.png, 3-reviews.png, 4-reviews-panel.png docs/design/2026-10-17-dashboard/: common.js, data.js, data.json, recommendation.md, research.md, snapshot.py docs/design/2026-10-17-dashboard/pitch-a/: index.html, pitch.md docs/design/2026-10-17-dashboard/pitch-b/: index.html, pitch.md docs/design/2026-10-17-dashboard/pitch-c/: index.html, pitch.md docs/design/2026-10-17-dashboard/round-2/: app.js, pitches.md, recommendation.md docs/design/2026-10-17-dashboard/round-2/pane/: index.html, mockups.py, pitch-1.txt, pitch-2.txt, pitch-3.txt, pitches.md, recommendation.md docs/design/2026-10-17-dashboard/round-2/pitch-a/: index.html docs/design/2026-10-17-dashboard/round-2/pitch-b/: index.html docs/design/2026-10-17-dashboard/round-2/pitch-c/: index.html docs/design/2026-10-17-dashboard/round-3/: pitches.md, reader.css, reader.js, recommendation.md, research.md docs/design/2026-10-17-dashboard/round-3/pitch-1/: index.html docs/design/2026-10-17-dashboard/round-3/pitch-2/: index.html docs/design/2026-10-17-dashboard/round-3/pitch-3/: index.html docs/design/2026-10-21-waiting/: build.py, data.json, pitches.md, recommendation.md, research.md, windows-check.md docs/design/2026-10-21-waiting/built/: index.html docs/design/2026-10-21-waiting/pitch-a/: index.html docs/design/2026-10-21-waiting/pitch-b/: index.html docs/design/2026-10-21-waiting/pitch-c/: index.html docs/design/2026-10-22-agent-sandbox/: pitch-a-main.png, pitch-a-second.png, pitch-a.md, pitch-b-main.png, pitch-b-second.png, pitch-b.md, ... (11 files) docs/design/2026-10-22-agent-sandbox-v2/: pitch-a-main.png, pitch-a-second.png, pitch-a.md, pitch-b-main.png, pitch-b-second.png, pitch-b.md, ... (11 files) docs/design/2026-10-22-agent-sandbox-v2/prompts/: a-main.txt, a-second.txt, b-main.txt, b-second.txt, c-main.txt, c-second.txt, ... (14 files) docs/design/2026-10-22-agent-sandbox-v2/rejected/: pitch-a-second-try1.png, pitch-b-main-try1.png, pitch-c-main-try1.png, pitch-c-second-try1.png, v1-permanent-panel-pitch-a-main.png, v1-permanent-panel-pitch-b-second.png docs/design/2026-10-22-agent-sandbox/prompts/: a-main.txt, a-second.txt, b-main.txt, b-second.txt, c-main.txt, c-second.txt, ... (14 files) docs/design/2026-10-22-agent-sandbox/rejected/: pitch-b-second-try1.png, pitch-c-main-try1.png docs/flows/2026-10-13/: flow-card.md, mock.html, screens, screens, screens docs/flows/2026-10-13/screens/: 1-today.webp, 2-areas.webp, 3-reviews.webp docs/flows/2026-10-17/: data-model.md, flow-card.md, model.md, team-overview-flow-card.md, working-notes.md docs/flows/2026-10-17/baseline/: areas.png, changelog-top.png, reviews.png, today.png docs/flows/2026-10-22-agent-sandbox/: data-model.md, flow-card.md docs/flows/2026-10-23/: scratchpad-takes-items.md docs/functional-research/2026-10-21/: agency-agents.md, agno.md, baseline.md, claude-code-subagents.md, crewai.md, features.md, ... (9 files) docs/items/: planned.item.md, urgent.item.md, work.item.md docs/plans/: 2026-10-23-opencode-profiles-everywhere.md docs/plans/2026-10-22-agent-sandbox/: prd.html docs/plans/2026-10-23-one-rule-list/: plan.md docs/plans/2026-10-24-claude-personas/: plan.md docs/plans/2026-10-24-filesystem-order/: log.md, move-repo.py, plan.md, systemctl_stub.py, test_move_repo.py docs/plans/2026-10-24-rules-per-role/: plan.md docs/plans/2026-10-24-rules-per-role/reminder/: open-plan.sh, rules-roles-reminder.service, rules-roles-reminder.timer docs/plans/2026-10-25-editable-plan-page/: plan.md docs/plans/2026-10-25-hook-prints-rules/: plan.md docs/plans/2026-10-25-project-task-state/: plan.md docs/plans/2026-10-25-workstation-on-bulletproof/: plan.md, rule-sort.md docs/plans/2026-10-26-cli-engineer-agent/: plan.md docs/plans/2026-10-26-sessions-any-program/: plan.md docs/plans/2026-10-26-shared-clipboard/: plan.md docs/plans/2026-10-26-workstation-intent/: plan.md docs/plans/2026-10-26-workstation-projects/: plan.md docs/playbooks/: talk-while-team-builds.md docs/research/2026-10-25-phase-checks/: research.md docs/research/2026-10-25-phase-goals/: research.md docs/research/2026-10-26-failed-check/: research.md docs/research/2026-10-26-phase1-check-test/: build.py, research.md, run1.sh, run2.sh docs/research/2026-10-26-phase1-check-test/cases/: hook-gap.cut.md, hook-gap.goal.txt, hook-gap.kept.md, hook.cut.md, hook.goal.txt, hook.kept.md, ... (18 files) docs/research/2026-10-26-phase1-check-test/heldout/cases/: fs-gap.cut.md, fs-gap.goal.txt, fs-gap.kept.md, fs.cut.md, fs.goal.txt, fs.kept.md, ... (12 files) docs/research/2026-10-26-phase1-check-test/heldout/old/: fs-gap.t1.judge.out, fs-gap.t1.judge.prompt, fs-gap.t1.r1.out, fs-gap.t1.r1.prompt, fs-gap.t1.r2.out, fs-gap.t1.r2.prompt, ... (96 files) docs/research/2026-10-26-phase1-check-test/heldout/out/: fs-gap.t1.r1.out, fs-gap.t1.r1.prompt, fs-gap.t1.r2.out, fs-gap.t1.r2.prompt, fs-gap.t1.r3.out, fs-gap.t1.r3.prompt, ... (96 files) docs/research/2026-10-26-phase1-check-test/out/: hook-gap.cut.t1.judge.out, hook-gap.cut.t1.r1.out, hook-gap.cut.t1.r2.out, hook-gap.cut.t1.r3.out, hook-gap.cut.t1.strict.out, hook-gap.cut.t2.judge.out, ... (180 files) docs/research/2026-10-26-phase1-check-test/out2/: hook-gap.cut.t1.r1.out, hook-gap.cut.t1.r1.prompt, hook-gap.cut.t1.r2.out, hook-gap.cut.t1.r2.prompt, hook-gap.cut.t1.r3.out, hook-gap.cut.t1.r3.prompt, ... (144 files) docs/research/2026-10-26-phase1-check-test/out3/: hook-gap.cut.t1.r1.out, hook-gap.cut.t1.r1.prompt, hook-gap.cut.t1.r2.out, hook-gap.cut.t1.r2.prompt, hook-gap.cut.t1.r3.out, hook-gap.cut.t1.r3.prompt, ... (144 files) docs/research/2026-10-26-phase1-check-test/prompts/: lenient-judge.example.prompt, reader.example.prompt, strict-judge.example.prompt docs/research/2026-10-26-proven-methods/: research.md docs/roles/: qa-agent.md docs/roles/drafts-2026-10-23/: README.md docs/roles/drafts-2026-10-23/.old/admin/: SKILL.md docs/roles/drafts-2026-10-23/.old/qa-agent/: SKILL.md docs/roles/drafts-2026-10-23/.old/supervisor/: SKILL.md docs/roles/drafts-2026-10-23/.old/worker/: SKILL.md docs/roles/drafts-2026-10-23/admin/: SKILL.md, agent.yaml docs/roles/drafts-2026-10-23/qa-agent/: SKILL.md, agent.yaml docs/roles/drafts-2026-10-23/supervisor/: SKILL.md, agent.yaml docs/roles/drafts-2026-10-23/test/: cases.json, rejudge.py, results2.txt, run.py docs/roles/drafts-2026-10-23/worker/: SKILL.md, agent.yaml docs/superpowers/plans/: 2026-10-03-claude-usage-guard.md git-hooks/: commit-msg, pre-commit, pre-push, prepare-commit-msg, scenario-gate.py hermes/: BACKUP-2026-10-02.md, README.md, RESTORE.md, default.config.example.yaml, jobs.config.example.yaml, zprofile-path.zsh init-windows/: .gitignore, Export-Windows.ps1, Install-Windows.ps1, README.md, Remove-WindowsPack.ps1, Smoke-Test-Windows.ps1, ... (11 files) init-windows/configs/git/: .gitconfig init-windows/configs/vscode/: keybindings.json, settings.json init-windows/configs/vscode/snippets/: typescriptreact.json init-windows/lib/: Chrome.ps1, Files.ps1, Mongo.ps1, Node.ps1, Pack.Common.ps1, VSCode.ps1, Winget.ps1 init-windows/logs/: Install-Windows.errors.log, Install-Windows.log init-windows/manifests/: managed-files.json, node.json, programs.json, vscode-extensions.txt init-windows/user-scripts/: do_hibernate.ps1, fix_touchpad.ps1, fix_touchpad2.ps1, fix_touchpad3.ps1, restore-mongo.ps1 jev-browser-test/: README.md, cli.py, env.example, install.sh, instructions.md, jev-browser-test, jev-ultrafast.patch, runtime.py lan-mouse/: README.md, lan-mouse-controller.desktop, lan-mouse-controller.py, linux-status.md, linux.config.toml, windows-status.md, windows.config.toml laptop-utilities/: keep-running-with-lid-closed.sh, restore-default-lid-behavior.sh opencode-profiles/: profiles.py, test_profiles.py opencode-profiles/private-leb-experimental/: CLAUDE.md, claude-settings.json, claude-settings.local.json, opencode.json reference/: README.md reference/incidents/: 2026-10-01-codebot-lid-closed.md repos/: Clone-BetecRepos.ps1 skills-sync-windows/: README.md, Sync-Skills.ps1, Test-Account.ps1, Test-Sync.ps1, verification.md supabase-keepalive/: install.sh, supabase-keepalive.service, supabase-keepalive.sh, supabase-keepalive.timer workboard/: rules, rules-meta.yaml, rules.yaml, test_org_folder.py, test_rules.py zsh.d/: api-keys.zsh, dash-path-warn.zsh, git-safety.zsh, infra.zsh, opencode-profiles.zsh, review-open.zsh, rules.zsh, utils.zsh ``` ## File: README.md (its sections) ``` # workstation One developer's workstation: working documents, CVs, config, scripts, agent setup and small tools, kept together in one private repo for ongoing work, version history and recovery. (Formerly `Lebnor/scripts`, renamed because it grew past scripts.) Nothing here installs itself. Files are **copies** you place where they belong (see [Where things land](#where-things-land)), and each folder explains its own use. ## Where things land | In this repo | On the machine | | --- | --- | | `.gitconfig` | `~/.gitconfig` | | `zsh.d/*.zsh` | `~/.zsh.d/` (`~/.zshrc` sources every `~/.zsh.d/*.zsh`) | | `zsh.d/review-open.zsh` | also `~/.local/bin/review-open`, a 3-line zsh wrapper that sources it, for bash and agents | | `workstation-cli/workstation.py` | run in place by `zsh.d/workstation.zsh` | | `git-hooks/*` | `~/.git-hooks/` (`.gitconfig` sets `core.hooksPath` there) | | `claude/hooks/machine-history.sh` | `~/.claude/hooks/` (wired in `~/.claude/settings.json`) | | `claude/hooks/core-rules.sh` | `~/.claude/hooks/` (wired in `~/.claude/settings.json`, SessionStart and PreToolUse Bash) | | `claude/hooks/team-activity.sh` | `~/.claude/hooks/` (wired in `~/.claude/settings.json`) | | `claude/hooks/local-server-guard.py` | `~/.claude/hooks/` (wired in `~/.claude/settings.json`, PreToolUse on Bash) | | `claude/hooks/proof-reminder.sh` | `~/.claude/hooks/` (wired in `~/.claude/settings.json`, PostToolUse on Edit, MultiEdit, Write, Bash) | | `workboard/rules.yaml` | read by `workboard/rules`; `~/.claude/references/rules.md` is generated from it | | `claude/session-types/session-types.sh` | `~/.claude/hooks/session-types.sh` (a `SessionStart` hook in `~/.claude/settings.json`) | | `claude/session-types/main-sessions.py` | `~/.claude/hooks/main-sessions.py` (the wrapper runs it for `claude --main -c` and `-r`) | | `claude/usage-guard/claude` | `~/bin/claude`: the `claude` command on PATH is this wrapper, ahead of the native `~/.local/bin/claude` (installed by `claude/usage-guard/install.sh`) | | `claude/team-park/team_park.py` | `~/.local/bin/team-park` | | `claude/CLAUDE.md`, `claude/settings.json` | `%USERPROFILE%\.claude\` (deployed by `init-windows`) | | `claude/skills/*` | `~/.claude/skills/` (backups; copy in the ones you want installed) | | `claude/AGENTS.md` | `%USERPROFILE%\AGENTS.md` (deployed by `init-windows`) | | `codex/config.toml` | `%USERPROFILE%\.codex\config.toml` (deployed by `init-windows`) | | `init-windows/user-scripts/*` | `%USERPROFILE%\Scripts\` (deployed by `init-windows`) | | `deskflow/linux.conf`, `deskflow/server.conf` | `~/.config/Deskflow/Deskflow.conf`, `server.conf` | | `deskflow/deskflow.service` | `~/.config/systemd/user/deskflow.service` | | `deskflow/windows.conf`, `deskflow/windows-service.conf` | Separate client/service settings; see [Deskflow paths](deskflow/README.md#repository-copies-and-restore-boundaries) | | `lan-mouse/windows.config.toml` | `%LOCALAPPDATA%\lan-mouse\config.toml` (copy and pair locally) | | `lan-mouse/linux.config.toml` | `${XDG_CONFIG_HOME:-$HOME/.config}/lan-mouse/config.toml` (copy and pair locally) | The Linux machine's own global agent files (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.claude/settings.json`, `~/.codex/config.toml`) are separate files. The installed Linux instruction files are mirrored in [`claude/linux-global/`](claude/linux-global/); settings and config remain machine-local. The Windows desktop's installed `CLAUDE.md` and its four `docs/` files are mirrored the same way in [`claude/windows-global/`](claude/windows-global/) (a copy of `%USERPROFILE%\.claude\`; `claude/CLAUDE.md` above is a different file). ## Shell and git (Linux) - **`.gitconfig`** sets the author identity, Git LFS, the `store` credential helper, a large `http.postBuffer`, and `core.hooksPath = ~/.git-hooks`. - **`zsh.d/`** is split by topic. `git-safety.zsh` wraps `git checkout` so it lists the files and asks `[y/N]` before discarding unstaged changes. `infra.zsh` holds Docker/Compose shortcuts, Prisma and Postgres helpers, nginx and VPN commands. `utils.zsh` holds terminal helpers (`set-title`, `killport`), IP aliases, lazy-loaded `nvm`/`node`/`npm`/`npx`, Android/Java and Bun setup, and repair helpers (`fix-keyboard`, `fix-mouse`, `fix-disk`, `fix-whatsapp`). `api-keys.zsh` exports the general-use API keys kept in `~/.config/api-keys/env` (never in Git); `api-keys-edit` opens it. `opencode-profiles.zsh` (also sourced by `~/.bashrc`) runs `opencode` and `oc` with the current OpenCode profile (`opencode-profiles/`): `opencode-profile` names it, `opencode-profiles` shows what each one loads, `opencode-switch ` switches every shell's new runs, `opencode-login` signs a profile's Claude Code in, `opencode-files` lists the current profile's files and `opencode-edit ` opens one. `opencode help` (also `oc help`, `opencode-help`, `oc-help`) shows every profile's files, one column per profile, and the commands; with more than 3 profiles it writes them to `~/.opencode-profiles/help.md` and opens it. `workstation.zsh` (also sourced by `~/.bashrc`) gives `workstation`, `setup` and `ws`, one command for this kit all of them, drawn on a terminal, plain markdown when piped. On a terminal, both help pages print every link and path white and underlined, as a link that opens it (`workstation-cli/terminal_links.py`). - **`git-hooks/`** are generated [Lefthook](https://github.com/evilmartians/lefthook) shims. Because `core.hooksPath` is global, they run in every repo. They need `lefthook` on the PATH (or in a project's `node_modules`); without it you'll see "Can't find lefthook in PATH" on each git action, though commits still go through. `pre-push` also holds the push gates (approval note, 2026-10-17; nothing to main in a repo marked `team.gitpolicy pull-request`, 2026-10-18) and `commit-msg` the commit gate (nothing committed on main in a marked repo). They were added by hand at the top, before the `LEFTHOOK=0` early exit, so that variable cannot skip them: a `lefthook install` would overwrite them, so add them back after one. ## Machine utilities (Linux) | Script | What it does | Notes | | --- | --- | --- | | `cpu-min-power.sh` | `power-saver` profile, turbo off, CPU capped at 8% of max | Intel P-state only; asks for sudo | | `cpu-normal-power.sh` | `balanced` profile, turbo on, cap back to 100% | Same requirements | | `fix_old_monitor_hdmi.sh` | Sets a mode/refresh rate on the external HDMI/DP output with `xrandr` (default `1920x1080` at `59.88`) | `--output`, `--mode`, `--rate`, `--quiet`; picks the first external output if none given | | `linux-internet-recovery.sh` | Enables `systemd-resolved`, points `/etc/resolv.conf` at it, restarts NetworkManager, flushes DNS, cycles networking | Re-runs itself with sudo | | `recover-tailscale-remote-terminal.sh` | Repairs DNS, restarts `tailscaled`, waits up to 30 s for reconnect, then starts the `remote-terminal` user service and checks port 3500 | Run as your normal user; the Tailscale hostname is hardcoded to this machine | | `laptop-utilities/keep-running-with-lid-closed.sh` | Writes a `logind` drop-in so closing the lid does nothing | Applies after a reboot; keep it ventilated | | `laptop-utilities/restore-default-lid-behavior.sh` | Removes that drop-in | Applies after a reboot | ## AI assistant setup `claude/` and `codex/` hold the assistant setup that `init-windows` deploys to Windows. The Linux machine's installed instructions are mirrored in [`claude/linux-global/`](claude/linux-global/). The global agent files point skill-design work to the custom [`volatility-based-skill-design`](https://github.com/Lebnor/my-skills/tree/master/volatility-based-skill-design) skill. It defines volatility boundaries and requires every created or restructured skill to declare its `metadata.usage-tier` from `junior` through `me`. `codex/chrome-bridge/` maintains the Chrome plugin's `latest` link when it goes missing or points to a removed version, and reapplies the narrow local `file:` navigation-policy patch used by Browser Use. On Linux, `install.sh` installs a systemd user watcher and timer. On Windows, `Install-CodexChromeBridge.cmd` (or its PowerShell script) installs a current-user Scheduled Task. Each machine patches its own local Codex/Chrome cache; generated vendor-cache files are not copied between machines. See the folder README for installation and restart requirements. [`codex/browser/`](codex/browser/) documents Codex's direct Chrome command path and its live verification. The previous `codex/playwright-mcp/` setup is retired; it does not install a browser server anymore. - `claude/CLAUDE.md` — global rules (browser automation, communication style, research protocol, how to present work). `claude/AGENTS.md` — the shorter global agent notes. - `claude/settings.json` — Claude Code settings. `codex/config.toml` — Codex CLI config. - [Desktop v2 2026 instruction package](claude/backups/desktop-v2-2026/) is a portable snapshot of the Windows desktop's global AGENTS.md and CLAUDE.md, their four supporting docs, and two supporting skills. Read its README to inspect or manually restore the package; it does not install or load automatically. - `claude/communication-framework.md` — design notes, **a draft that isn't enforced anywhere yet**. - `claude/skills-shortlist.md` — skills researched on skills.sh; its own header records what is installed. - Global skills live in [`Lebnor/my-skills`](https://github.com/Lebnor/my-skills) (`/home/liel/projects/my-skills`), linked by `install.sh` into the folders in its `skill_targets` (`~/.claude/skills`, `~/.codex/skills`, `~/.config/opencode/skills`; `~/.agents/skills` holds older links and gets no new skills). No project-level skills. This list only points there; the copies are not stored here: | Skill (in `my-skills`) | Purpose | | --- | --- | | `supabase` | Supabase's own skill: Auth, RLS, `supabase-js`/`@supabase/ssr`, migrations, CLI, debugging | | `supabase-postgres-best-practices` | Supabase's Postgres performance rules (MIT) | | `clone-website` | Reverse-engineer and clone websites with parallel builder agents | | `lab-experiment` | How to run an experiment in `/home/liel/projects/ai-lab` | | `coding-guidelines` | House coding rules: lean code, reuse before writing, no normalization sprawl, component file order | | `volatility-based-decomposition` | Decompose systems around independently changing decisions (architect tier) | | `working-with-windows` | Windows gotchas for Node MCP servers that call PowerShell | | `solaraai-content-calendar`, `solaraai-deployment`, `solaraai-design`, `solaraai-forms` | SolaraAI platform: content calendar, deploy flow, design system, form behavior | - `claude/skills/` — backups of skills that are kept here: | Skill | Purpose | | --- | --- | | `contextual-value-product-thinking` | Analyze products and startup ideas through contextual human values | | `elad12390--web-research-assistant` | Web research MCP server (search, crawling, stealth scraping, package/GitHub lookups, docs discovery), hosted on liel-windows; when to use it and its setup: `SETUP-NOTES.md` there | | `epic-fanout-planning` | 10-step pattern for QA-gap-driven epics with parallel-agent fan-out and merge/release gates | | `impeccable` | Frontend design skill (pbakaus/impeccable v4.5.0, Apache-2.0): shape, critique, audit, polish; the engine binary downloads on first run, not stored here | | `api-key-creation` | Orchestrator troubleshooting (admin tier): get a missing API key with browser tools instead of escalating to the user | | `iterative-action-review` | Review a completed real-world action as one iteration in a series | | `post-feature-cleanup` | The pass after writing code: UI defects the builder misses, code leftovers, verification that can lie, repo hygiene | | `powershell-launching` | Launch PowerShell or a new terminal window on Windows | | `reboot-resume` | Preserve and resume work across a reboot or a Claude Code restart | | `tank--communication-engineering` | Apply engineering discipline to what an agent says and how much | | `tank--skill-creator` | Create new skills | | `tech-ledger` | Read and write the betec Tech Ledger of evaluated tech | Heads-up: `init-windows` deploys `claude/CLAUDE.md`, `claude/AGENTS.md`, `claude/settings.json` and `codex/config.toml` by relative path (`../claude/...`), so those files must stay where they are. ### Agent system Where the skills, roles, global rules and decision data live. Paths checked 2026-10-09. | Thing | Source of truth | Installed or linked at | | --- | --- | --- | | Skills | `~/projects/my-skills//SKILL.md` | symlinks in `~/.claude/skills`, `~/.codex/skills`, `~/.agents/skills` | | Agent records | `~/projects/my-skills/agents//agent.yaml` (typed: `.idd/modules/agent-framework/INTENT.md`, K1), with the agent's situations, saved tests (`evals/`) and, for agents outside a team, its role skill (`skills//`). Results in `~/projects/data//eval-results/`, memory in `~/projects/data//memory/` | not linked as skills; checked by `agent-framework/agent check`, tested in the Agent Sandbox (`agent serve`) | | Roles | Role skills: `~/projects/my-skills/{worker,supervisor,admin,qa-agent}/SKILL.md` (`qa-agent`: 2026-10-18, one for the machine, not started by any team file yet); the researcher uses `functional-research`. OpenCode agents for worker, supervisor, admin and researcher: `my-skills/agents//opencode.md` (2026-10-23). Claude personas for worker, supervisor, researcher, admin and qa-agent: `my-skills/agents//claude.md` (2026-10-24) | each member's first message names its role skill, and Claude members start with `--agent ` (`coordinated-agentic-session/references/runtimes.md`); `my-skills/install.sh` links OpenCode agents as `~/.config/opencode/agent/.md` and personas as `~/.claude/agents/.md` | | Starting a team | `~/projects/my-skills/spawn-team/SKILL.md` (tier `mid-level`), team files in `spawn-team/teams/` (`worker-pair.md`, `research-team.md`) | one spawner for Claude and Codex; every team gets an admin; a new team is a new team file. `/spawn-team ` (Claude), `$spawn-team ` (Codex) | | How team members talk | `~/projects/my-skills/coordinated-agentic-session/` (tier `junior`): `references/handoff.md` (rules), `references/runtimes.md` (Claude vs Codex tools) | the runtime's own tools only: Claude `SendMessage`, Codex `multi_agent_v2` tools (`followup_task` and others); no scripts, no `codex queue` | | Codex agent tools | `multi_agent_v2 = true` under `[features]` in `~/.codex/config.toml` (machine-local) | turned on 2026-10-09 | | Rules (every org, the escalation policy among them) | `workboard/rules.yaml`, metadata in `workboard/rules-meta.yaml`; changed only by the user or an accepted rule proposal (R43) | printed by `rules [folder]` (`~/.local/bin/rules`); line 1 of `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md` (facts only now, mirrored in `claude/linux-global/`) tells every session to run it | | Cases (questions, decided alone), rule proposals, verdicts, troubleshooting, design and functional items, approach reviews, team reviews | `~/projects/data/` (private repo `Lebnor/data`) | agents use `~/projects/data//` directly; projects get no `data` link | | Answer sync | `~/projects/data/bin/{issue,pull,sync}` and `~/projects/data/systemd/data-pull.*` | `~/.config/systemd/user/`, every 5 minutes | | Supervision backlog | `~/projects/betec/workboard/docs/supervision-backlog.md` | | | Archive | `~/archive/` (not a repo, not backed up); layout in `~/archive/README.md` | files moved out of projects, each folder with an `ARCHIVE.md` saying where it came from; agents' test evidence goes here | ## Browser CLI `browser/` is the `browser` command: a thin client plus a small background server that keeps one real Chrome window open across calls, so login state and page state survive between commands. It exists because MCP browser tools kept disconnecting mid-session. **Recording a feature (proof):** use `recordStart` / `recordStop`. That is the one supported way; it replaces the older Codex recorders in `codex/browser/` for everything the `browser` command can drive. How: [`browser/README.md`](browser/README.md), "Recording proof". Why Chrome starts the way it does: [`chrome/README.md`](chrome/README.md). ```bash cd browser && npm install && npm link # once per machine browser '[{"action":"goto","url":"https://example.com"},{"action":"screenshot","path":"/tmp/a.webp"}]' browser status # is the background server up? browser close # close Chrome and stop the server ``` Everything else (actions, viewport presets, annotating, network capture, login gotchas) is in [`browser/README.md`](browser/README.md). **Chrome itself** is started only through `chrome/chrome.sh` (a launch flag lets agents record proof of a feature with no prompt). Do not start the real Chrome by hand; see [`chrome/README.md`](chrome/README.md). ## Behavioral browser smoke QA [`jev-browser-test/`](jev-browser-test/) runs a goal against a browser and reports only its supplied text and URL assertions. Its own README covers the shared Liel Chrome profile, isolated mode, privacy boundary, exit codes, and the canonical Linux agent snippet. ## Windows bootstrap `init-windows/` rebuilds a Windows dev environment from exact, reviewable manifests (programs, Node versions and global packages, VS Code extensions and settings, Git config, user scripts). It is not an OS image, a file backup, or a credential backup. - Install: extract the repo on Windows, open `init-windows`, run `Start-Install.cmd`. - Check: `Smoke-Test-Windows.ps1` / `Verify-Windows.ps1`. Roll back: `Remove-WindowsPack.ps1`. - Inventory of what was captured: `inventory.md`. Sign-ins to redo by hand: `secrets-checklist.md`. - Full guide: [`init-windows/README.md`](init-windows/README.md). ## Cloning the work repos `repos/Clone-BetecRepos.ps1` clones every repository in the standard Betec workspace layout that is missing locally, and leaves existing folders alone, so it is safe to re-run. Its list mirrors the `betec-workboard` docs; update them together when the layout changes. ## Case studies Archived, human-reviewed experiments, one folder each, named `case-studies///` with its own `README.md`. - `conceptual-modeling/2026-09-15-codebot-return` — the same design request run with and without the `conceptual-modeling` skill; the skill-guided run was judged materially better. Includes prompts, run records, images and a snapshot of the skill. - `blume-astryx/2026-09-16-signal-garden` — a small interactive documentation exhibit that separates durable explanation (Blume) from the live interface (Astryx). - `/home/liel/projects/ai-lab/experiments/2026-10-08-kernel-use-cases/insights/RESULTS.md` — Kernel cloud browsers: use cases, speed vs local Chrome, and session recording, tested live (2026-10-08). ## Conventions and gotchas - **Copies, not links.** Repo and machine copies drift. To see how far, diff a pair, e.g. `diff zsh.d/utils.zsh ~/.zsh.d/utils.zsh`, then decide which side wins. - **Known issue: credentials in `zsh.d/`.** `infra.zsh` (Prisma init, `git_pull_with_creds`) and `utils.zsh` (`update-gitlab-token`) embed a credential in git URLs. `init-windows/secrets-checklist.md` already says to treat it as compromised: rotate it and move to a credential manager. Everything else follows the rule: keys, tokens, `.env` files and browser profiles stay out of Git, and that checklist lists what to sign in to again. - **Machine-specific on purpose.** Paths like `/home/liel`, the Tailscale hostname, and the Intel-only CPU scripts are not portable as-is. - **New things follow the existing pattern.** A shell helper goes in `zsh.d/`; a one-off Linux fix is a root script named for the action (hardware or power-related ones in `laptop-utilities/`); agent behavior goes in `claude/` or `codex/`; a tool with its own dependencies gets its own folder and README; experiments with evidence go in `case-studies/`. - **Renamed from `scripts`.** GitHub redirects the old URL. To repoint an old clone: `git remote set-url origin https://github.com/Lebnor/workstation.git`. - 2026-10-23: `audio-share` (`audio-share/`, `zsh.d/audio-share.zsh`, sourced from `~/.bashrc` too): `audio-start` / `audio-pause` (or `audio-share on|off|status|tone`) send all Linux audio to the Windows machine over Tailscale (null sink `windows_share` as default output, its monitor served as raw PCM on tcp 4953) and restore the speakers on pause. Runtime only; the Windows `ffplay` reconnect loop is run by the `windows-audio-share` agent. ``` ## File: agent-framework/README.md ``` # Agent framework and Agent Sandbox An Agent is a typed record (`agent.yaml`), checked before any session starts. The Agent Sandbox page (named after Deadlock's sandbox mode; runs are real sessions, see below): pick an agent, change anything about its setup at any time, type and press Ask. Nothing is locked and nothing has to happen in an order. Intent and rules: [`.idd/modules/agent-framework/INTENT.md`](../.idd/modules/agent-framework/INTENT.md). PRD and mockups: [`../docs/plans/2026-10-22-agent-sandbox/prd.html`](../docs/plans/2026-10-22-agent-sandbox/prd.html). How the page works: one conversation. The setup is one line in the header (click it to change the agent, model, effort, folder, rules, memory, skill versions or tools; the next message uses it). The right panel, "Did it react right?", is about the message you clicked: your expectations passed or failed with the step or sentence that decided each, what it did (tools grouped, a skill load named by its skill, one target each), the calls that failed ("Refused permission" vs "Did not work"). With two or more answers to one message it shows only what differs, or "Reacted the same." "Every step, in order" (closed) holds the raw steps. In the left column, "Expectations", you write what it must or must not do on every next answer ("must call Read", "must not call Bash", "must call ", "reply contains "). Words used on the page: - **Start from** (in the code, a *situation*): an optional ready-made start for one agent: the first message it gets and a folder of files it can read. Shown only before the first message. - **Answer again with another setup:** the same message answered by a changed setup, side by side with the other answers, each named by what differs ("effort low" / "effort medium"). The next message can go to one of them or to all. - **Reply from here:** the next message continues from that answer, as if later turns never happened. - **Save as test:** the message is asked again later from the same point. Its quick checks become exact checks (`tool_used`, `regex` in `claude plugin eval`); an expected reaction, if written, is checked by a judge (Sonnet). ```bash ~/projects/workstation/agent-framework/agent check # refuse broken records (exit 1) ~/projects/workstation/agent-framework/agent list # agents, tier, model, number of tests ~/projects/workstation/agent-framework/agent serve # the sandbox page: http://127.0.0.1:8790 ~/projects/workstation/a [... cut at 2500 characters] ``` ## File: browser/README.md ``` # browser Persistent Chrome automation, driven by a thin CLI. The first `browser` call in a session starts a small background server (`server.mjs`) that launches one real Chrome window and keeps it open; every later `browser` call — even from a totally separate command — reuses that same window and page. Nothing closes until you run `browser close`. Installed globally via `npm link` (see Setup below), so it's callable as `browser` from any repo/directory, not just from inside this folder. **On Linux** the launcher is `browser/browser.sh`, linked as `~/.local/bin/browser` (it calls the nvm node binary by path, because nvm's `node` shell function can crash agents' shells). The Windows paths in the examples below do not apply; use any absolute path, for example under your scratchpad. ## Why this exists, and why it's not MCP MCP-based browser tools (chrome-devtools-mcp, playwright-mcp) kept disconnecting mid-session. The actual problem was never persistence itself — it was MCP's stdio JSON-RPC transport inside Claude Code's client dropping the connection. This tool gets persistence back without that transport: `cli.mjs` is a stateless client that talks to `server.mjs` over plain localhost HTTP. If the server isn't up, the client spawns it (detached, backgrounded) and waits for it to answer `/health`. There's no long-lived connection *Claude Code itself* has to hold open — each `browser` invocation is still a normal one-shot CLI call from Claude Code's point of view, it just happens to talk to a browser that was already running. Architecture: - `steps.mjs` — the step-execution logic (`goto`, `click`, `fill`, ...), shared by the server. - `server.mjs` — launches Chrome once (`launchPersistentContext`), keeps one `page` alive, serves `GET /health`, `POST /run` (array of steps), `POST /close` on `127.0.0.1:8848`. - `cli.mjs` — the `browser` command itself. Ensures the server is running, forwards steps to it, prints the JSON result. Also handles `browser status` and `browser close` directly. ## Usage ```bash browser '' # or browser path/to/steps.json browser status # is the persistent server/browser currently up? browser close # close the browser and stop the server ``` To prove a feature works, record it: `recordStart` / `recordStop` (see "Recording proof"). That is the only supported way to record a tab; for stills use `screenshot`. Steps run in order against the one persistent page, and results print as JSON to stdout. Be [... cut at 2500 characters] ``` ## File: chrome/README.md ``` # chrome **There is one way to start Chrome on this machine: through `chrome/chrome.sh`.** It adds the flags in `chrome/flags`, then starts the real Chrome. The menu, the `google-chrome` and `google-chrome-stable` commands, links opened from other apps, and Chrome's own app shortcuts all go through it. Do not start `/opt/google/chrome/google-chrome` or `/usr/bin/google-chrome-stable` by hand: a Chrome started without the flag cannot be recorded (see below), and two ways to start Chrome is how this gets confusing. ## Why Agents prove that a feature works by recording it in the browser (the `browser` command's `recordStart` / `recordStop`, see [`../browser/README.md`](../browser/README.md), "Recording proof"). The recording is Chrome's own tab capture, which normally asks the user to pick what to share. The flag in `flags`, `--auto-select-desktop-capture-source=REC-TARGET`, makes Chrome pick the tab titled `REC-TARGET` with no prompt, so a recording can start and stop without a person. The flag does nothing else: it only matters when a page asks to capture and a tab has that title, so normal screen sharing still shows the usual picker (not tested in a real call). Chrome reads this flag only when it starts. A Chrome that was already running ignores it, so it has to be started this way from the beginning. ## Setup (once per machine, and again if a Chrome update rewrites the menu entry) ```bash ~/projects/workstation/chrome/install.sh ``` Then quit Chrome completely and start it again. The script: - links `~/.local/bin/google-chrome` and `~/.local/bin/google-chrome-stable` to `chrome.sh` (`~/.local/bin` comes before `/usr/bin` in `PATH`); - writes a user-level `google-chrome.desktop` that replaces the system menu entry (the system file under `/usr` is not touched), with every `Exec` pointing at `chrome.sh`; - points Chrome's own app shortcuts (`~/.local/share/applications/chrome-*.desktop`, such as Google Password Manager) at `chrome.sh`. To check a running Chrome has the flag: `pgrep -af chrome | grep -o 'auto-select-desktop-capture-source=[A-Z-]*'`. ## Changing the flags Edit `flags` only. `chrome.sh` reads it at every start, and `browser/recorder.mjs` reads it too (the `browser` command launches its own Chrome with the same flag), so there is one list. Do not copy the flag anywhere else. ## Limits - Linux only so far (GNOME on Wayland, Chrome 145). Windows and macOS need their own launcher change. - This only lets a recording start without a prom [... cut at 2500 characters] ``` ## File: cv/README.md ``` # CVs This directory is the canonical home for the CVs and their editable sources. Keep both sources and rebuilt PDFs in Git so future updates are versioned and backed up together. | Version | PDF | LaTeX | | --- | --- | --- | | Full Stack Developer | [cv-full-stack.pdf](cv-full-stack.pdf) | [cv-full-stack.tex](cv-full-stack.tex) | | AI Full Stack Engineer | [cv-ai-full-stack.pdf](cv-ai-full-stack.pdf) | [cv-ai-full-stack.tex](cv-ai-full-stack.tex) | | AI Integrations | [cv-ai-integrations.pdf](cv-ai-integrations.pdf) | [cv-ai-integrations.tex](cv-ai-integrations.tex) | Shared content: `cv-details.tex`, `cv-work-experience.tex`, `cv-codebot.tex`, and `cv-layout.tex`. The factual input is [experience-notes.md](experience-notes.md); [cv-master.md](cv-master.md) is the readable master, and [cv-material-draft.md](cv-material-draft.md) records drafting decisions. ## Update Edit the files here. Rebuild affected versions from this directory: ```bash pdflatex -interaction=nonstopmode -halt-on-error cv-full-stack.tex pdflatex -interaction=nonstopmode -halt-on-error cv-ai-full-stack.tex pdflatex -interaction=nonstopmode -halt-on-error cv-ai-integrations.tex ``` Check the resulting PDF and commit/push the changed sources and PDFs together. Git records updates; merely editing a local file does not create an off-device backup. There is no automatic commit/upload timer. The matching files under `/home/liel/projects/tech-cv-workspace/` are compatibility symlinks to this directory. Hermes keeps using those paths without maintaining duplicate CV copies. The job vault and pipeline runtime stay at their existing locations; they are not part of this CV directory. ``` ## File: dashboard-concepts/README.md ``` # Dashboard, concepts version A second version of [`../dashboard`](../dashboard/), kept apart so the two can be compared by their output. Same server (imported from `../dashboard/server.py`, not copied), same page, except the bottom-right panel: "Projects", one cell per project grouped by org with only what waits there, and two buttons for what belongs to no project, "Agent system" and "This machine". Everything else is one press inside a project or an area. Model: [`../docs/flows/2026-10-17/data-model.md`](../docs/flows/2026-10-17/data-model.md) ("What contains what", "Concepts"). Intent: [`.idd/modules/dashboard-concepts/INTENT.md`](../.idd/modules/dashboard-concepts/INTENT.md). ```bash python3 ~/projects/workstation/dashboard-concepts/server.py # http://127.0.0.1:8781 (or pass a port) python3 -I -m unittest discover -s ~/projects/workstation/dashboard-concepts # 17 checks against the real data and a real server ``` Hot reload as in `../dashboard`: the page reloads when this `index.html` or either `server.py` changes; the server runs itself again when either server file changes and compiles. A change to `../dashboard/server.py` reaches both versions; a change to either `index.html` reaches only its own. ``` ## File: dashboard/README.md ``` # Dashboard One screen on this machine for its owner, read at a glance. It opens on the Waiting tab: every case asked, every rule change an admin proposed and every call agents made alone, in one list in three groups (Decisions, Rule changes, Decided alone), the newest day first as rows (what it is about, and what to do), the older ones behind a Show. The Overview tab has the count of cases asked and of proposed rule changes on the left, the running team as lanes of file reads and edits and every kind of thing with its count on the right. A press on any of them opens the reader over the right column, with the rows and the open item's real file. Desktop only (1440 by 900). Intent and behavior: [`.idd/modules/dashboard/INTENT.md`](../.idd/modules/dashboard/INTENT.md). Flow card: [`../docs/flows/2026-10-17/flow-card.md`](../docs/flows/2026-10-17/flow-card.md). Look: pitch 2 (Lanes) of [`../docs/design/2026-10-17-dashboard/round-3/`](../docs/design/2026-10-17-dashboard/round-3/). ```bash python3 ~/projects/workstation/dashboard/server.py # http://127.0.0.1:8780 (or pass a port) python3 -I -m unittest discover -s ~/projects/workstation/dashboard # 199 checks against the real data and a real server ``` - Reads what `/api/models` lists (the kinds of `../docs/flows/2026-10-17/data-model.md`) and opens an item's file through `/api/file?path=...&as=html` (Markdown rendered with the system `python3-markdown-it` package; raw HTML is shown as text, not run). - Writes three things: an Answer on an asked case is posted as a comment on its GitHub issue; Accept or Reject on a rule change (a file in `~/projects/data/global/rule-proposals/`) sets `status: accepted|rejected` in that file and adds the line under `## Decision`; a review of a call decided alone (Justified, Should have asked, Wrong call, and a note) sets `review:` in the case file and puts the note under `## Final feedback`, with no GitHub call. It does not edit the rule or skill a proposal is about. The `data` timer commits it within 5 minutes. - Listens on 127.0.0.1 only. Not started by anything: run it when you want it. A service for it would be a new timer or unit, which is your call. - Hot reload: the open page asks `/api/version` every second and reloads itself when `index.html` or `server.py` changed (not while you type an answer); the server runs `server.py` again in place when it changes and still compiles. Data refreshes every 30 s. - Three tabs: Waiting (the default, `#waiting`), Overview ( [... cut at 2500 characters] ``` ## File: deskflow/README.md ``` # Deskflow — shared mouse and laptop keyboard Installed 2026-10-05 with user approval. Official release v1.27.0, not the older Ubuntu package. This supersedes the Lan Mouse runtime, retaining its files for rollback. No UAC/security-desktop policy was weakened. ## Everyday use 1. Keep the Windows PC's USB-tethered phone connected to the **same Wi-Fi as the laptop**, with USB tethering on. Keep Tailscale running on both computers. 2. Use the **laptop trackpad** with the **laptop keyboard**: move past the laptop's **right edge** to control Windows, and past Windows' **left edge** to return. Each machine keeps its own display. The **Windows USB mouse** is a plain Windows mouse (native, no lag). The keyboard follows the mouse you pick up: touch the Windows USB mouse after the trackpad and the keyboard snaps to Windows; touch the trackpad after the Windows USB mouse and it snaps back to the laptop. The same mouse keeps crossing freely. How it works and how to stop it: [Keyboard follows the mouse](usb-mouse/README.md#keyboard-follows-the-mouse). 3. Open Windows Terminal (Admin) normally. Control its UAC permission prompt and the elevated terminal, then cross back as usual. The user verified this. USB/IP forwarding of the Windows USB mouse and of future USB keyboards is **off** since 2026-10-20 (`deskflow-usb-mouse.service` disabled): a forwarded Windows USB mouse felt "like 30fps". See [the USB sharing notes](usb-mouse/README.md) to turn it back on. You do not need to open either Deskflow GUI or log in to a Deskflow account. The Linux server starts with the graphical session; the Windows service is Automatic. GNOME asks to allow input capture every time the server starts: its portal (InputCapture version 1) cannot remember the answer. Click Allow. A Cancel, or a prompt left until it closes, stops Deskflow (`CreateSession canceled` in the log, exit code 0, so systemd does not restart it); run `resume-kvm` to start it and ask again. Startup is configured, but a full reboot and Linux permission-dialog recovery have not been tested. Windows UAC prompts are still intentional security prompts; we did not disable them or make arbitrary administrator commands passwordless. Do **not** start Lan Mouse or use its old "Lan Mouse Control" launcher alongside Deskflow. There is one Deskflow server: the laptop, which also receives the forwarded Windows USB inputs. Returning from Windows does not require a second input server on Windows. ## If it [... cut at 2500 characters] ``` ## File: hermes/README.md ``` # Hermes source installation Installed on 2026-10-02 from https://github.com/NousResearch/hermes-agent at `5bba024d8ddd388f56f354c1f789be825e3d8a3c`. Checkout: `/home/liel/projects/hermes-agent`; launcher: `~/.local/bin/hermes`. State and secrets: `~/.hermes` (not backed up in this repository). Secret-free example settings and the [restore runbook](RESTORE.md) live here. Private Hermes/CV state is archived separately and encrypted before Drive upload; it is never stored as plaintext in this Git repository. ## Current configuration (2026-10-02) Both default/personal and jobs/pipeline profiles now use `gpt-6-luna` through `openai-codex` with separate Hermes ChatGPT logins in protected `auth.json` files. The single user gateway serves both Telegram bots, and all three jobs-profile schedules are active with group delivery. Enrichment has completed and delivered; the personal bot returned a verified Luna response in its Telegram direct chat at 17:50. Curator filtering quality is not yet verified. The laptop must remain awake and online, and ChatGPT usage limits still apply. No paid API fallback was configured. ## Initial installation and staging history The official installer failed when PM bridged the machine's pip.conf work registry into uv: authentication was expired. A command-scoped public index override succeeded without editing that registry or shell configuration: ```bash env UV_INDEX_URL=https://pypi.org/simple \ bash scripts/install.sh --dir /home/liel/projects/hermes-agent \ --non-interactive --skip-computer-use ``` The installer published its launcher and added a guarded PATH fragment to `~/.zprofile`. [zprofile-path.zsh](zprofile-path.zsh) mirrors just that addition; it does not replace the existing Kiro profile blocks. No copy of the unrelated profile content is stored here. Python/tool environments are managed by `hermes pm`, not raw pip. Telegram was added with `env UV_INDEX_URL=https://pypi.org/simple hermes pm install --extra telegram`. Default and jobs profiles use native Gemini; credentials were saved through the Hermes configuration CLI to mode-600 files, never here. Jobs uses Gemini 3.8 Flash after a successful read-only vacancy fit check; Gemini 3.7's larger curator stream stalled, and Gemini 2.5 returned a retired- model error for this key. Default retains Gemini 3.7's successful basic smoke configuration. A one-listing check is not whole-pipeline proof. Job-specific artifacts are project content, not machine-kit code: `/ho [... cut at 2500 characters] ``` ## File: init-windows/README.md ``` # Init Windows Rebuild the selected daily Windows development environment from exact, reviewable manifests. This is not an operating-system image, a personal-file backup, or a credential backup. ## Prerequisites - x64 Windows 10/11, including a bare machine with nothing installed yet — WinGet itself is bootstrapped automatically if `winget.exe` isn't found - The Windows account that will own the tools must itself be a local administrator - Internet access to WinGet, nodejs.org, npm, GitHub, and Visual Studio Marketplace - Close Node, npm, Git, and VS Code processes before install or rollback ## One-command install 1. Download this private repository as a ZIP on Windows and extract it. 2. Open `init-windows`. 3. Double-click `Start-Install.cmd` and approve the administrator prompt. The launcher runs `Install-Windows.ps1`. It installs the selected WinGet programs, all captured Node versions and global npm packages, the captured VS Code extensions, the default VS Code configuration, Git configuration, and the selected user scripts. It finishes by opening Chrome to the Google sign-in page and opening Windows' Default apps settings so you can pick Chrome as default in one click — Windows has blocked scripts from forcing the default browser since 1703, so this is the closest a script can get. ```mermaid flowchart LR A[Start-Install.cmd] --> B[Snapshot existing state] B --> C[Install exact programs] C --> D[Restore Node and VS Code] D --> E[Back up and copy configs/scripts] E --> I[Open Chrome sign-in + Default apps] I --> F[Verify-Windows.ps1] B --> G[Install journal] G --> H[Remove-WindowsPack.ps1] ``` ## What is pinned - NVM for Windows 1.1.12 - Node.js 18.20.4 and active 22.21.1 (16.20.2 and 20.17.0 dropped - present in the original capture with zero global packages attached, doing nothing) - Exact global npm packages per Node version - Git 2.47.1.2 - GitHub CLI 2.92.0 - Grok Build CLI 1.0.4 (`xAI.GrokBuild`) - Claude Code 2.1.229 (`Anthropic.ClaudeCode`) and Codex CLI 0.146.1 (`OpenAI.Codex`) - WinGet, not npm, so they don't wait on Node/NVM at all. Their config (`claude/CLAUDE.md`, `claude/settings.json`, `codex/config.toml`) is deployed as managed files - see the callout below, this is not a subtle default. - Google Chrome 151.0.7922.138 (`Google.Chrome`; Chrome self-updates after install regardless of this pin) - MongoDB Server 8.0.23 (`MongoDB.Server`), auto-configured as a single-node replica set (`rs0` on `local [... cut at 2500 characters] ``` ## File: jev-browser-test/README.md ``` # jev-browser-test `jev-browser-test` is a Linux CLI for behavioral browser smoke QA. It gives a Jev agent a URL and a goal, then optionally checks visible text and the final URL. The result is deliberately narrow: it reports the supplied assertions and does not prove that the page looks correct. ## The Jev Loop When consulting Jev for a decision, state the context and present concrete options. Always include `Other / none of the above`; use the CLI id `other_none`. Prefer `-c` multi-choice questions, especially for programming or coding, and avoid yes/no questions unless the decision is genuinely binary. If Jev chooses `Other / none of the above`, create a different option set and ask again; do not repeat the same options unchanged. Use `-j` when confidence matters: a choice with confidence `>= 0.85` may be heuristically selected as approved for that decision. Lower confidence is not approval; refine the options and loop again, or ask the user. Keep context free of secrets and personal data, and disclose the question and answer. A Jev choice is guidance, not proof of implementation or QA success. ```bash jev "$CONTEXT" -c "Which browser check?" no_browser_check,jev_smoke,jev_smoke_plus_vision,other_none -j ``` ## Install From this directory: ```bash sh install.sh ``` The installer clones `browser-use/jev-ultrafast` to `~/.local/share/jev-ultrafast` when needed, verifies the exact revision pinned in `install.sh` (`1231850a0bf1a0c0341fe408ef1668dbbfdfac46`), installs its frozen environment, and places the CLI in `~/.local/bin/jev-browser-test`. It refuses an existing upstream checkout at a different revision. Treat that pin as part of the tool's behavior; inspect and update it deliberately when changing the upstream dependency. Configure secrets in the private file `~/.config/jev-browser-test/env` (mode `600`): ```dotenv TYPESAFE_API_KEY= TEXT_MODEL_API_KEY= TEXT_MODEL_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai TEXT_MODEL=gemini-3.1-flash-lite TEXT_MODEL_REASONING=omit ``` `TYPESAFE_API_KEY` is preferred. If it is blank, the CLI falls back to `JEV_API_KEY` in `~/projects/jev-relay/.env`. `TEXT_MODEL_API_KEY` is a Google AI Studio (Gemini) key. Gemini rejects the OpenRouter-style `reasoning` field, so `TEXT_MODEL_REASONING=omit` drops it; that option comes from `jev-ultrafast.patch`, which `install.sh` applies to the pinned checkout. Measured 2026-09-21 on a Hebrew login form: `gemini-3.1-flash-lite` filled 6/6 fields correc [... cut at 2500 characters] ``` ## File: lan-mouse/README.md ``` # Lan Mouse over Tailscale > Retired on 2026-10-05. The active setup is [Deskflow](../deskflow/README.md). > Use that guide for everyday use and recovery. The text below is historical; > do not start this controller/daemon alongside Deskflow. The Linux service is > disabled, and its old controller login/menu entries have been archived. > Existing binaries, pairing files and repository templates remain for rollback. Current user preference: the **laptop trackpad and keyboard control the Windows PC**. Each machine keeps its own display. Windows accepts trusted incoming input; its outgoing laptop peer is inactive. The Linux agent must keep its outgoing PC peer active on the right. The PC's local Logitech mouse remains usable locally. The earlier bidirectional Logitech-sharing setup is paired, but forwarding PC input to the laptop is now disabled at the user's request. Reactivate the Windows laptop peer to restore that direction. Use upstream Lan Mouse for the KVM transport; the local controller only manages its existing user service. ## Mouse-accessible controller The Linux machine keeps the upstream Lan Mouse daemon as the KVM runtime and adds a small local GTK controller at `/home/liel/.local/bin/lan-mouse-controller`. The controller is started at graphical login and exposes two independent switches: - **KVM now** starts or stops only the existing `lan-mouse.service`. Stopping it closes the local input-control session and UDP listener without deleting the pairing or certificate. - **Start at login** enables or disables the existing user-service autostart policy. It does not unexpectedly start or stop the current session. - **Retry input access** sends the upstream daemon's input-capture request again when GNOME canceled it. If GNOME shows an approval prompt, allow it with the mouse; the controller reports that the request was sent but cannot approve a desktop security prompt on the user's behalf. The daemon remains the fallback: if the controller is closed or fails, the enabled user service still starts the KVM on the next graphical login. The controller does not alter fingerprints, peer addresses, or the Lan Mouse configuration. Its status only calls input sharing active when the GNOME input-capture session exists; an active service alone is not treated as working input. ## Agent handoff Read this file and both status files after pulling `master`. - Windows agent owns [windows-status.md](windows-status.md). - Laptop agent owns [linux- [... cut at 2500 characters] ``` ## File: reference/README.md ``` # Workstation reference cases Dated incident records for machine-level failures, repairs, and verified operating states. Use these cases to recover the workstation, avoid repeating false diagnoses, and turn observed incidents into reusable runbooks. ## Incidents | Date | Case | Outcome | | --- | --- | --- | | 2026-10-01 | [Keep CodeBot serving with the laptop lid closed](incidents/2026-10-01-codebot-lid-closed.md) | Closed-lid test passed for 1 minute 46 seconds with Wi-Fi, CodeBot, and Tailscale continuously healthy | ``` ## File: skills-sync-windows/README.md ``` # Windows skill synchronization `Lebnor/my-skills` has a repository-scoped self-hosted runner named `my-skills-liel-windows`. Trusted pushes to `master` dispatch the `Sync Windows skills` workflow through outbound HTTPS. No incoming port, DNS record, nginx configuration, relay, or periodic Git polling is needed. ## Installed components | Component | Location | |---|---| | Windows account | `LIEL\my-skills-runner` (not an administrator) | | Runner service | `actions.runner.Lebnor-my-skills.my-skills-liel-windows` (delayed automatic startup) | | Runner files | `C:\actions-runner\my-skills` | | Protected script and configuration | `C:\ProgramData\MySkillsSync` | | Existing checkout | `D:\projects\my-claude-skills`, branch `master` | | Link destinations | `C:\Users\liel\.claude\skills`, `.codex\skills`, `.config\opencode\skills` | | Catch-up task | `MySkillsSync-CatchUp`: once after startup, with three retries if that attempt fails | | Latest successful synchronization | `C:\ProgramData\MySkillsSync\state\last-success.json` | `Sync-Skills.ps1` verifies the branch, origin, and absence of tracked edits. It fetches using a repository-only, read-only SSH deploy key, checks ancestry, then fast-forwards the existing checkout. It reuses the repository's `install.ps1` to keep correct links and add missing ones. Conflicts fail without deleting user files. A file lock serializes startup and GitHub-triggered runs. No repository is cloned by the installed workflow. The runtime script and configuration are writable only by administrators and SYSTEM. The runner can read its deploy key, change its own runner/state directories, update this checkout, and manage the three skill directories. Account-specific deny permissions on D: restrict inherited access outside the protected checkout. Existing Windows permission inheritance can have protected exceptions; this account is not a virtual machine or a network sandbox. Anyone able to change this repository's workflows can execute commands as this account. Keep the repository private and workflow edits trusted. The runner was downloaded from the official Actions runner release `v2.337.0`; the Windows x64 archive SHA256 was verified against GitHub's release metadata: `1150692afa94e71f872017e254ea55b6eece1eece3fe7e3a6d4c93d0a1b85cfc`. The runner's normal automatic updates remain enabled. The account has the Windows service-logon and batch-logon rights required by these two components. Other user-right assignments were preserved [... cut at 2500 characters] ```