@blundergoat/gruff-ts 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,12 +1,24 @@
 # Changelog
 
+## [0.1.1] - 2026-05-24
+
+Onboarding flow, machine-readable summaries, and a `waste` → `maintainability` pillar rename. Catalogue is now 119 rules across 11 pillars.
+
+- **Breaking**: pillar `waste` renamed to `maintainability` — rule IDs unchanged, but text/JSON/SARIF parsers, dashboard nav, and the `Pillar` TypeScript union must update. Rules `docs.todo-density` and `naming.abbreviation` removed (both opt-in advisories), along with the now-unused `allowlists.abbreviationDenylist` config key; stale entries are silently ignored.
+- **Added**: `gruff-ts init` writes the default `.gruff-ts.yaml`, refusing to overwrite any supported config name without `--force` (which preserves existing `paths.ignore` entries). `analyse`, `summary`, `report`, and `dashboard` auto-prompt for `init` when no config is found, gated by `--no-interaction`, `--silent`/`--quiet`, and TTY checks so it never fires in CI.
+- **Added**: `summary --format=json` emits the new `gruff.summary.v1` schema; `summary --top <n>` controls digest size; a baseline status line surfaces source and suppression count. `dashboard --project-root <path>` sets the default scan root.
+- **Added**: docs index (`docs/README.md`) plus `ci-integration.md`, `dashboard.md`, `output-formats.md`, `rules.md`; CI now runs `npm audit --audit-level=moderate`.
+- **Fixed**: `summary`/`list-rules` `--format` rejects unsupported values via Commander instead of coercing to `text`; CLI switched to `parseAsync` so async handler rejections exit with the correct code.
+- **Fixed**: `summary --top <n>` now actually controls file-offender count beyond 10. `gruff.analysis.v1` `score.topOffenders` is now the full sorted file list (was capped at 10); HTML report and `--format=hotspot` still cap their own output at 10 rows. `init --force` help text now reflects that it also overrides the refusal triggered by non-canonical configs (`.gruff.yaml`/`.yml`/`.json`). `--top` added to the known-CLI-flag list so comments documenting it no longer trip `docs.stale-comment`.
+- **Changed**: docs filenames lowercased (`CONFIGURATION.md` → `configuration.md`, `RELEASING.md` → `releasing.md`, `REPORTS_AND_CI.md` → `reports-and-ci.md`).
+
 ## [0.1.0] - 2026-05-23
 
 Initial public release of the `@blundergoat/gruff-ts` npm package.
 
 - TypeScript/JavaScript code quality scanner: 121 rules across 11 pillars
-  (complexity, dead-code, design, documentation, modernisation, naming,
-  security, sensitive-data, size, test-quality, waste).
+  (complexity, dead-code, design, documentation, maintainability,
+  modernisation, naming, security, sensitive-data, size, test-quality).
 - CLI commands: `analyse`, `summary`, `report`, `list-rules`, `dashboard`,
   `completion`.
 - Output formats: `text`, `json`, `html`, `markdown`, `github`, `hotspot`,

package/CONTRIBUTING.md

@@ -68,9 +68,9 @@ Update docs when behavior changes:
 
 - `README.md` for user-facing workflow changes.
 - `CHANGELOG.md` for release-visible changes.
-- `docs/CONFIGURATION.md` for config shape or threshold changes.
-- `docs/REPORTS_AND_CI.md` for output, CI, dashboard, or baseline changes.
-- `docs/RELEASING.md` for release process changes.
+- `docs/configuration.md` for config shape or threshold changes.
+- `docs/reports-and-ci.md` for output, CI, dashboard, or baseline changes.
+- `docs/releasing.md` for release process changes.
 
 ## Pull Request Checklist
 

package/README.md

@@ -1,23 +1,38 @@
 # gruff-ts
 
