agent-codinglanguage-mapper 1.0.0__tar.gz → 1.1.1__tar.gz

{agent_codinglanguage_mapper-1.0.0 → agent_codinglanguage_mapper-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-codinglanguage-mapper
-Version: 1.0.0
+Version: 1.1.1
 Summary: Agent-focused semantic mapping and language services for mixed-language codebases.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -47,7 +47,7 @@ Dynamic: license-file
 
 # Agent Coding Language Mapper
 
-`agent-codinglanguage-mapper` gives coding agents a bounded semantic view of mixed-language repositories. It maps Python, Rust, C#, Delphi, and C++ into one language-neutral index and exposes that index through a Python API, a command-line interface, Protocol 3, an LSP server, and an OpenCode skill/plugin pair.
+`agent-codinglanguage-mapper` gives coding agents a bounded semantic view of mixed-language repositories. It maps Python, Rust, C#, Delphi, and C++ into one language-neutral index and exposes that index through a Python API, a command-line interface, Protocol 3, an LSP server, and an OpenCode skill/plugin pair. It also detects repository coding conventions, audits source against them, and produces reviewable formatting patches before any explicit write.
 
 The mapper is designed for code investigation without sending whole files through `grep`, `cat`, or generic file-reading tools. Responses are paginated, carry stable target IDs and source citations, distinguish proven from partial relations, and preserve focus across follow-up requests.
 
@@ -99,6 +99,8 @@ The public types are:
 - `Project` and `SourceFile`
 - `Symbol`, `Reference`, and `Relation`
 - `Problem` and `SourceRange`
+- `CodingGuidelines`
+- `GuidelineProfile`, `GuidelineFinding`, `GuidelineChange`, and `GuidelineReport`
 
 Parser-native nodes are intentionally private. Ranges are zero-based and half-open. Rendered citations use one-based line numbers, for example `src/payment.py:42`.
 
@@ -124,6 +126,16 @@ codinglanguage-mapper index --root . --out .mapper/index.json
 # Discovery and parser diagnostics
 codinglanguage-mapper doctor --root . --format json
 
+# Detect and audit repository coding conventions
+codinglanguage-mapper guidelines detect --root . --format json
+codinglanguage-mapper guidelines audit --root . --format json
+
+# Preview a deterministic patch; this never changes source files
+codinglanguage-mapper guidelines format --root .
+
+# Apply the reviewed plan atomically
+codinglanguage-mapper guidelines format --root . --write
+
 # Language Server Protocol over stdio
 codinglanguage-mapper lsp --root .
 
@@ -133,6 +145,43 @@ codinglanguage-mapper worker --root .
 
 Available view layers are `overview`, `projects`, `languages`, `files`, `file`, `symbols`, `symbol`, `implementation`, `references`, and `problems`.
 
+## Coding Guidelines and Formatting
+
+The guidelines API uses the mapper's normal project discovery and language detection, so one request can audit a mixed Python, Rust, C#, Delphi, and C++ workspace. Detection is file-specific rather than one profile for the entire repository. Defaults are refined by language configuration and then by the nearest applicable `.editorconfig`, which has the highest precedence.
+
+```python
+from agent_codinglanguage_mapper import CodingGuidelines
+
+guidelines = CodingGuidelines.open(".", languages="auto")
+detected = guidelines.detect()
+audit = guidelines.audit()
+
+# A stable unified diff for agent or human review; no files are changed.
+patch = guidelines.patch()
+print(patch)
+
+# Mutation is rejected unless write=True is explicit.
+plan = guidelines.plan()
+applied = guidelines.apply(plan, write=True)
+print(applied.to_mapping())
+```
+
+`detect()` reports the effective profile and its configuration sources. `audit()` returns exact zero-based, half-open ranges for line length, indentation, line endings, trailing whitespace, and final-newline findings. Invalid supported values and unsupported EditorConfig properties are reported as non-fixable configuration findings; affected rules retain their previous effective value. Agents can use those findings to make source-aware improvements that are outside the formatter's conservative scope. `plan()` records original-content hashes, the guideline-configuration revision, and the exact replacement bytes. `apply()` rejects stale plans after either source or configuration changes, workspace-escaping paths, and symlinks; accepted writes use a same-directory temporary file and atomic replacement.
+
+The built-in formatter safely normalizes configured line endings, removes trailing whitespace outside protected multiline string literals, and applies the configured final-newline rule while preserving UTF-8 BOM, UTF-16, and legacy single-byte source encodings. When installed and runnable, the package delegates broader formatting to the language's established tool and validates the result with the mapper before planning it:
+
+| Language | Detected configuration | Preferred formatter |
+| --- | --- | --- |
+| Python | `pyproject.toml` (`ruff`) and `.editorconfig` | Ruff, then Black |
+| Rust | `rustfmt.toml`, `.rustfmt.toml`, and `.editorconfig` | `rustfmt` |
+| C# | `.editorconfig` common whitespace rules | `dotnet format whitespace` in an isolated temporary copy |
+| Delphi | RAD Studio-compatible defaults and `.editorconfig` | Built-in conservative formatter |
+| C++ | `.clang-format`, `_clang-format`, and `.editorconfig` | `clang-format` |
+
+Native formatter executables are optional and are never downloaded or installed by this package. A missing tool selects the built-in formatter. A timeout, nonzero exit, invalid output, or other native failure also falls back to the built-in formatter and emits a structured `native-formatter-failed` finding instead of discarding the audit. No formatter command is executed through a shell.
+
+`guidelines audit` exits with status 1 when findings exist, making it suitable for CI. `guidelines format` without `--write` always prints the unified diff and leaves the workspace untouched. The only mutating CLI form is `guidelines format --write`.
+
 ## Protocol 3
 
 Protocol 3 is the bounded request/response contract used by the worker and OpenCode plugin.
@@ -270,27 +319,37 @@ Example generic client configuration:
 
 ## OpenCode Integration
 
-Install the packaged skill, plugin, and restricted agent configuration into a repository:
+Install the package-named skill, Markdown agent, and plugin into a repository:
 
 ```bash
-codinglanguage-mapper opencode install --target . --write
+codinglanguage-mapper opencode install --target .
 ```
 
 This creates:
 
 ```text
-.agents/skills/mixed-codebase-navigator/SKILL.md
+.agents/skills/agent-codinglanguage-mapper/SKILL.md
+.opencode/agents/agent-codinglanguage-mapper.md
 .opencode/plugins/codebase_map.ts
-opencode.json
 ```
 
-The generated `mixed-codebase-navigator` agent denies all tools by default and permits only `skill` and `codebase_map`. The plugin maps the active OpenCode directory, serializes Protocol 3 requests through one worker, applies a hard timeout, reports bounded worker `stderr`, restarts after failure, and preserves focus plus warm parser indexes across short idle gaps. It stops the worker when the session is deleted or after 60 seconds without another mapper request.
+The generated `agent-codinglanguage-mapper` agent denies all tools by default and permits only its package-named skill, `codebase_map`, and `code_guidelines`. The plugin maps the active OpenCode directory, serializes Protocol 3 requests through one worker, applies a hard timeout, reports bounded worker `stderr`, restarts after failure, and preserves focus plus warm parser indexes across short idle gaps. It stops the worker when the session is deleted or after 60 seconds without another mapper request.
+
+The installer never reads or changes `opencode.json`; user configuration remains
+user-owned. The deprecated `--write`, `--write-config`, and `--write-agent`
+compatibility flags are accepted, but the Markdown agent is installed by
+default and those flags do not enable configuration writes.
+
+`code_guidelines` exposes four actions: `detect`, `audit`, `patch`, and `apply`. The first three are read-only. `apply` is rejected unless its request contains `write: true`, so the agent must inspect a patch before it can opt into mutation.
+
+The agent's YAML frontmatter contains its restricted permissions; no matching
+JSON agent block is required.
 
 Run it with:
 
 ```bash
 opencode run \
-  --agent mixed-codebase-navigator \
+  --agent agent-codinglanguage-mapper \
   "Find PaymentService, inspect its implementation, and cite the callers. Use only the installed skill and codebase_map."
 ```
 
@@ -303,6 +362,8 @@ A typical investigation should:
 5. Use `trace` only for explicit Protocol 3 relations.
 6. Follow `next_cursor` when evidence is truncated.
 
+A formatting task should first call `code_guidelines` with `detect`, then `audit`, then `patch`. The agent can either improve source-aware findings itself or apply the package plan with `action: apply` and `write: true`. It must finish with another `audit`; it must never use `apply` merely to discover what would change.
+
 ## Large-Workspace Performance
 
 The release benchmark generates one valid file above 100,000 lines for each language and a mixed workspace above 500,000 lines. On the reference Apple Silicon Mac, release budgets are:
@@ -326,7 +387,7 @@ Private Linux CI records and uploads the same measurements with `--report-only`;
 
 ## Offline Ornith/OpenCode Evaluation
 
-The repository contains six release E2Es: Python, Rust, C#, Delphi, C++, and a mixed-language FFI workspace. They use the pinned local Ornith revision through vLLM 0.23.0 and OpenCode 1.17.18. The Python scenario continues the same session through a headless OpenCode server and must inspect the focused symbol in a second turn without another `find` or explicit `target_id`, proving that the plugin preserves its warm worker. It then opens an independent session whose target-less `inspect` must be empty, proving that focus never crosses chat boundaries. The harness fails if a model shard is missing, a download is attempted, an unapproved tool is called, any assistant message uses a different agent, model, or provider, a worker survives server shutdown, or golden file/line evidence is absent.
+The repository contains seven release E2Es: Python, Rust, C#, Delphi, C++, a mixed-language FFI workspace, and a coding-guidelines write workflow. They use the pinned local Ornith revision through vLLM 0.23.0 and OpenCode 1.17.18. The guidelines scenario must detect and audit the profile, inspect a patch, explicitly apply it with `write: true`, and finish with a clean audit. The Python scenario continues the same session through a headless OpenCode server and must inspect the focused symbol in a second turn without another `find` or explicit `target_id`, proving that the plugin preserves its warm worker. It then opens an independent session whose target-less `inspect` must be empty, proving that focus never crosses chat boundaries. The harness fails if a model shard is missing, a download is attempted, an unapproved tool is called, any assistant message uses a different agent, model, or provider, a worker survives server shutdown, or required evidence is absent.
 
 Inspect the plan without launching a model:
 
@@ -340,7 +401,7 @@ Verify the exact local executables, versions, model revision, and weight shards:
 python scripts/run_opencode_e2e.py --verify-runtime
 ```
 
-Run all six scenarios and retain complete evidence:
+Run all seven scenarios and retain complete evidence:
 
 ```bash
 HF_HUB_OFFLINE=1 \

{agent_codinglanguage_mapper-1.0.0 → agent_codinglanguage_mapper-1.1.1}/README.md

@@ -1,6 +1,6 @@
 # Agent Coding Language Mapper
 
-`agent-codinglanguage-mapper` gives coding agents a bounded semantic view of mixed-language repositories. It maps Python, Rust, C#, Delphi, and C++ into one language-neutral index and exposes that index through a Python API, a command-line interface, Protocol 3, an LSP server, and an OpenCode skill/plugin pair.
+`agent-codinglanguage-mapper` gives coding agents a bounded semantic view of mixed-language repositories. It maps Python, Rust, C#, Delphi, and C++ into one language-neutral index and exposes that index through a Python API, a command-line interface, Protocol 3, an LSP server, and an OpenCode skill/plugin pair. It also detects repository coding conventions, audits source against them, and produces reviewable formatting patches before any explicit write.
 
 The mapper is designed for code investigation without sending whole files through `grep`, `cat`, or generic file-reading tools. Responses are paginated, carry stable target IDs and source citations, distinguish proven from partial relations, and preserve focus across follow-up requests.
 
@@ -52,6 +52,8 @@ The public types are:
 - `Project` and `SourceFile`
 - `Symbol`, `Reference`, and `Relation`
 - `Problem` and `SourceRange`
+- `CodingGuidelines`
+- `GuidelineProfile`, `GuidelineFinding`, `GuidelineChange`, and `GuidelineReport`
 
 Parser-native nodes are intentionally private. Ranges are zero-based and half-open. Rendered citations use one-based line numbers, for example `src/payment.py:42`.
 
@@ -77,6 +79,16 @@ codinglanguage-mapper index --root . --out .mapper/index.json
 # Discovery and parser diagnostics
 codinglanguage-mapper doctor --root . --format json
 
+# Detect and audit repository coding conventions
+codinglanguage-mapper guidelines detect --root . --format json
+codinglanguage-mapper guidelines audit --root . --format json
+
+# Preview a deterministic patch; this never changes source files
+codinglanguage-mapper guidelines format --root .
+
+# Apply the reviewed plan atomically
+codinglanguage-mapper guidelines format --root . --write
+
 # Language Server Protocol over stdio
 codinglanguage-mapper lsp --root .
 
@@ -86,6 +98,43 @@ codinglanguage-mapper worker --root .
 
 Available view layers are `overview`, `projects`, `languages`, `files`, `file`, `symbols`, `symbol`, `implementation`, `references`, and `problems`.
 
+## Coding Guidelines and Formatting
+
+The guidelines API uses the mapper's normal project discovery and language detection, so one request can audit a mixed Python, Rust, C#, Delphi, and C++ workspace. Detection is file-specific rather than one profile for the entire repository. Defaults are refined by language configuration and then by the nearest applicable `.editorconfig`, which has the highest precedence.
+
+```python
+from agent_codinglanguage_mapper import CodingGuidelines
+
+guidelines = CodingGuidelines.open(".", languages="auto")
+detected = guidelines.detect()
+audit = guidelines.audit()
+
+# A stable unified diff for agent or human review; no files are changed.
+patch = guidelines.patch()
+print(patch)
+
+# Mutation is rejected unless write=True is explicit.
+plan = guidelines.plan()
+applied = guidelines.apply(plan, write=True)
+print(applied.to_mapping())
+```
+
+`detect()` reports the effective profile and its configuration sources. `audit()` returns exact zero-based, half-open ranges for line length, indentation, line endings, trailing whitespace, and final-newline findings. Invalid supported values and unsupported EditorConfig properties are reported as non-fixable configuration findings; affected rules retain their previous effective value. Agents can use those findings to make source-aware improvements that are outside the formatter's conservative scope. `plan()` records original-content hashes, the guideline-configuration revision, and the exact replacement bytes. `apply()` rejects stale plans after either source or configuration changes, workspace-escaping paths, and symlinks; accepted writes use a same-directory temporary file and atomic replacement.
+
+The built-in formatter safely normalizes configured line endings, removes trailing whitespace outside protected multiline string literals, and applies the configured final-newline rule while preserving UTF-8 BOM, UTF-16, and legacy single-byte source encodings. When installed and runnable, the package delegates broader formatting to the language's established tool and validates the result with the mapper before planning it:
+
+| Language | Detected configuration | Preferred formatter |
+| --- | --- | --- |
+| Python | `pyproject.toml` (`ruff`) and `.editorconfig` | Ruff, then Black |
+| Rust | `rustfmt.toml`, `.rustfmt.toml`, and `.editorconfig` | `rustfmt` |
+| C# | `.editorconfig` common whitespace rules | `dotnet format whitespace` in an isolated temporary copy |
+| Delphi | RAD Studio-compatible defaults and `.editorconfig` | Built-in conservative formatter |
+| C++ | `.clang-format`, `_clang-format`, and `.editorconfig` | `clang-format` |
+
+Native formatter executables are optional and are never downloaded or installed by this package. A missing tool selects the built-in formatter. A timeout, nonzero exit, invalid output, or other native failure also falls back to the built-in formatter and emits a structured `native-formatter-failed` finding instead of discarding the audit. No formatter command is executed through a shell.
+
+`guidelines audit` exits with status 1 when findings exist, making it suitable for CI. `guidelines format` without `--write` always prints the unified diff and leaves the workspace untouched. The only mutating CLI form is `guidelines format --write`.
+
 ## Protocol 3
 
 Protocol 3 is the bounded request/response contract used by the worker and OpenCode plugin.
@@ -223,27 +272,37 @@ Example generic client configuration:
 
 ## OpenCode Integration
 
-Install the packaged skill, plugin, and restricted agent configuration into a repository:
+Install the package-named skill, Markdown agent, and plugin into a repository:
 
 ```bash
-codinglanguage-mapper opencode install --target . --write
+codinglanguage-mapper opencode install --target .
 ```
 
 This creates:
 
 ```text
-.agents/skills/mixed-codebase-navigator/SKILL.md
+.agents/skills/agent-codinglanguage-mapper/SKILL.md
+.opencode/agents/agent-codinglanguage-mapper.md
 .opencode/plugins/codebase_map.ts
-opencode.json
 ```
 
-The generated `mixed-codebase-navigator` agent denies all tools by default and permits only `skill` and `codebase_map`. The plugin maps the active OpenCode directory, serializes Protocol 3 requests through one worker, applies a hard timeout, reports bounded worker `stderr`, restarts after failure, and preserves focus plus warm parser indexes across short idle gaps. It stops the worker when the session is deleted or after 60 seconds without another mapper request.
+The generated `agent-codinglanguage-mapper` agent denies all tools by default and permits only its package-named skill, `codebase_map`, and `code_guidelines`. The plugin maps the active OpenCode directory, serializes Protocol 3 requests through one worker, applies a hard timeout, reports bounded worker `stderr`, restarts after failure, and preserves focus plus warm parser indexes across short idle gaps. It stops the worker when the session is deleted or after 60 seconds without another mapper request.
+
+The installer never reads or changes `opencode.json`; user configuration remains
+user-owned. The deprecated `--write`, `--write-config`, and `--write-agent`
+compatibility flags are accepted, but the Markdown agent is installed by
+default and those flags do not enable configuration writes.
+
+`code_guidelines` exposes four actions: `detect`, `audit`, `patch`, and `apply`. The first three are read-only. `apply` is rejected unless its request contains `write: true`, so the agent must inspect a patch before it can opt into mutation.
+
+The agent's YAML frontmatter contains its restricted permissions; no matching
+JSON agent block is required.
 
 Run it with:
 
 ```bash
 opencode run \
-  --agent mixed-codebase-navigator \
+  --agent agent-codinglanguage-mapper \
   "Find PaymentService, inspect its implementation, and cite the callers. Use only the installed skill and codebase_map."
 ```
 
@@ -256,6 +315,8 @@ A typical investigation should:
 5. Use `trace` only for explicit Protocol 3 relations.
 6. Follow `next_cursor` when evidence is truncated.
 
+A formatting task should first call `code_guidelines` with `detect`, then `audit`, then `patch`. The agent can either improve source-aware findings itself or apply the package plan with `action: apply` and `write: true`. It must finish with another `audit`; it must never use `apply` merely to discover what would change.
+
 ## Large-Workspace Performance
 
 The release benchmark generates one valid file above 100,000 lines for each language and a mixed workspace above 500,000 lines. On the reference Apple Silicon Mac, release budgets are:
@@ -279,7 +340,7 @@ Private Linux CI records and uploads the same measurements with `--report-only`;
 
 ## Offline Ornith/OpenCode Evaluation
 
-The repository contains six release E2Es: Python, Rust, C#, Delphi, C++, and a mixed-language FFI workspace. They use the pinned local Ornith revision through vLLM 0.23.0 and OpenCode 1.17.18. The Python scenario continues the same session through a headless OpenCode server and must inspect the focused symbol in a second turn without another `find` or explicit `target_id`, proving that the plugin preserves its warm worker. It then opens an independent session whose target-less `inspect` must be empty, proving that focus never crosses chat boundaries. The harness fails if a model shard is missing, a download is attempted, an unapproved tool is called, any assistant message uses a different agent, model, or provider, a worker survives server shutdown, or golden file/line evidence is absent.
+The repository contains seven release E2Es: Python, Rust, C#, Delphi, C++, a mixed-language FFI workspace, and a coding-guidelines write workflow. They use the pinned local Ornith revision through vLLM 0.23.0 and OpenCode 1.17.18. The guidelines scenario must detect and audit the profile, inspect a patch, explicitly apply it with `write: true`, and finish with a clean audit. The Python scenario continues the same session through a headless OpenCode server and must inspect the focused symbol in a second turn without another `find` or explicit `target_id`, proving that the plugin preserves its warm worker. It then opens an independent session whose target-less `inspect` must be empty, proving that focus never crosses chat boundaries. The harness fails if a model shard is missing, a download is attempted, an unapproved tool is called, any assistant message uses a different agent, model, or provider, a worker survives server shutdown, or required evidence is absent.
 
 Inspect the plan without launching a model:
 
@@ -293,7 +354,7 @@ Verify the exact local executables, versions, model revision, and weight shards:
 python scripts/run_opencode_e2e.py --verify-runtime
 ```
 
-Run all six scenarios and retain complete evidence:
+Run all seven scenarios and retain complete evidence:
 
 ```bash
 HF_HUB_OFFLINE=1 \

{agent_codinglanguage_mapper-1.0.0 → agent_codinglanguage_mapper-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-codinglanguage-mapper"
-version = "1.0.0"
+version = "1.1.1"
 description = "Agent-focused semantic mapping and language services for mixed-language codebases."
 readme = "README.md"
 requires-python = ">=3.10,<3.15"

{agent_codinglanguage_mapper-1.0.0 → agent_codinglanguage_mapper-1.1.1}/src/agent_codinglanguage_mapper/__init__.py

@@ -1,4 +1,5 @@
 from ._version import __version__
+from .guidelines import CodingGuidelines, GuidelineChange, GuidelineFinding, GuidelineProfile, GuidelineReport
 from .mapper import CodebaseMapper
 from .models import Language, Problem, Project, Reference, Relation, SourceFile, SourceRange, Symbol
 from .protocol import AgentRequest, AgentResponse
@@ -7,6 +8,11 @@ __all__ = [
     "AgentRequest",
     "AgentResponse",
     "CodebaseMapper",
+    "CodingGuidelines",
+    "GuidelineChange",
+    "GuidelineFinding",
+    "GuidelineProfile",
+    "GuidelineReport",
     "Language",
     "Problem",
     "Project",
@@ -17,4 +23,3 @@ __all__ = [
     "Symbol",
     "__version__",
 ]
-

agent_codinglanguage_mapper-1.1.1/src/agent_codinglanguage_mapper/_version.py

@@ -0,0 +1 @@
+__version__ = "1.1.1"

{agent_codinglanguage_mapper-1.0.0 → agent_codinglanguage_mapper-1.1.1}/src/agent_codinglanguage_mapper/cli.py

@@ -5,8 +5,9 @@ import json
 import os
 import sys
 from pathlib import Path
-from typing import Sequence
+from typing import BinaryIO, Sequence, TextIO, cast
 
+from .guidelines import CodingGuidelines, GuidelineReport
 from .integration import install_opencode, install_skill
 from .mapper import CodebaseMapper
 from .models import Language
@@ -59,6 +60,18 @@ def build_parser() -> argparse.ArgumentParser:
     _root_argument(worker)
     worker.add_argument("--project-file", type=Path)
 
+    guidelines = subparsers.add_parser("guidelines", help="Detect, audit, and apply coding guidelines.")
+    guideline_subparsers = guidelines.add_subparsers(dest="guidelines_command", required=True)
+    for name in ("detect", "audit"):
+        command = guideline_subparsers.add_parser(name)
+        _root_argument(command)
+        command.add_argument("--format", choices=("json", "text"), default="text")
+        command.add_argument("--language", dest="languages", action="append", choices=[item.value for item in Language])
+    guideline_format = guideline_subparsers.add_parser("format")
+    _root_argument(guideline_format)
+    guideline_format.add_argument("--language", dest="languages", action="append", choices=[item.value for item in Language])
+    guideline_format.add_argument("--write", action="store_true")
+
     skill = subparsers.add_parser("skill", help="Install agent skills.")
     skill_subparsers = skill.add_subparsers(dest="skill_command", required=True)
     skill_install = skill_subparsers.add_parser("install")
@@ -71,7 +84,14 @@ def build_parser() -> argparse.ArgumentParser:
     opencode_install.add_argument("--target", type=Path, default=Path("."))
     opencode_install.add_argument("--python", default=sys.executable)
     opencode_install.add_argument("--force", action="store_true")
-    opencode_install.add_argument("--write", "--write-config", dest="write_config", action="store_true")
+    opencode_install.add_argument(
+        "--write-agent",
+        "--write",
+        "--write-config",
+        dest="write_config",
+        action="store_true",
+        help="deprecated compatibility flag; the Markdown agent is always installed",
+    )
     return parser
 
 
@@ -85,6 +105,24 @@ def main(argv: Sequence[str] | None = None) -> int:
         return 0
     if args.command == "worker":
         return serve_worker(args.root, sys.stdin, sys.stdout)
+    if args.command == "guidelines":
+        languages = tuple(Language(item) for item in (args.languages or ()))
+        selection: str | tuple[Language, ...] = languages or "auto"
+        guidelines = CodingGuidelines.open(args.root, languages=selection)
+        if args.guidelines_command == "detect":
+            guideline_report = guidelines.detect()
+            _print_guideline_report(guideline_report, args.format)
+            return 0
+        if args.guidelines_command == "audit":
+            guideline_report = guidelines.audit()
+            _print_guideline_report(guideline_report, args.format)
+            return 1 if guideline_report.findings else 0
+        if not args.write:
+            _write_patch(guidelines.patch())
+            return 0
+        guideline_report = guidelines.apply(write=True)
+        print(json.dumps(guideline_report.to_mapping(), indent=2, sort_keys=True))
+        return 0
     if args.command == "skill":
         path = install_skill(args.target, force=args.force)
         print(path)
@@ -112,16 +150,27 @@ def main(argv: Sequence[str] | None = None) -> int:
             path = write_index(mapper, args.out)
             print(json.dumps({"path": str(path), "revision": mapper.snapshot.revision}, sort_keys=True))
             return 0
-        report = _doctor_report(mapper)
+        doctor_report = _doctor_report(mapper)
         if args.format == "json":
-            print(json.dumps(report, indent=2, sort_keys=True))
+            print(json.dumps(doctor_report, indent=2, sort_keys=True))
         else:
-            status = "ready" if report["ok"] else "problems"
+            status = "ready" if doctor_report["ok"] else "problems"
             print(f"status: {status}")
             print("languages: " + ", ".join(item.value for item in Language))
-            print(f"files: {report['files']}")
-            print(f"errors: {report['errors']}")
-        return 0 if report["ok"] else 1
+            print(f"files: {doctor_report['files']}")
+            print(f"errors: {doctor_report['errors']}")
+    return 0 if doctor_report["ok"] else 1
+
+
+def _write_patch(patch: str, stream: TextIO | None = None) -> None:
+    output = stream or sys.stdout
+    binary = getattr(output, "buffer", None)
+    if binary is None:
+        output.write(patch)
+        output.flush()
+        return
+    cast(BinaryIO, binary).write(patch.encode("utf-8"))
+    cast(BinaryIO, binary).flush()
 
 
 def _doctor_report(mapper: CodebaseMapper) -> dict[str, object]:
@@ -136,3 +185,16 @@ def _doctor_report(mapper: CodebaseMapper) -> dict[str, object]:
         "problems": len(mapper.snapshot.problems),
         "errors": len(errors),
     }
+
+
+def _print_guideline_report(report: GuidelineReport, output_format: str) -> None:
+    if output_format == "json":
+        print(json.dumps(report.to_mapping(), indent=2, sort_keys=True))
+        return
+    print(f"workspace: {report.workspace}")
+    print(f"profiles: {len(report.profiles)}")
+    print(f"findings: {len(report.findings)}")
+    for finding in report.findings:
+        line = finding.range.start_line + 1
+        character = finding.range.start_character + 1
+        print(f"{finding.range.path}:{line}:{character}: {finding.severity} {finding.code}: {finding.message}")