debugbrief 1.4.0__tar.gz → 1.4.1__tar.gz

{debugbrief-1.4.0 → debugbrief-1.4.1}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -21,7 +21,7 @@ body:
     attributes:
       label: DebugBrief version
       description: Output of `debugbrief --version`.
-      placeholder: debugbrief 1.3.0
+      placeholder: debugbrief 1.4.1
     validations:
       required: true
   - type: input

{debugbrief-1.4.0 → debugbrief-1.4.1}/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to DebugBrief are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.1] - 2026-10-16
+
+### Fixed
+
+- Corrected the security policy's process-cleanup and local file-access descriptions.
+- Made Git requirements and timestamp validation consistent across the README,
+  command reference and website docs. Added the missing recover reference and
+  clarified stdout formats and Explorer report imports.
+- Rewrote the README for a shorter introduction and practical examples. Added
+  contributor browser checks and documented the actual repository protections
+  and token-free PyPI release workflow.
+- Enabled the private vulnerability-reporting form referenced by the security policy.
+- Command capture and report behavior are unchanged from 1.4.0.
+
 ## [1.4.0] - 2026-10-16
 
 ### Added
@@ -12,17 +26,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Reports now expose an explicit `verified` or `unverified` evidence state and
   preserve the important caveat that DebugBrief does not infer a root cause.
 - `end --format html` writes a self-contained browser report, and `--format all`
-  writes Markdown, JSON, and HTML together. HTML mode sections now follow the
-  selected reader and omit sections with no evidence.
+  writes Markdown, JSON, and HTML together. HTML sections follow the
+  selected report mode and omit sections with no evidence.
 - The static product site lives in `site/` and presents the real workflow,
   report modes, trust boundary, and limitations. Fonts and optional homepage animation libraries load from a CDN.
 - `end --format html --open` writes and opens a self-contained HTML brief, `open --html` opens
   the newest HTML report, and `last --open` provides a one-step review path.
-- `preview --format html|json` renders machine-readable or browser-ready proofs
+- `preview --format html|json` renders JSON or HTML previews
   without finalizing the active session.
 - PR and HTML reports now expose the verification scope and the captured failure
   excerpt, not only a pass/fail headline.
-- The supplied product-site design includes the animated red-to-green field,
+- The product site includes the animated red-to-green field,
   light and dark themes, report tabs, install copying and a keyboard-accessible
   documentation section finder.
 - The Evidence Explorer reads local JSON reports in memory, with command/output
@@ -54,7 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Reports and JSON output now normalize untrusted legacy text without allowing
   modified filenames or tainted command/error fields to break Markdown structure.
   JSON scalar values remain plain, `last` handles malformed report files, and
-  absolute project paths are a CLI-only opt-in.
+  the absolute project-root field is a CLI-only opt-in.
 - Invalid command end timestamps fall back to validated event or start timestamps,
   malformed persisted leaves degrade to controlled values, and multiline notes
   remain intact in storage while being escaped at report-rendering time.

{debugbrief-1.4.0 → debugbrief-1.4.1}/CONTRIBUTING.md

@@ -12,7 +12,8 @@ DebugBrief intentionally does NOT:
 - make network calls at runtime,
 - capture shell history,
 - run a background daemon,
-- ship a runtime web UI or TUI (the repository may contain a static product site),
+- run a web server as part of command capture. Self-contained HTML reports and
+  the separate static website are supported,
 - add new runtime dependencies. DebugBrief uses the standard library and native
   `git`, plus one conditional dependency: the `tomli` TOML parser on Python 3.9
   and 3.10, where the standard-library `tomllib` is not yet available.