-`gruff-ts` is a static analyzer for TypeScript and JavaScript projects. The
-dependency-light Node.js CLI scans source, tests, package metadata, and
-common config files, then reports quality findings across 11 pillars with
-stable fingerprints for baselines and repeatable machine output.
+`gruff-ts` is an opinionated static analyzer for TypeScript and JavaScript projects. The dependency-light Node.js CLI scans source, tests, package metadata, and common config files, then emits reports for terminals, CI annotations, SARIF consumers, static HTML, and a local dashboard. It is heuristic static analysis; run it beside `tsc`, ESLint, tests, dependency scanners, and code review, not instead of them.
 
-The 0.1.0 release ships 121 rules across 11 pillars,
-JSON/HTML/Markdown/GitHub/SARIF/hotspot output, baseline support, changed-file
-filtering, local score history, a rule catalogue, and a dark local dashboard.
-Scanned file types include TypeScript, JavaScript, CSS, JSON, YAML, TOML, INI,
-XML, and `.env*`.
+## Status At A Glance
+
+| Field | Value |
+| --- | --- |
+| Release line | Published `0.1.0` package line |
+| Runtime | Node.js `22+` |
+| Package | `@blundergoat/gruff-ts` |
+| Binary | `gruff-ts` |
+| Rule catalogue | 119 rules across 11 pillars |
+| Primary config | `.gruff-ts.yaml`; `.gruff.json`, `.gruff.yaml`, and `.gruff.yml` are fallback files |
+| Analysis schema | `gruff.analysis.v1` |
+| Baseline schema | `gruff.baseline.v1` |
+| Severity gate | `--fail-on` with `none`, `advisory`, `warning`, `error` |
+| Dashboard | `127.0.0.1:8767` by default |
+
+Scanned file types include TypeScript, JavaScript, CSS, JSON, YAML, TOML, INI, XML, and `.env*`.
+
+## Requirements
+
+- Node.js `22+`, matching [`package.json`](package.json).
+- npm for source-checkout development.
+- Git only for diff modes.
 
 ## Install
 
-Install the scoped npm package; it exposes the `gruff-ts` CLI command:
+Install as a project dev dependency:
 
 ```bash
 npm install --save-dev @blundergoat/gruff-ts
-npx gruff-ts analyse . --fail-on=none
+./node_modules/.bin/gruff-ts init
+./node_modules/.bin/gruff-ts summary
 ```
 
 From this checkout:
@@ -29,170 +44,90 @@ npm install
 
 ## Quick Start
 
-Run an exploratory scan without failing the shell on findings:
-
 ```bash
-gruff-ts analyse . --fail-on=none
-```
+# Create the project config.
+./node_modules/.bin/gruff-ts init
 
-Scan specific paths:
+# Review the current finding mix.
+./node_modules/.bin/gruff-ts summary
 
-```bash
-gruff-ts analyse src fixtures/sample.ts --fail-on=none
-```
+# Explore without failing because of findings.
+./node_modules/.bin/gruff-ts analyse . --fail-on=none
 
-Generate a static HTML report:
+# Gate on warning and error findings.
+./node_modules/.bin/gruff-ts analyse . --fail-on=warning
 
-```bash
-gruff-ts report . --output gruff-report.html
-```
+# Emit SARIF for code scanning.
+./node_modules/.bin/gruff-ts analyse . --format=sarif --fail-on=none > gruff-ts.sarif
 
-Start the local dashboard:
+# Generate a fresh-start baseline.
+./node_modules/.bin/gruff-ts analyse . --generate-baseline gruff-baseline.json --fail-on=none
 
-```bash
-gruff-ts dashboard
+# Start the local dashboard.
+./node_modules/.bin/gruff-ts dashboard
 ```
 
