@rmrdeveloper/sideroom-pi 8.11.0 → 8.13.0

package/README.md

@@ -1,5 +1,9 @@
 # Sideroom Pi — the side room your agent was missing
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/RMRdeveloper/sideroom-pi/main/media/logo.png" alt="The Sideroom Pi mark" width="640">
+</p>
+
 [![npm version](https://img.shields.io/npm/v/@rmrdeveloper/sideroom-pi?label=npm&logo=npm)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 [![npm monthly downloads](https://img.shields.io/npm/dm/@rmrdeveloper/sideroom-pi?label=downloads&logo=npm)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 [![npm license](https://img.shields.io/npm/l/@rmrdeveloper/sideroom-pi?label=license)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
@@ -54,6 +58,7 @@ Sideroom answers each one with a small, opinionated surface:
 | Style drift | A pre-edit gate + the on-demand `sideroom-guidelines` skill + an end-of-turn review steer |
 | Invisible monorepo skills | `monorepo-skills` — trusted child folders join Pi's available skill list |
 | Vague plans | `sideroom-grill` — an interview that settles the words before the work |
+| Costly growth and refactors | `sideroom-codebase-design` — evidenced improvements to module design, tests, and long-term scaling |
 | Unapplied guidelines | `sideroom_rules` — mechanical checks that block or flag the lines you add |
 | Unchecked judgment rules | `jev` — asks a decision model about guide rules with visible evidence |
 | Unclear answers | `sideroom_persona` — one voice: direct, plain, and free of unnecessary technical words |
@@ -136,6 +141,22 @@ session. The compact view shows at most five recent paths below an active
 board; the extended `F8` view scrolls through everything. Paths outside the
 project are labelled `external`. A new session starts clean.
 
+### Browser context — point to the element
+
+Press `F7` to authorize the bundled browser companion once per Pi installation.
+It reconnects automatically and remembers Windows and WSL independently; choose
+a destination if several Pi sessions are open. Press `Alt+Shift+S` to select
+several elements without opening the popup; Escape or the shortcut exits.
+Review their local source candidates in Pi and send your
+instruction. The click prepares context; it never starts the agent. No project
+configuration or framework plugin is needed. Source ranges are real, but the
+DOM-to-source relationship is inferred and stays labelled as a candidate.
+Download [the companion ZIP](https://github.com/RMRdeveloper/sideroom-pi/releases/latest/download/sideroom-browser-extension.zip)
+from GitHub Releases, extract it, and load its folder in your browser's developer mode.
+No extension store is required; installation and updates are manual. The same
+companion ships in the npm package. See [browser context](docs/extensions/visual-context.md)
+for installation, Windows/WSL pairing and supported source searches.
+
 ### Grill — settle the words first
 
 An on-demand skill for fuzzy plans. It interviews you in `sideroom_ask`
@@ -154,6 +175,18 @@ one to interview at all, `sideroom-domain-scaffold` reads the central
 domain code as source of truth, builds or completes `CONTEXT.md` on its
 own, and grills the conflicting terms once, at the end.
 
+### Codebase design — improve how the code grows
+
+`sideroom-codebase-design` reviews existing code, identifies where changes or
+growth create friction, and designs improvements with small interfaces and
+clear responsibilities. It considers growing features, teams, traffic, and
+data, using known needs and evidence rather than hypothetical infrastructure.
+Each recommendation explains the problem, benefit, cost, confidence, migration,
+and verification in text. It produces no diagrams or HTML reports. A review
+stays a review; when implementation is requested, it follows the authorized
+scope and preserves behavior and compatibility. See
+[skill activation](docs/skills.md) for routing and examples.
+
 ### Guidelines — a gate, not a novel
 
 A short system-prompt contract points at the packaged
@@ -197,13 +230,18 @@ Reading the guide covers the mechanical rules. `jev` makes one optional call
 to TypeSafe's decision model about the changed file and, when available, up to
 four directly related source files. It checks guard clauses, fail fast,
 command/query separation, null handling, immutability, repeated validation,
-responsibility, dependency direction, and comments only when the supplied
+responsibility, dependency direction, comments, testability, redundant
+abstractions, consumer compatibility and test quality only when the supplied
 files support the question. An answer above the cutoff travels with the
 end-of-run guidelines review instead of interrupting each edit. READMEs, JSON,
 lockfiles, deletion-only edits, and files outside the project are never sent.
 
 It never blocks and never enters the system prompt. No conversation or session
-content leaves the machine. Related source excludes ignored, hidden, sensitive-
+history leaves the machine. Successful questionnaires also send their question
+wording and options, without user answers. Newly completed tasks may send their
+descriptions, up to four observed changed files and a check status, without
+commands or logs. These additional calls review explicit contradictions and
+ambiguous choices. Related source excludes ignored, hidden, sensitive-
 named and symlinked paths; a normal source file can still contain a secret.
 The footer counts the calls the session made, and `F10` shows the same count
 beside the key source. Without a key nothing is called, and when Jev runs out of
@@ -365,7 +403,12 @@ itself.
   prompt.
 - One request per successful `write`/`edit` of a project file in a supported
   language that added lines, with applicable `noul` questions on the complete
-  changed file and up to four directly related source files.
+  changed file and up to four directly related source files, prioritizing tests
+  and production consumers before imports.
+- One additional request per successful, non-cancelled questionnaire and per
+  eligible completion update. Only validated question wording or targeted
+  completion descriptions and bounded observed evidence travel; no answers,
+  conversation history or command output. All requests share the same limits.
 - The official 32k-token state-plus-longest-question and 64k-token request
   limits are observed conservatively using 32,000 and 64,000 UTF-8 bytes.
   Oversized neighbours are omitted whole; if the changed file cannot fit,
@@ -433,8 +476,9 @@ and zero ADRs is working as designed.
 
 ### Coexisting with other grilling skills
 
-Pi routes skills by description, not by name, so several grilling skills can
-be installed at once. `sideroom-grill` claims non-trivial plans before
+See [skill activation](docs/skills.md) for selection boundaries and discovery
+diagnostics. Pi routes skills by description, not by name, so several grilling
+skills can be installed at once. `sideroom-grill` claims non-trivial plans before
 implementation and states precedence over other grilling, interview, and spec
 skills. If a third-party skill still wins, remove it from routing by adding
 `disable-model-invocation: true` to its frontmatter, or exclude its path with

package/assets/artifacts/GUIDELINES_TEMPLATE.md

@@ -181,7 +181,7 @@ async function createUser(data) {
 ```
 
 ### 12. DRY (real duplication only)
-RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge.
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract solely to anticipate reuse on the first or second occurrence, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 ```ts
 // bad — extracted after one real use
 function formatName(x: string) { return x.trim().toUpperCase(); }
@@ -190,7 +190,7 @@ function normalizeTicketStatus(status: string): TicketStatus { /* ... */ }
 ```
 
 ### 13. KISS
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 ```js
 // bad
 function formatPrice(value, { currency = 'USD', locale = 'en-US', showSymbol = true } = {}) { /* ... */ }
@@ -199,7 +199,7 @@ function formatPrice(value) { return `$${value.toFixed(2)}`; }
 ```
 
 ### 14. YAGNI
-RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (Differs from KISS: KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 ```js
 // bad
 function createInvoice(order, { supportsRecurring = false, supportsMultiCurrency = false } = {}) { /* ... */ }

package/assets/visual-context/browser/INSTALL.md

@@ -0,0 +1,69 @@
+# Sideroom Visual Context
+
+## English
+
+This is a manually installed companion for Chromium-based browsers 116 or
+later, such as Chrome, Edge or Brave. It is not a store installation. Firefox is
+not supported.
+
+1. Extract the ZIP. Keep the `sideroom-browser-extension` folder in a permanent
+   location; the browser loads the extension from this directory.
+2. Open `chrome://extensions` (or `edge://extensions`), enable developer mode,
+   choose **Load unpacked**, and select the folder containing `manifest.json`.
+3. Install Sideroom Pi with `pi install npm:@rmrdeveloper/sideroom-pi`. Start Pi
+   in your project, press `F7`, and choose **Pair browser**.
+4. Open the companion, paste the private pairing address from Pi, and choose
+   **Connect to Pi**. Keep that address private. Choose a destination if several
+   Pi sessions are open. Repeat pairing for a separate Windows or WSL installation.
+5. On a normal web page, press `Alt+Shift+S` to start selecting. Click several
+   elements. Press the shortcut again or Escape to return to normal browsing.
+   Review pending elements with `F7` in Pi, then send your instruction.
+
+Change or assign the shortcut in `chrome://extensions/shortcuts` or
+`edge://extensions/shortcuts`. Browser and operating-system shortcuts can take
+priority. Internal browser pages and other protected pages cannot be inspected.
+Managed browsers can prohibit developer mode.
+
+Updates are manual. Download the ZIP from the new Sideroom GitHub Release,
+replace the files in the same folder, and reload the extension from the browser's
+extensions page. Do not remove and reinstall it unless you want to pair again.
+The extension connects only to authorized local Pi installations; it captures
+DOM descriptions, not form values or editable text. Source locations are inferred
+candidates, never proven mappings.
+
+## Español
+
+Esta extensión se instala manualmente en navegadores basados en Chromium 116 o
+posterior, como Chrome, Edge o Brave. No se instala desde una tienda. Firefox no
+está soportado.
+
+1. Descomprime el ZIP. Guarda la carpeta `sideroom-browser-extension` en una
+   ubicación permanente; el navegador carga la extensión desde esa carpeta.
+2. Abre `chrome://extensions` (o `edge://extensions`), activa el modo
+   desarrollador, elige **Cargar desempaquetada** y selecciona la carpeta que
+   contiene `manifest.json`.
+3. Instala Sideroom Pi con `pi install npm:@rmrdeveloper/sideroom-pi`. Inicia Pi
+   en tu proyecto, pulsa `F7` y elige **Pair browser**.
+4. Abre la extensión, pega la dirección privada de emparejamiento de Pi y elige
+   **Connect to Pi**. No compartas esa dirección. Elige un destino si hay varias
+   sesiones abiertas. Repite el emparejamiento para otra instalación de Windows o WSL.
+5. En una página web normal, pulsa `Alt+Shift+S` para seleccionar. Haz clic en
+   varios elementos. Pulsa de nuevo el atajo o Escape para navegar normalmente.
+   Revisa los elementos con `F7` en Pi y envía tu instrucción.
+
+Cambia o asigna el atajo en `chrome://extensions/shortcuts` o
+`edge://extensions/shortcuts`. Los atajos del navegador o del sistema pueden
+tener prioridad. No puedes seleccionar elementos de páginas internas del
+navegador ni de otras páginas protegidas. Un navegador administrado puede
+prohibir el modo desarrollador.
+
+Las actualizaciones son manuales. Descarga el ZIP de la nueva versión de Sideroom
+en GitHub Releases, reemplaza los archivos en la misma carpeta y recarga la
+extensión desde la página de extensiones del navegador. No la elimines y
+reinstales salvo que quieras volver a emparejarla.
+La extensión solo se conecta a instalaciones locales de Pi que hayas autorizado;
+recoge descripciones de los elementos, no valores de formularios ni texto editable.
+Los archivos de origen son candidatos inferidos, no correspondencias demostradas.
+
+Full guide / Guía completa:
+https://github.com/RMRdeveloper/sideroom-pi/blob/main/docs/extensions/visual-context.md