@@ -45,6 +46,44 @@ deliberate):
 DEBUGBRIEF_UPDATE_SNAPSHOTS=1 pytest tests/test_snapshots.py
 ```
 
+Run the same lint and type checks as CI:
+
+```bash
+python -m ruff check src tests
+python -m mypy src/debugbrief
+```
+
+## Website changes
+
+The site is plain HTML, CSS and JavaScript; there is no build step. From the
+repository root, `python3 scripts/serve_site.py` starts an uncached preview at
+`http://127.0.0.1:8765`. Stop it when you finish.
+
+Check local links and the generated report fixtures:
+
+```bash
+python scripts/check_site.py
+python scripts/generate_samples.py --check
+```
+
+For browser tests, install Node.js and the pinned tools in `package-lock.json`:
+
+```bash
+npm ci
+npx playwright install --with-deps chromium
+npm run test:site
+```
+
+The browser suite checks imports, keyboard interaction, accessibility, reflow and
+report privacy. Firefox and WebKit checks are available through
+`npm run test:site:firefox` and `npm run test:site:webkit` after installing those
+Playwright engines. Engine tests do not replace physical-device or screen-reader
+checks.
+
+When report rendering changes, regenerate the nine illustrative site fixtures
+with `python scripts/generate_samples.py`, review the output, then run the check
+again. Do not edit generated reports by hand or pass them off as real executions.
+
 ## Build the wheel
 
 ```bash
@@ -76,7 +115,7 @@ python -m debugbrief --help
   runtime dependencies. If one is truly unavoidable, justify it clearly in the
   pull request and README.
 - Add or update tests for any behavior you change. Core logic must stay tested.
-- Keep CLI output plain and human-readable. 
+- Keep CLI output plain and readable.
 - Be honest in code and docs. Do not fabricate report content, root causes,
   test results, or verification, and do not claim a command was run unless it
   was actually run. Do not include AI-generated fake summaries or fabricated

debugbrief-1.4.1/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: debugbrief
+Version: 1.4.1
+Summary: Records debugging commands, outcomes, notes, and Git changes, then generates evidence-backed reports for pull requests, handoffs, and incidents.
+Author: Hari Krishna Kancharla
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hari-kancharla/Debug-Brief
+Project-URL: Repository, https://github.com/hari-kancharla/Debug-Brief
+Project-URL: Documentation, https://github.com/hari-kancharla/Debug-Brief/tree/main/docs
+Project-URL: Changelog, https://github.com/hari-kancharla/Debug-Brief/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/hari-kancharla/Debug-Brief/issues
+Project-URL: Security, https://github.com/hari-kancharla/Debug-Brief/security/policy
+Keywords: cli,debugging,developer-tools,git,testing,pull-request,handoff,incident,report,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1.0; extra == "release"
+Requires-Dist: twine>=5.0; extra == "release"
+Dynamic: license-file
+
+# DebugBrief
+
+[![CI](https://github.com/hari-kancharla/Debug-Brief/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/hari-kancharla/Debug-Brief/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/debugbrief?cacheSeconds=3600)](https://pypi.org/project/debugbrief/)
+
+Record commands and notes while you debug, then turn them into a report for a
+pull request, a handoff, or an incident review.
+
+DebugBrief keeps the actual commands, exit codes, output previews and Git changes.
+It does not use AI or infer a root cause. You decide what to run and what to share.
+
+![A failing test, a fix, a passing rerun and the generated report](https://raw.githubusercontent.com/hari-kancharla/Debug-Brief/main/docs/demo.gif)
+
+## Install
+
+Python 3.9 or newer on Linux or macOS. The project you debug can use any language.
+
+```bash
+pipx install debugbrief
+# or
+uv tool install debugbrief
+```
+
+Upgrade an existing installation with `pipx upgrade debugbrief` or
+`uv tool upgrade debugbrief`. Inside an activated Python environment, use
+`python -m pip install --upgrade debugbrief`.
+
+The HTML and Explorer workflows below require DebugBrief 1.4.0 or newer.
+Check your installed version with `debugbrief --version`. Install your project's
+test tools and dependencies separately; DebugBrief does not install them for you.
+
+## Quickstart
+
+Run this from your project, replacing the pytest command with your usual check:
+
+```bash
+debugbrief run -- python -m pytest -q
+# If it fails, edit the files and run the same command again:
+debugbrief redo
+debugbrief end --format html --open
+```
+
+The first `run` starts a session automatically. A title and notes are optional:
+
+```bash
+debugbrief start "Handle an expired cache entry"
+debugbrief note "Expired entries still reach the read path."
+```
+
+Use `start` before your first captured command if you want to set the title.
+Put DebugBrief flags before `--`; everything after it is the command to capture.
+An optional alias saves some typing:
+
+```bash
+alias db="debugbrief run --"
+db pytest -q
+```
+
+## Reports
+
+| Mode | What it contains |
+| --- | --- |
+| `pr` | Reproduce and verify commands, changed files, failed attempts and a red-to-green window when available. |
+| `handoff` | Current status, notes, command history and next steps drawn from your notes. |
+| `incident` | A timeline, the recorded error, current outcome and follow-up notes. |
+
+`end` defaults to a compact PR report in Markdown. Use `--detail full` for the
+complete Markdown record. JSON and HTML always retain the complete evidence.
+
+```bash
+debugbrief end --format all    # Markdown, JSON and HTML
+debugbrief open --html         # open the newest HTML report
+```
+
+The other formats are `md`, `json`, `both` (Markdown and JSON), and `html`.
+Use `preview --format html` or `preview --format json` to inspect an active
+session without ending it.
+
+Current illustrative reports, generated by the report code:
+[PR](https://github.com/hari-kancharla/Debug-Brief/blob/main/site/data/sample-pr.md),
+[handoff](https://github.com/hari-kancharla/Debug-Brief/blob/main/site/data/sample-handoff.md),
+[incident](https://github.com/hari-kancharla/Debug-Brief/blob/main/site/data/sample-incident.md).
+The incident example deliberately retains a later failure and incomplete capture.
+
+Review a report before sharing it. To post a reviewed Markdown brief with the
+optional GitHub CLI:
+
+```bash
+debugbrief end --stdout | gh pr comment --body-file -
+```
+
+## What the evidence means
+
+- Verification needs an eligible passing check, valid recorded timestamps for all
+  verification candidates, and no currently failing check. A previous failure is
+  not required. Help, version and collection/list commands do not count, even
+  with `--verify`. Use that flag to declare a custom check.
+- A red-to-green window requires Git and the same command failing and then passing
+  in the same directory. Files changed during that window are a correlation,
+  not a proven cause. A later failure keeps the report unverified.
+- `redo` runs the stored command in its recorded directory using the current
+  files, environment and dependencies. It does not recreate an old environment.
+  `redo --dry-run` shows what would run; potentially destructive reruns ask for
+  confirmation. `--yes` skips that prompt.
+- Reports retain project-relative command directories. Missing directory data in
+  older reports stays unknown. The project-root field uses the repository name
+  by default; absolute paths inside commands, notes and output can still appear.
+- Stored text goes through best-effort secret redaction. Live command output is
+  shown as the command prints it. Redaction can miss secrets, and `--no-redact`
+  disables it for a captured command. Review reports before sharing.
+
+Verification covers the recorded checks, not the whole issue. Full capture and
+privacy details are in [SECURITY.md](https://github.com/hari-kancharla/Debug-Brief/blob/main/SECURITY.md).
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `init` | Set up local state and show the workflow. |
+| `start "<title>"` | Start a named session. |
+| `note <text>` | Record an observation. |
+| `run -- <command>` | Run and capture a command. |
+| `redo` | Run the last captured command again. |
+| `preview` | Print a report without ending the session. |
+| `end` | Finish the session and write reports. |
+| `cancel` | Abandon the session, keeping its local record. |
+| `status` | Inspect the active session and command. |
+| `doctor` | Check the project and local state. |
+| `recover` | Repair stale state after an interruption. |
+| `last` / `open` | Find or open a saved report. |
+| `list` / `show <id>` | Inspect earlier sessions. |
+
+See [the command reference](https://github.com/hari-kancharla/Debug-Brief/blob/main/docs/COMMANDS.md)
+for flags, configuration, recognized runners and recovery behavior.
+
+## Dependencies and limits
+
+The CLI uses the Python standard library and native Git. Python 3.9 and 3.10 also
+need `tomli`, installed automatically to read optional TOML configuration.
+DebugBrief itself sends no telemetry and makes no network requests. Commands you
+run can still use the network.
+
+Linux and macOS are tested in CI on Python 3.9–3.14. Native Windows and PowerShell
+are not supported. Capture is explicit through `run`; it does not read shell
+history or meaningfully capture full-screen programs such as vim or htop. Output
+previews are bounded, so reports are not complete terminal transcripts.
+
+Ordinary background descendants are stopped during command cleanup. Deliberately
+detached processes can survive; run long-lived servers outside DebugBrief.
+Outside a Git repository, command and note capture still work, but Git state,
+changed-file correlation and red-to-green windows are unavailable.
+
+## Website and development
+
+The static site includes a command reference and a JSON Evidence Explorer.
+Imported reports stay in memory in the browser; they are never uploaded or stored.
+An explicitly chosen color theme is saved. Fonts and optional homepage animations
+load from a CDN. Generated HTML reports are self-contained and need no CDN.
+
+From a source checkout, preview the site with `python3 scripts/serve_site.py`.
+The site is included in the source archive, not the installed wheel.
+
+For Python development:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+[CONTRIBUTING.md](https://github.com/hari-kancharla/Debug-Brief/blob/main/CONTRIBUTING.md)
+covers setup, linting, types, browser checks and builds.
+
+## License
+
+MIT. See [LICENSE](https://github.com/hari-kancharla/Debug-Brief/blob/main/LICENSE).

debugbrief-1.4.1/README.md

@@ -0,0 +1,174 @@
+# DebugBrief
+
+[![CI](https://github.com/hari-kancharla/Debug-Brief/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/hari-kancharla/Debug-Brief/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/debugbrief?cacheSeconds=3600)](https://pypi.org/project/debugbrief/)
+
+Record commands and notes while you debug, then turn them into a report for a
+pull request, a handoff, or an incident review.
+
+DebugBrief keeps the actual commands, exit codes, output previews and Git changes.
+It does not use AI or infer a root cause. You decide what to run and what to share.
+
+![A failing test, a fix, a passing rerun and the generated report](https://raw.githubusercontent.com/hari-kancharla/Debug-Brief/main/docs/demo.gif)
+
+## Install
+
+Python 3.9 or newer on Linux or macOS. The project you debug can use any language.
+
+```bash
+pipx install debugbrief
+# or
+uv tool install debugbrief
+```
+
+Upgrade an existing installation with `pipx upgrade debugbrief` or
+`uv tool upgrade debugbrief`. Inside an activated Python environment, use
+`python -m pip install --upgrade debugbrief`.
+
+The HTML and Explorer workflows below require DebugBrief 1.4.0 or newer.
+Check your installed version with `debugbrief --version`. Install your project's
+test tools and dependencies separately; DebugBrief does not install them for you.
+
+## Quickstart
+
+Run this from your project, replacing the pytest command with your usual check:
+
+```bash
+debugbrief run -- python -m pytest -q
+# If it fails, edit the files and run the same command again:
+debugbrief redo
+debugbrief end --format html --open
+```
+
+The first `run` starts a session automatically. A title and notes are optional:
+
+```bash
+debugbrief start "Handle an expired cache entry"
+debugbrief note "Expired entries still reach the read path."
+```
+
+Use `start` before your first captured command if you want to set the title.
+Put DebugBrief flags before `--`; everything after it is the command to capture.
+An optional alias saves some typing:
+
+```bash
+alias db="debugbrief run --"
+db pytest -q
+```
+
+## Reports
+
+| Mode | What it contains |
+| --- | --- |
+| `pr` | Reproduce and verify commands, changed files, failed attempts and a red-to-green window when available. |
+| `handoff` | Current status, notes, command history and next steps drawn from your notes. |
+| `incident` | A timeline, the recorded error, current outcome and follow-up notes. |
+
+`end` defaults to a compact PR report in Markdown. Use `--detail full` for the
+complete Markdown record. JSON and HTML always retain the complete evidence.
+
+```bash
+debugbrief end --format all    # Markdown, JSON and HTML
+debugbrief open --html         # open the newest HTML report
+```
+
+The other formats are `md`, `json`, `both` (Markdown and JSON), and `html`.
+Use `preview --format html` or `preview --format json` to inspect an active
+session without ending it.
+
+Current illustrative reports, generated by the report code:
+[PR](https://github.com/hari-kancharla/Debug-Brief/blob/main/site/data/sample-pr.md),
+[handoff](https://github.com/hari-kancharla/Debug-Brief/blob/main/site/data/sample-handoff.md),
+[incident](https://github.com/hari-kancharla/Debug-Brief/blob/main/site/data/sample-incident.md).
+The incident example deliberately retains a later failure and incomplete capture.
+
+Review a report before sharing it. To post a reviewed Markdown brief with the
+optional GitHub CLI:
+
+```bash
+debugbrief end --stdout | gh pr comment --body-file -
+```
+
+## What the evidence means
+
+- Verification needs an eligible passing check, valid recorded timestamps for all
+  verification candidates, and no currently failing check. A previous failure is
+  not required. Help, version and collection/list commands do not count, even
+  with `--verify`. Use that flag to declare a custom check.
+- A red-to-green window requires Git and the same command failing and then passing
+  in the same directory. Files changed during that window are a correlation,
+  not a proven cause. A later failure keeps the report unverified.
+- `redo` runs the stored command in its recorded directory using the current
+  files, environment and dependencies. It does not recreate an old environment.
+  `redo --dry-run` shows what would run; potentially destructive reruns ask for
+  confirmation. `--yes` skips that prompt.
+- Reports retain project-relative command directories. Missing directory data in
+  older reports stays unknown. The project-root field uses the repository name
+  by default; absolute paths inside commands, notes and output can still appear.
+- Stored text goes through best-effort secret redaction. Live command output is
+  shown as the command prints it. Redaction can miss secrets, and `--no-redact`
+  disables it for a captured command. Review reports before sharing.
+
+Verification covers the recorded checks, not the whole issue. Full capture and
+privacy details are in [SECURITY.md](https://github.com/hari-kancharla/Debug-Brief/blob/main/SECURITY.md).
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `init` | Set up local state and show the workflow. |
+| `start "<title>"` | Start a named session. |
+| `note <text>` | Record an observation. |
+| `run -- <command>` | Run and capture a command. |
+| `redo` | Run the last captured command again. |
+| `preview` | Print a report without ending the session. |
+| `end` | Finish the session and write reports. |
+| `cancel` | Abandon the session, keeping its local record. |
+| `status` | Inspect the active session and command. |
+| `doctor` | Check the project and local state. |
+| `recover` | Repair stale state after an interruption. |
+| `last` / `open` | Find or open a saved report. |
+| `list` / `show <id>` | Inspect earlier sessions. |
+
+See [the command reference](https://github.com/hari-kancharla/Debug-Brief/blob/main/docs/COMMANDS.md)
+for flags, configuration, recognized runners and recovery behavior.
+
+## Dependencies and limits
+
+The CLI uses the Python standard library and native Git. Python 3.9 and 3.10 also
+need `tomli`, installed automatically to read optional TOML configuration.
+DebugBrief itself sends no telemetry and makes no network requests. Commands you
+run can still use the network.
+
+Linux and macOS are tested in CI on Python 3.9–3.14. Native Windows and PowerShell
+are not supported. Capture is explicit through `run`; it does not read shell
+history or meaningfully capture full-screen programs such as vim or htop. Output
+previews are bounded, so reports are not complete terminal transcripts.
+
+Ordinary background descendants are stopped during command cleanup. Deliberately
+detached processes can survive; run long-lived servers outside DebugBrief.
+Outside a Git repository, command and note capture still work, but Git state,
+changed-file correlation and red-to-green windows are unavailable.
+
+## Website and development
+
+The static site includes a command reference and a JSON Evidence Explorer.
+Imported reports stay in memory in the browser; they are never uploaded or stored.
+An explicitly chosen color theme is saved. Fonts and optional homepage animations
+load from a CDN. Generated HTML reports are self-contained and need no CDN.
+
+From a source checkout, preview the site with `python3 scripts/serve_site.py`.
+The site is included in the source archive, not the installed wheel.
+
+For Python development:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+[CONTRIBUTING.md](https://github.com/hari-kancharla/Debug-Brief/blob/main/CONTRIBUTING.md)
+covers setup, linting, types, browser checks and builds.
+
+## License
+
+MIT. See [LICENSE](https://github.com/hari-kancharla/Debug-Brief/blob/main/LICENSE).

{debugbrief-1.4.0 → debugbrief-1.4.1}/SECURITY.md

@@ -6,9 +6,10 @@ and makes no network requests of its own.
 ## What data leaves your machine
 
 DebugBrief itself sends nothing. It has no network code: no telemetry, no
-accounts, no cloud sync, no update checks. It reads and writes only under your
-project's `.debugbrief/` directory and shells out to local `git` and to the
-commands you ask it to run.
+accounts, no cloud sync, no update checks. It stores session state and reports under your project's `.debugbrief/`
+directory. It also reads project configuration, Git metadata and changed-file
+contents for comparison, and can add a local ignore entry in `.git/info/exclude`.
+It runs local Git and the commands you ask it to capture.
 
 Commands you run through DebugBrief keep their normal behavior. A command can
 access the network exactly as it would if you ran it directly, so what such a
@@ -36,8 +37,11 @@ hazards rather than a remote attacker:
   that do not support Unix permissions.
 - **Crash safety.** Session and report writes are atomic (write to a temp file,
   then rename). A running command holds an OS lock for its whole lifetime; if the
-  process dies, the lock is released by the OS and `debugbrief recover` reports
-  the unfinished command without losing the session.
+  recorder dies, an independent supervisor stops the owned command process
+  group, including after SIGKILL. Cleanup releases the lock after its holders
+  exit. `recover` preserves saved events and reports the lost result as unknown;
+  it never turns an incomplete capture into a pass. Recovery can still report a
+  held lock during cleanup, and deliberately detached processes can outlive it.
 - **Repository-supplied state.** `.debugbrief/` lives inside the project, so a
   cloned repository could ship a pre-seeded session. DebugBrief does not trust
   that state to drive execution: `debugbrief redo` refuses to re-run a command
@@ -55,16 +59,38 @@ hazards rather than a remote attacker:
 It does **not** defend against a local attacker who already has write access to
 your `.debugbrief/` directory or who can modify the commands you run.
 
-## Command capture is foreground-only
+## Foreground commands and cleanup
 
-DebugBrief captures a single foreground command and holds the active-command
-lease until that command's process tree exits. If a captured command backgrounds
-a long-lived process (for example `debugbrief run --shell "my-server &"`), that
-descendant keeps the lease held until it exits, so a later `run` may report that
-a command is still running. When that happens, `debugbrief status` and
-`debugbrief recover` detect and explain the held lock rather than reporting the
-project as idle. Capture, and the lease, are designed for foreground commands;
-start long-running daemons outside DebugBrief.
+Capture is intended for commands that finish, not for managing long-lived servers.
+On normal completion, timeout, interruption or recorder death, the supervisor
+stops ordinary descendants in its process group. It escalates from SIGTERM to
+SIGKILL when needed. A program that deliberately creates another session or
+process group can survive. If it also closes its captured streams, its continued
+execution may be undetectable to the recorder.
+
+A surviving process can retain the command lock. `status` and `recover` report
+that the lock is still held; recovery will not clear it to pretend the project
+is idle. After cleanup finishes, retry recovery. Saved events remain available,
+but a crash can lose the command result that had not yet been recorded.
+
+## Reports and the browser Explorer
+
+The project-root field shows the repository name by default. The
+`--include-full-path` flag exposes the full root intentionally. This setting does
+not remove absolute paths inside command text, output or notes.
+
+Generated HTML reports escape recorded text, include their own styles and use a
+restrictive Content Security Policy. They contain no executable application
+scripts or external assets.
+
+The static website is separate from the CLI. It loads fonts and optional homepage
+animation libraries from a CDN. Its Explorer reads one JSON report in memory,
+without uploading it or saving report contents to browser storage. Only an
+explicitly chosen theme is saved. File size, structure and list lengths are
+bounded; the current limits include 5 MiB per file and 2,000 entries per list.
+Imported text is rendered as text, not HTML or executable commands. A fixed
+allowlist supplies the bundled examples. The Explorer displays the report's
+claims; it does not authenticate or rerun the recorded checks.
 
 ## Redaction is best effort
 
@@ -73,7 +99,9 @@ command text, captured output, notes, titles, warnings, the session pointer, and
 the lease: sensitive `name=value` and quoted/JSON `"name": "value"` pairs,
 `Authorization`/`Bearer` headers, OpenAI/AWS/GitHub-style keys,
 connection-string passwords, and PEM private-key blocks, each replaced with
-`[redacted]`. Pass `--no-redact` to store a command's output verbatim.
+`[redacted]`. Pass `--no-redact` to store raw command text and captured output
+for that command. Redaction applies to stored text, not to the command's live
+terminal output.
 
 This is **best effort and conservative; it is not a guarantee.** It recognizes
 known shapes and will miss secrets that do not match one. Known limitations
@@ -91,7 +119,6 @@ Native Windows and PowerShell are not supported.
 ## Reporting a vulnerability
 
 Please report security issues privately rather than opening a public issue. Use
-GitHub's "Report a vulnerability" (Security advisories) for this repository, or
-contact the maintainer through the address on their GitHub profile. Include
-steps to reproduce and the affected version; you will get an acknowledgement and
-a fix timeline.
+the repository's [private vulnerability report form](https://github.com/hari-kancharla/Debug-Brief/security/advisories/new).
+Include the affected version, steps to reproduce and the impact. Remove unrelated
+secrets and personal data from logs. The maintainer can follow up privately.