-The dashboard binds to `127.0.0.1:8767` by default.
-
-## What It Checks
-
-Findings are grouped into 11 public pillars:
-
-- `size`
-- `complexity`
-- `dead-code`
-- `waste`
-- `naming`
-- `documentation`
-- `modernisation`
-- `security`
-- `sensitive-data`
-- `test-quality`
-- `design`
-
-Inspect the exact rule ids, severities, confidence levels, remediation text,
-threshold values, and options:
-
-```bash
-gruff-ts list-rules
-gruff-ts list-rules --format=json
-```
+Open `http://127.0.0.1:8767/` for the dashboard.
 
 ## Commands
 
 | Command | Purpose |
 | --- | --- |
-| `analyse [paths...]` | Run the scanner and print findings. |
-| `summary [paths...]` | Print per-pillar counts, top rules, and top file offenders without per-finding output. |
-| `report [paths...]` | Render an HTML or JSON report, optionally to a file. |
-| `list-rules` | Print rule catalogue metadata. |
-| `dashboard` | Serve the local HTTP dashboard. |
+| `analyse [paths...]` | Run the analyzer and print findings. |
+| `summary [paths...]` | Print compact score, pillar, rule, and file summaries. |
+| `report [paths...]` | Render an HTML or JSON report to stdout or `--output`. |
+| `init` | Write the default `.gruff-ts.yaml` to the current directory (`--force` to overwrite). |
+| `list-rules` | Print rule metadata as text or JSON. |
+| `dashboard` | Serve the local browser dashboard. |
 | `completion [shell]` | Print a shell completion script for `bash`, `zsh`, or `fish`. |
-| `list` | Print the Symfony-style command catalogue. |
+| `list`, `help` | Show command lists and command-specific help. |
 
-Useful help commands:
-
-```bash
-gruff-ts --help
-gruff-ts list
-gruff-ts analyse --help
-gruff-ts summary --help
-gruff-ts report --help
-gruff-ts dashboard --help
-```
-
-Global console options match the `gruff` PHP CLI surface: `--silent`,
-`--quiet`, `--ansi` / `--no-ansi`, `--no-interaction`, and `-v` / `-vv` /
-`-vvv`. The command menu uses the same ANSI colour treatment as `gruff` when
-stdout is a TTY; `--ansi` forces colour and `--no-ansi` disables it.
+Global console options match the broader gruff CLI surface: `--silent`, `--quiet`, `--ansi` / `--no-ansi`, `--no-interaction`, and `-v` / `-vv` / `-vvv`.
 
 ## Output Formats
 
-`analyse` supports:
+`analyse --format <fmt>` accepts:
 
-| Format | Use case |
+| Format | Use it for |
 | --- | --- |
 | `text` | Human terminal output. |
-| `json` | Full machine-readable `gruff.analysis.v1` report. |
-| `html` | Self-contained dark inspection report. |
-| `markdown` | Short Markdown summary. |
-| `github` | GitHub Actions annotation commands. |
-| `hotspot` | Compact `gruff.hotspot.v1` top-offender payload. |
-| `sarif` | SARIF 2.1.0 code-scanning output. |
-
-Examples:
-
-```bash
-gruff-ts analyse . --format=json --fail-on=none
-gruff-ts analyse . --format=github --fail-on=warning
-gruff-ts analyse . --format=hotspot --fail-on=none
-gruff-ts analyse . --format=sarif --fail-on=none > gruff.sarif
-```
+| `json` | Full `gruff.analysis.v1` report. |
+| `html` | Self-contained inspection report. |
+| `markdown` | Pull-request or issue comment summary. |
+| `github` | GitHub Actions workflow annotations. |
+| `hotspot` | `gruff.hotspot.v1` file-offender JSON. |
+| `sarif` | SARIF 2.1.0 for code scanning. |
 
-`report` supports `html` and `json`:
+`report --format <fmt>` accepts `html` and `json`.
 
-```bash
-gruff-ts report . --format=json --output gruff-report.json
-```
+## Exit Codes
 
