@grifhinz/logics-manager 2.2.0 → 2.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/AlexAgo83/logics-manager)](LICENSE)
-![Version](https://img.shields.io/badge/version-v2.2.0-4C8BF5)
+![Version](https://img.shields.io/badge/version-v2.3.1-4C8BF5)
 ![VS Code](https://img.shields.io/badge/VS%20Code-1.86.0-007ACC?logo=visualstudiocode&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-3178C6?logo=typescript&logoColor=white)
 ![Vitest](https://img.shields.io/badge/Vitest-2.1.8-6E9F18?logo=vitest&logoColor=white)
@@ -58,6 +58,15 @@ python3.11 -m pip install .
 logics-manager --help
 ```
 
+On Debian, Ubuntu, or WSL environments where Python is externally managed, use `pipx` instead of installing into the system Python:
+
+```bash
+sudo apt update
+sudo apt install pipx python3-venv
+pipx ensurepath
+pipx install logics-manager
+```
+
 Or install the npm package:
 
 ```bash
@@ -95,6 +104,7 @@ The CLI is the stable contract for Logics. It supports:
 - closing tasks, backlog items, and requests with consistency checks;
 - linting and auditing workflow traceability;
 - exporting indexes, context packs, and graph data;
+- serving a read-only local browser viewer for the Logics corpus;
 - serving the bounded MCP tool surface.
 
 Useful commands:
@@ -105,8 +115,48 @@ logics-manager flow promote request-to-backlog req_001_example
 logics-manager flow promote backlog-to-task item_001_example
 logics-manager flow finish task task_001_example
 logics-manager sync context-pack req_001_example --format json
+logics-manager view --open
+logics-manager view --focus req_001_example --read --open
+```
+
+### Local Browser Viewer
+
+Use the CLI viewer when you want to inspect the Logics corpus outside VS Code:
+
+```bash
+logics-manager view --open
+```
+
+The viewer starts a localhost-only, read-only browser UI on `127.0.0.1:8765` by default. It shows the same workflow board/list experience as the extension, with search, filters, document previews, corpus insights, lint/audit health, Mermaid rendering, auto-refresh, and an edit shortcut that opens the selected Markdown file in the system editor.
+
+Useful options:
+
+```bash
+logics-manager view --port 0 --open
+logics-manager view --host 127.0.0.1 --port 9876
+logics-manager view --focus req_001_example --open
+logics-manager view --focus logics/tasks/task_001_example.md --read --open
+logics-manager view --no-open
+```
+
+Use `--port 0` when the default port is already taken. The viewer is intentionally read-only; use the canonical CLI commands such as `flow promote`, `flow finish`, `lint`, and `audit` for workflow mutations.
+
+Focused viewer links can point directly at a corpus item:
+
+```text
+http://127.0.0.1:8765/?focus=logics/request/req_001_example.md
+http://127.0.0.1:8765/?focus=logics/request/req_001_example.md&read=1
+```
+
+If the viewer server is not already running, start it with the equivalent fallback command:
+
+```bash
+logics-manager view --focus logics/request/req_001_example.md --open
+logics-manager view --focus req_001_example --read --open
 ```
 
+This is the recommended assistant handoff pattern: provide the local viewer link for an already-running viewer and the CLI fallback command for a stopped server. Focus targets accept workflow refs such as `req_001_example`, `item_001_example`, or `task_001_example`, plus repo-relative Logics Markdown paths. Traversal and non-Logics paths are rejected.
+
 ### CLI Contracts
 
 Workflow target arguments accept these forms:
@@ -156,6 +206,32 @@ To update the installed CLI later:
 logics-manager self-update
 ```
 
+If `self-update` reports an externally managed Python environment, migrate the Python install through `pipx`:
+
+```bash
+sudo apt update
+sudo apt install pipx python3-venv
+pipx ensurepath
+pipx install --force logics-manager
+```
+
+For npm installs, update with:
+
+```bash
+npm install -g @grifhinz/logics-manager@latest
+```
+
+If npm reports a successful update but `logics-manager --version` still shows an older version, another installation is earlier on `PATH`. Diagnose it with:
+
+```bash
+command -v -a logics-manager
+npm prefix -g
+npm list -g @grifhinz/logics-manager --depth=0
+"$(npm prefix -g)/bin/logics-manager" --version
+```
+
+If the direct npm binary shows the expected version, remove the older Python install or move the npm global `bin` directory earlier on `PATH`.
+
 ## VS Code Extension
 
 The VS Code extension is the human cockpit around the same runtime. It helps you:
@@ -347,6 +423,7 @@ Windows notes:
 - Create a fixture request with `logics-manager flow new request --title "Smoke test"` and confirm the compact synthetic request shape is generated.
 - Create a backlog item and a task from the UI and confirm markdown is generated.
 - Open `Read` on a Mermaid-bearing doc and confirm the graph is rendered.
+- Run `logics-manager view --port 0 --open`, confirm the browser viewer loads repository docs, then stop it with `Ctrl+C`.
 - Promote request -> backlog and confirm links are updated.
 - Confirm request/backlog/task generation fails fast if a Mermaid signature or traceability block is stale instead of waiting for audit to find it later.
 - Promote backlog -> task and confirm task document is generated.
@@ -391,6 +468,22 @@ npm run dev
 
 `npm run dev` requires the `code` CLI on PATH, so the F5 path above remains the safest cross-platform dev entrypoint.
 
+### Browser UI Debugging
+
+Use the real local viewer for repository data:
+
+```bash
+logics-manager view --open
+```
+
+Use the mock webview harness only when developing the shared browser/webview UI without VS Code:
+
+```bash
+npm run debug:webview
+```
+
+The harness runs at `http://localhost:4173/` and supports mock scenarios such as `/?scenario=empty` and `/?scenario=error`. It does not execute real VS Code commands or workflow writes.
+
 ## Deploy / Release (VSIX)
 
 1. Bump the version in `package.json`, `pyproject.toml`, and root `VERSION` when preparing a release manually.
@@ -446,6 +539,7 @@ If the current plugin version is already published, `logics-manager assist next-
 - Logics docs lint: `npm run lint:logics`
 - Logics workflow audit + docs lint: `npm run audit:logics`
 - Strict Logics governance audit: `npm run audit:logics:strict`
+- Local browser viewer smoke: `logics-manager view --port 0 --open`
 - Fast extension-focused local check: `npm run ci:fast`
 - Full CI-equivalent local check: `npm run ci:check`
 - Security audit policy gate: `npm run audit:ci`

package/VERSION

@@ -1 +1 @@
-2.2.0
+2.3.1

package/clients/README.md

@@ -0,0 +1,9 @@
+# Logics Clients
+
+This directory separates user-facing clients from the shared Logics runtime.
+
+- `vscode/` contains the VS Code extension host implementation.
+- `shared-web/` contains browser/webview assets that can be reused by the VS Code extension and the future local viewer.
+- `viewer/` is reserved for the CLI-launched local browser viewer.
+
+The Python CLI/runtime remains in `logics_manager/`.