-## CI
+| Code | Meaning |
+| --- | --- |
+| `0` | Run completed and no finding met `--fail-on`. |
+| `1` | At least one finding met `--fail-on`. |
+| `2` | Fatal diagnostic such as missing input, parse error, config error, diff failure, baseline failure, or invalid input. |
 
 `analyse` defaults to `--fail-on error`.
 
-```bash
-# Exploratory scan: never fail because of findings.
-gruff-ts analyse . --fail-on=none
-
-# CI gate only on error findings.
-gruff-ts analyse . --fail-on=error
-
-# Stricter CI gate on warnings and errors.
-gruff-ts analyse . --fail-on=warning
-```
-
-Exit codes:
+## CI Usage
 
-- `0`: scan completed and no finding met `--fail-on`.
-- `1`: scan completed and at least one finding met `--fail-on`.
-- `2`: scan produced diagnostics such as missing inputs or parse/config errors.
-
-Changed-file scans:
+Generic CI command:
 
 ```bash
-gruff-ts analyse . --diff=working-tree --format=github --fail-on=warning
-gruff-ts analyse . --diff=staged --format=json --fail-on=none
+./node_modules/.bin/gruff-ts analyse . --format=github --fail-on=warning
 ```
 
-`--diff` accepts `working-tree`, `staged`, `unstaged`, or a base ref.
-
-Security-focused CI can run without baseline suppression so new error-severity
-security or sensitive-data findings cannot be hidden by an adoption baseline:
+SARIF jobs can write an artifact for code scanning:
 
 ```bash
-gruff-ts analyse . --no-baseline --fail-on=error
+./node_modules/.bin/gruff-ts analyse . --format=sarif --fail-on=none > gruff-ts.sarif
 ```
 
-## Baselines And History
-
-Baselines suppress existing findings by stable fingerprint so teams can adopt
-the tool without fixing every current issue first.
+Security-focused gates can bypass adoption baselines:
 
 ```bash
-gruff-ts analyse . --generate-baseline gruff-baseline.json --fail-on=none
-gruff-ts analyse . --baseline gruff-baseline.json --fail-on=warning
-gruff-ts analyse . --no-baseline --fail-on=none
-```
-
-Baseline files use `schemaVersion: "gruff.baseline.v1"`.
-
-`report` is intended for raw inspection output and does not accept
-`--baseline`; use `analyse` when you need baseline suppression in CI.
-
-Append local score history:
-
-```bash
-gruff-ts analyse . --history-file .gruff-history.json --fail-on=none
+./node_modules/.bin/gruff-ts analyse . --no-baseline --fail-on=error
 ```
 
 ## Configuration
@@ -204,18 +139,7 @@ gruff-ts analyse . --history-file .gruff-history.json --fail-on=none
 3. `.gruff.yaml`
 4. `.gruff.yml`
 
-Use an explicit config or skip config loading:
-
-```bash
-gruff-ts analyse . --config .gruff-ts.yaml
-gruff-ts analyse . --no-config
-```
-
-Recursive scans respect root and nested `.gitignore` files. Use
-`--include-ignored` to include default and Git-ignored paths for a run;
-`paths.ignore` entries still apply as project policy.
-
-Minimal YAML example:
+Use `--config <path>` for an explicit file or `--no-config` to skip config loading. Recursive scans respect root and nested `.gitignore` files; `--include-ignored` includes default and Git-ignored paths for one run, but `paths.ignore` entries still apply as project policy.
 
 ```yaml
 paths:
@@ -237,41 +161,74 @@ rules:
     severity: warning
 ```
 
-See [Configuration](docs/CONFIGURATION.md) for the full config shape and
-examples.
+See [Configuration](docs/configuration.md) for the full config shape.
 
-## Dashboard
+## Rules And Pillars
+
+The v0.1 catalogue contains 119 rules:
+
+| Pillar | Rules |
+| --- | ---: |
+| `complexity` | 3 |
+| `dead-code` | 1 |
+| `design` | 6 |
+| `documentation` | 17 |
+| `maintainability` | 14 |
+| `modernisation` | 14 |
+| `naming` | 10 |
+| `security` | 27 |
+| `sensitive-data` | 8 |
+| `size` | 4 |
+| `test-quality` | 15 |
+
+Use `./node_modules/.bin/gruff-ts list-rules --format=json` for exact rule IDs, severities, confidence levels, remediation text, thresholds, and options.
+
+## Baselines And Changed-Code Scans
 
-Start the local dashboard:
+Baselines suppress reviewed findings by stable fingerprint:
 
 ```bash
-gruff-ts dashboard --host 127.0.0.1 --port 8767 --project-root .
+./node_modules/.bin/gruff-ts analyse . --generate-baseline gruff-baseline.json --fail-on=none
+./node_modules/.bin/gruff-ts analyse . --baseline gruff-baseline.json --fail-on=warning
+./node_modules/.bin/gruff-ts analyse . --no-baseline --fail-on=none
 ```
 
-The dashboard serves a local iframe report and a compact controls panel. Keep
-the default loopback bind unless the network is trusted. The `/scan` endpoint
-analyses filesystem paths from request parameters, so the bind address is the
-main safety boundary.
+Changed-file scans use Git only when requested:
 
-## Safety And Limitations
+```bash
+./node_modules/.bin/gruff-ts analyse . --diff=working-tree --format=github --fail-on=warning
+./node_modules/.bin/gruff-ts analyse . --diff=staged --format=json --fail-on=none
+```
 
-- Secret-like findings include redacted previews; raw secret values should not
-  appear in findings or rendered output.
-- The scanner is heuristic. It is not a TypeScript compiler, type checker, or
-  full JavaScript parser.
-- Rule confidence is included in the rule catalogue and each finding. Treat low
-  and medium confidence findings as review prompts.
-- Baselines suppress matching fingerprints. Review baseline diffs carefully so
-  new findings are not hidden by accident.
+`--diff` accepts `working-tree`, `staged`, `unstaged`, or a base ref. `report` renders raw inspection output and does not accept `--baseline`; use `analyse` when baseline suppression matters.
 
-## Documentation
+## Dashboard
 
-- [Changelog](CHANGELOG.md)
-- [Configuration](docs/CONFIGURATION.md)
-- [Reports and CI](docs/REPORTS_AND_CI.md)
-- [Contributing](CONTRIBUTING.md)
-- [Security](SECURITY.md)
-- [Release checklist](docs/RELEASING.md)
+```bash
+./node_modules/.bin/gruff-ts dashboard --host 127.0.0.1 --port 8767 --project-root .
+```
+
+The dashboard serves a local iframe report and compact controls panel. It has no authentication; keep the default loopback bind unless the network is trusted. The `/scan` endpoint analyses filesystem paths from request parameters, so the bind address is the main safety boundary.
+
+In polyglot repositories, `gruff-ts` defaults to port `8767`, `gruff-rs` defaults to `8766`, and `gruff-go`, `gruff-php`, and `gruff-py` default to `8765`; use `--port` when running multiple dashboards at the same time.
+
+## Trust Boundary
+
+Default scans are local source inspections. `gruff-ts` parses supported source, config, and package metadata files; it does not execute target application code, run tests, invoke the TypeScript compiler, query package registries, or read vulnerability feeds. Git is used only for explicit diff modes. Secret-like findings use redacted previews; raw secret values should not appear in terminal, JSON, SARIF, GitHub, Markdown, hotspot, or HTML output.
+
+## Stability Contract
+
+The `0.1.x` line treats rule IDs, finding fingerprints, baseline identity, `gruff.analysis.v1`, `gruff.baseline.v1`, `gruff.hotspot.v1`, SARIF rendering, and CLI exit semantics as compatibility-sensitive. Breaking changes should be tagged as a future minor release and recorded in [`CHANGELOG.md`](CHANGELOG.md).
+
+## How It Compares
+
+| Tool | Relationship |
+| --- | --- |
+| `tsc` | Type checking. `gruff-ts` does not prove type correctness or replace compiler diagnostics. |
+| ESLint | Rule-driven linting. `gruff-ts` adds scoring, baselines, reports, dashboard, and cross-file/project-quality signals. |
+| Prettier / formatters | Formatting only. `gruff-ts` does not format code. |
+| Knip / ts-prune | Focused unused export/dead-code tools. `gruff-ts` includes broader quality and security-oriented heuristics. |
+| `npm audit` / dependency scanners | Advisory-backed dependency checks. `gruff-ts` reports local static signals and does not replace advisory feeds. |
 
 ## Development
 
@@ -283,16 +240,17 @@ npm run start-dev
 ./bin/gruff-ts analyse . --fail-on=none
 ```
 
-Source lives under `src/`: `src/cli.ts` is the thin bootstrap,
-`src/cli-program.ts` owns Commander wiring, `src/analyser.ts` orchestrates the
-scan, `src/rules.ts` holds the descriptor catalogue, and focused sibling
-modules own rule packs and renderers. Tests live in focused `src/*.test.ts`
-files.
+Source lives under `src/`: `src/cli.ts` is the bootstrap, `src/cli-program.ts` owns Commander wiring, `src/analyser.ts` orchestrates scans, and focused sibling modules own rules and renderers.
 
-To bump the released version, run `scripts/bump-version.sh <new-version>` - it
-updates `package.json` and `src/constants.ts` in lockstep so the CLI
-`--version` output stays consistent with the published `@blundergoat/gruff-ts`
-package.
+## Documentation
+
+- [Changelog](CHANGELOG.md)
+- [Configuration](docs/configuration.md)
+- [Rules catalogue](docs/rules.md)
+- [Reports and CI](docs/reports-and-ci.md)
+- [Release checklist](docs/releasing.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
 
 ## Author
 

package/docs/README.md

@@ -0,0 +1,23 @@
+# gruff-ts docs
+
+Use these docs with the top-level README for the stable user-facing surface.
+
+## Core Docs
+
+- [Configuration](configuration.md) - config discovery, schema, allowlists, and rule overrides.
+- [Rules](rules.md) - rule IDs, severities, thresholds, and remediation guidance.
+- [Output Formats](output-formats.md) - text, JSON, HTML, Markdown, GitHub annotations, hotspot, and SARIF.
+- [CI Integration](ci-integration.md) - GitHub Actions, SARIF upload, baselines, and diff scans.
+- [Dashboard](dashboard.md) - local dashboard flags and safety model.
+- [Releasing](releasing.md) - release checks and packaging notes.
+
+## Extra Docs
+
+- [Reports And CI](reports-and-ci.md) - combined reporting and CI details retained for existing links.
+
+## Shared Contract
+
+Cross-language naming and CLI expectations live in
+[`../../CONTRACT.md`](../../CONTRACT.md). TypeScript keeps `summary` analysis
+flags as documented extensions while also supporting the common `--format` and
+`--top` summary surface.

package/docs/ci-integration.md

@@ -0,0 +1,63 @@
+# CI Integration
+
+gruff-ts is designed to run as a deterministic CI quality gate.
+
+## GitHub Actions
+
+```yaml
+name: gruff-ts
+
+on: [push, pull_request]
+
+jobs:
+  analyse:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm ci
+      - run: ./bin/gruff-ts analyse src --format=sarif --fail-on=none > gruff-ts.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: gruff-ts.sarif
+```
+
+## Quality Gate
+
+For blocking jobs, choose the lowest severity that should fail the build:
+
+```sh
+./bin/gruff-ts analyse src --fail-on=warning
+```
+
+Use `--fail-on=none` when the job should only publish reports.
+
+## Baselines
+
+Generate an adoption baseline after reviewing current findings:
+
+```sh
+./bin/gruff-ts analyse src --generate-baseline gruff-baseline.json --fail-on=none
+```
+
+Future scans auto-apply `gruff-baseline.json` when present. Use
+`--no-baseline` to audit the full unsuppressed result.
+
+## Diff Scans
+
+TypeScript supports working-tree, staged, unstaged, and base-ref diff scans:
+
+```sh
+./bin/gruff-ts analyse src --diff=working-tree --format=github --fail-on=warning
+./bin/gruff-ts analyse src --diff=origin/main --format=json --fail-on=none
+```
+
+## Check
+
+Run the local TypeScript gate before release:
+
+```sh
+npm run check
+```

package/docs/{CONFIGURATION.md → configuration.md}

@@ -41,7 +41,6 @@ allowlists:
   booleanPrefixes: [is, has, can, should, does, did, was, will, may, in, scan, supports, requires]
   hungarianPrefixes: [str, obj, arr, bool, int, num]
   placeholderNames: [foo, bar, baz, tmp, temp, thing, stuff, data, value, item]
-  abbreviationDenylist: [ctx, pkg, opts, fn, idx, cb]
   negativeBooleanAllowed: [nostore, nofollow, noreferrer, noscript, noindex]
   knownAcronyms: [url, http, https, id, xml, json, html, css, api, sql, db, io, ui, uuid, ip, tcp, udp, ast, cli, npm]
 
@@ -116,7 +115,6 @@ fingerprints:
 | `booleanPrefixes` | `naming.boolean-prefix` | Replaces the accepted boolean-name prefixes such as `is`, `has`, `should`, `may`, `supports`, and `requires`. |
 | `hungarianPrefixes` | `naming.hungarian-notation` | Replaces type-style prefixes to flag. |
 | `placeholderNames` | `naming.identifier-quality`, `naming.generic-parameter` | Replaces placeholder words; numbered suffix checks stay active. |
-| `abbreviationDenylist` | `naming.abbreviation` | Replaces the opt-in abbreviation denylist. |
 | `negativeBooleanAllowed` | `naming.negative-boolean` | Replaces domain terms allowed to start with `no`. |
 | `knownAcronyms` | `naming.acronym-case` | Replaces acronyms checked for mixed casing. |
 
@@ -165,6 +163,8 @@ gruff-ts list-rules
 gruff-ts list-rules --format=json
 ```
 
+See [Rules](./rules.md) for the full rule catalogue grouped by pillar.
+
 ## Example Project Config
 
 ```yaml
@@ -201,20 +201,3 @@ rules:
     threshold: 12
     severity: advisory
 ```
-
-## Adoption Defaults
-
-Two noisy-by-nature rules are present in the public catalogue but disabled by
-default in this repo config:
-
-```yaml
-rules:
-  docs.todo-density:
-    enabled: false
-  naming.abbreviation:
-    enabled: false
-```
-
-`docs.todo-without-tracking` remains enabled because it checks whether a TODO
-has owner, issue, date, ADR, or task context instead of counting raw TODO
-markers.

package/docs/dashboard.md

@@ -0,0 +1,29 @@
+# Dashboard
+
+`gruff-ts dashboard` serves a local browser dashboard for repeated analysis.
+
+## Start
+
+```sh
+./bin/gruff-ts dashboard --host 127.0.0.1 --port 8767 --project-root .
+```
+
+## Options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `--host` | `127.0.0.1` | Bind host. |
+| `--port` | `8767` | Bind port. |
+| `--project-root` | current directory | Initial project root. |
+
+## Safety
+
+The dashboard has no authentication and should stay bound to loopback unless the
+network is trusted. The `/scan` endpoint analyses filesystem paths from request
+parameters, so the bind address is the safety boundary.
+
+## Polyglot Repos
+
+`gruff-ts` defaults to port `8767`, `gruff-rs` defaults to `8766`, and Go, PHP,
+and Python default to `8765`. Use `--port` when running multiple dashboards at
+once.