cendor-init 0.1.0__tar.gz

cendor_init-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.uv/
+uv.lock
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.coverage
+coverage.json
+htmlcov/
+.smoke/
+.idea/
+.vscode/
+.DS_Store
+*.log
+
+# Local scratch / audit artifacts produced by examples & tests
+audit.jsonl
+*.audit.jsonl
+checkpoints/
+
+# Planning docs — kept local, not tracked
+plan/

cendor_init-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Raghav Mishra (PowerAI Labs)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cendor_init-0.1.0/NOTICE

@@ -0,0 +1,7 @@
+PowerAI Labs
+Copyright 2026 Raghav Mishra (PowerAI Labs)
+
+This product includes software developed by Raghav Mishra (PowerAI Labs).
+
+Licensed under the Apache License, Version 2.0. See the LICENSE file for the
+full terms.

cendor_init-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: cendor-init
+Version: 0.1.0
+Summary: Offline CLI to make your project Cendor-ready and Cendor-fluent for your AI assistant (init) and catch wiring mistakes (doctor). Run with `uvx cendor-init`.
+Project-URL: Homepage, https://cendor.ai/docs/for-ai-assistants
+Project-URL: Repository, https://github.com/cendorhq/cendor-sdk
+Project-URL: Issues, https://github.com/cendorhq/cendor-sdk/issues
+Author: Raghav Mishra (PowerAI Labs)
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai-assistant,cendor,claude-code,cli,copilot,cursor,init,llm,mcp,scaffold
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cendor-init
+
+**One command to make your project Cendor-ready and Cendor-fluent for your AI assistant** — plus a
+`doctor` that catches the wiring mistakes before they bite. Offline: no network, no API key.
+
+```bash
+uvx cendor-init            # detect + write assistant rules files (idempotent)
+uvx cendor-init doctor     # validate the wiring; exit 1 on hard problems (CI-usable)
+```
+
+> Optional developer tooling — dependency-free stdlib. It writes files and inspects your project; it
+> makes **no network call**, and no Cendor library depends on it at runtime. (Node users:
+> `npx @cendor/init`.) This is the Python twin of `@cendor/init`; both share the same behavior.
+
+## What `init` does
+
+1. **Detects your project** — Python (`pyproject.toml` / `requirements`) or Node (`package.json`),
+   which provider SDKs you have, and which `cendor-*` / `@cendor/*` packages are installed.
+2. **Writes the matching assistant rules file(s)** so your assistant reads the correct Cendor
+   call-shapes on every edit. Detected by default; `--all` for every one:
+   - `.github/copilot-instructions.md` (GitHub Copilot)
+   - `.cursor/rules/cendor.mdc` (Cursor)
+   - `AGENTS.md` (the cross-tool default — always written)
+   - a marked section in `CLAUDE.md` (Claude Code)
+   - `.windsurf/rules` (Windsurf)
+
+   **Idempotent and safe:** re-running updates a marker-delimited block in place — never duplicates,
+   never clobbers your surrounding content. A dedicated file it didn't create is left alone unless
+   you pass `--force`.
+3. **Offers MCP setup** (`--mcp`) — drops the connect config for the Cendor MCP server (remote
+   `mcp.cendor.ai` or local `uvx cendor-mcp` / `npx @cendor/mcp`) where it's absent.
+4. **Optional starter** (`--scaffold`) — a minimal, correct `instrument()` + budgeted-call example.
+
+The rules content is a copy of section 3 of the docs source of truth,
+[`for-ai-assistants`](https://cendor.ai/docs/for-ai-assistants).
+
+## What `doctor` checks
+
+Static checks only — it **never mutates** your project, and exits non-zero on hard problems so it
+works in CI:
+
+- **Namespace** — a stray `cendor/__init__.py` in your tree, or a bare `import cendor` (the namespace
+  has no module body — import `from cendor.<tool>`).
+- **Provider deps** — a provider SDK your code imports but hasn't installed/declared (Cendor never
+  pulls one for you; they are optional extras). Uses the installed environment when available.
+- **`instrument()` once** — warns if Cendor is imported but the client is never wrapped.
+- **Money** — flags coercing a price/cost to `float` (it should stay `Decimal`).
+- **Versions** — warns when an installed/pinned `cendor-*` version trails the latest release.
+
+```bash
+uvx cendor-init --help
+```
+
+Apache-2.0 · [cendor.ai](https://cendor.ai) · [For AI assistants](https://cendor.ai/docs/for-ai-assistants) · [MCP](https://cendor.ai/mcp)

cendor_init-0.1.0/README.md

@@ -0,0 +1,54 @@
+# cendor-init
+
+**One command to make your project Cendor-ready and Cendor-fluent for your AI assistant** — plus a
+`doctor` that catches the wiring mistakes before they bite. Offline: no network, no API key.
+
+```bash
+uvx cendor-init            # detect + write assistant rules files (idempotent)
+uvx cendor-init doctor     # validate the wiring; exit 1 on hard problems (CI-usable)
+```
+
+> Optional developer tooling — dependency-free stdlib. It writes files and inspects your project; it
+> makes **no network call**, and no Cendor library depends on it at runtime. (Node users:
+> `npx @cendor/init`.) This is the Python twin of `@cendor/init`; both share the same behavior.
+
+## What `init` does
+
+1. **Detects your project** — Python (`pyproject.toml` / `requirements`) or Node (`package.json`),
+   which provider SDKs you have, and which `cendor-*` / `@cendor/*` packages are installed.
+2. **Writes the matching assistant rules file(s)** so your assistant reads the correct Cendor
+   call-shapes on every edit. Detected by default; `--all` for every one:
+   - `.github/copilot-instructions.md` (GitHub Copilot)
+   - `.cursor/rules/cendor.mdc` (Cursor)
+   - `AGENTS.md` (the cross-tool default — always written)
+   - a marked section in `CLAUDE.md` (Claude Code)
+   - `.windsurf/rules` (Windsurf)
+
+   **Idempotent and safe:** re-running updates a marker-delimited block in place — never duplicates,
+   never clobbers your surrounding content. A dedicated file it didn't create is left alone unless
+   you pass `--force`.
+3. **Offers MCP setup** (`--mcp`) — drops the connect config for the Cendor MCP server (remote
+   `mcp.cendor.ai` or local `uvx cendor-mcp` / `npx @cendor/mcp`) where it's absent.
+4. **Optional starter** (`--scaffold`) — a minimal, correct `instrument()` + budgeted-call example.
+
+The rules content is a copy of section 3 of the docs source of truth,
+[`for-ai-assistants`](https://cendor.ai/docs/for-ai-assistants).
+
+## What `doctor` checks
+
+Static checks only — it **never mutates** your project, and exits non-zero on hard problems so it
+works in CI:
+
+- **Namespace** — a stray `cendor/__init__.py` in your tree, or a bare `import cendor` (the namespace
+  has no module body — import `from cendor.<tool>`).
+- **Provider deps** — a provider SDK your code imports but hasn't installed/declared (Cendor never
+  pulls one for you; they are optional extras). Uses the installed environment when available.
+- **`instrument()` once** — warns if Cendor is imported but the client is never wrapped.
+- **Money** — flags coercing a price/cost to `float` (it should stay `Decimal`).
+- **Versions** — warns when an installed/pinned `cendor-*` version trails the latest release.
+
+```bash
+uvx cendor-init --help
+```
+
+Apache-2.0 · [cendor.ai](https://cendor.ai) · [For AI assistants](https://cendor.ai/docs/for-ai-assistants) · [MCP](https://cendor.ai/mcp)

cendor_init-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cendor-init"
+version = "0.1.0"
+description = "Offline CLI to make your project Cendor-ready and Cendor-fluent for your AI assistant (init) and catch wiring mistakes (doctor). Run with `uvx cendor-init`."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Raghav Mishra (PowerAI Labs)" }]
+keywords = ["cendor", "cli", "init", "scaffold", "ai-assistant", "copilot", "cursor", "claude-code", "mcp", "llm"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Code Generators",
+]
+# Offline + dependency-light by design: stdlib only (argparse, importlib.metadata, pathlib, re, json).
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.10"]
+
+[project.urls]
+Homepage = "https://cendor.ai/docs/for-ai-assistants"
+Repository = "https://github.com/cendorhq/cendor-sdk"
+Issues = "https://github.com/cendorhq/cendor-sdk/issues"
+
+[project.scripts]
+cendor-init = "cendor_init.cli:main"
+
+# This is a SELF-CONTAINED package living inside the cendor-sdk repo (dev tooling, published
+# separately at the launch gate). It ships `cendor_init` — a standalone top-level package, NOT part
+# of the `cendor.*` PEP 420 namespace — so it never collides with cendor-sdk's `cendor/sdk`. It is
+# NOT a uv workspace member: `uv build` it from this directory; the cendor-sdk build/release is
+# untouched (mirrors how cendor-mcp keeps its Python twin standalone).
+[tool.hatch.build.targets.wheel]
+packages = ["src/cendor_init"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+# The rules templates + scaffolds are VERBATIM vendored copy (kept identical to the docs source of
+# truth); their bullet lines legitimately run past 100 cols. This is embedded text, not code width.
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"

cendor_init-0.1.0/src/cendor_init/__init__.py

@@ -0,0 +1,15 @@
+"""cendor-init — offline CLI to wire Cendor + your AI assistant (``init``) and validate the wiring
+(``doctor``). Optional developer tooling; no Cendor library depends on it, and it makes no network
+call. See https://cendor.ai/docs/for-ai-assistants.
+
+This is a standalone top-level package (``cendor_init``) — NOT part of the PEP 420 ``cendor.*``
+namespace — mirroring how ``cendor-mcp`` ships ``cendor_mcp``.
+"""
+
+from __future__ import annotations
+
+from .doctor import run_doctor
+from .initialize import run_init
+
+__all__ = ["run_init", "run_doctor", "__version__"]
+__version__ = "0.1.0"

cendor_init-0.1.0/src/cendor_init/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m cendor_init`` in addition to the ``cendor-init`` console script / ``uvx``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cendor_init-0.1.0/src/cendor_init/cli.py

@@ -0,0 +1,188 @@
+"""``cendor-init`` — one command to make a project Cendor-ready and Cendor-fluent for its AI
+assistant, plus a ``doctor`` that catches wiring mistakes before they bite. Offline: no network, no key.
+
+    uvx cendor-init            # detect + write assistant rules (idempotent)
+    uvx cendor-init doctor     # validate wiring; non-zero exit on hard problems (CI-usable)
+
+See https://cendor.ai/docs/for-ai-assistants and https://cendor.ai/mcp.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import textwrap
+from pathlib import Path
+
+from .doctor import SEVERITY_RANK, Finding, run_doctor
+from .initialize import ALL_ASSISTANTS, InitOptions, run_init
+
+__all__ = ["main"]
+
+_ICON = {
+    "created": "+",
+    "updated": "~",
+    "appended": "~",
+    "skipped": "·",
+    "would-create": "+",
+    "would-update": "~",
+    "would-append": "~",
+    "would-skip": "·",
+}
+
+
+def _version() -> str:
+    try:
+        from importlib import metadata
+
+        return metadata.version("cendor-init")
+    except Exception:
+        return "0.1.0"
+
+
+def _parse_assistants(raw: list[str] | None) -> list[str] | None:
+    if not raw:
+        return None
+    wanted: list[str] = []
+    for item in raw:
+        for part in item.split(","):
+            part = part.strip().lower()
+            if part and part not in wanted:
+                wanted.append(part)
+    bad = [w for w in wanted if w not in ALL_ASSISTANTS]
+    if bad:
+        sys.stderr.write(f"cendor-init: unknown assistant(s): {', '.join(bad)}\n")
+        sys.stderr.write(f"             valid: {', '.join(ALL_ASSISTANTS)}\n")
+        raise SystemExit(2)
+    return wanted
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    root = Path.cwd()
+    opts = InitOptions(
+        root=root,
+        assistants=_parse_assistants(args.assistant),
+        all=args.all,
+        mcp=args.mcp,
+        scaffold=args.scaffold,
+        force=args.force,
+        dry_run=args.dry_run,
+    )
+    result = run_init(opts)
+    dry = opts.dry_run
+    eco = result.detected.ecosystem
+
+    out = sys.stdout.write
+    out(
+        f"\ncendor-init — {'dry run (no files written)' if dry else 'wiring Cendor for your assistant'}\n"
+    )
+    line = "no package.json / pyproject found" if eco == "unknown" else f"{eco} project"
+    if result.detected.declared_providers:
+        line += f"  ·  providers: {', '.join(sorted(result.detected.declared_providers))}"
+    out(f"project: {line}\n\n")
+
+    for a in result.actions:
+        icon = _ICON.get(a.status, "·")
+        note = f"  ({a.note})" if a.note else ""
+        out(f"  {icon} {a.status:<13} {a.path}{note}\n")
+
+    out("\nMCP (agent-mode assistants):\n")
+    for ln in result.mcp_guidance.split("\n"):
+        out(f"  {ln}\n")
+
+    out("\nNext:\n")
+    out("  • Trust your editor's hover/completion — every Cendor symbol ships an @example.\n")
+    out("  • Full trap sheet:  https://cendor.ai/docs/for-ai-assistants\n")
+    out("  • Validate wiring:  uvx cendor-init doctor\n\n")
+    return 0
+
+
+def _print_finding(f: Finding) -> None:
+    tag = {"error": "ERROR", "warn": "WARN ", "ok": "OK   "}.get(f.severity, "INFO ")
+    out = sys.stdout.write
+    out(f"  [{tag}] {f.title}\n")
+    for ln in textwrap.wrap(f.detail, width=88):
+        out(f"          {ln}\n")
+    if f.fix:
+        out(f"          fix: {f.fix}\n")
+    for loc in f.locations:
+        out(f"          - {loc}\n")
+    out("\n")
+
+
+def _cmd_doctor(_args: argparse.Namespace) -> int:
+    result = run_doctor(Path.cwd())
+    sys.stdout.write("\ncendor-init doctor\n\n")
+    for f in sorted(result.findings, key=lambda x: SEVERITY_RANK.get(x.severity, 9)):
+        _print_finding(f)
+    errors = sum(1 for f in result.findings if f.severity == "error")
+    warns = sum(1 for f in result.findings if f.severity == "warn")
+    tail = "OK." if result.exit_code == 0 else "Fix the errors above."
+    sys.stdout.write(f"{errors} error(s), {warns} warning(s). {tail}\n\n")
+    return result.exit_code
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cendor-init",
+        description="Wire Cendor + your AI assistant, offline.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Docs: https://cendor.ai/docs/for-ai-assistants   MCP: https://cendor.ai/mcp",
+    )
+    parser.add_argument("-v", "--version", action="version", version=_version())
+    sub = parser.add_subparsers(dest="command")
+
+    p_init = sub.add_parser("init", help="write assistant rules files (default command)")
+    _add_init_args(p_init)
+    sub.add_parser("doctor", help="validate the wiring (never writes); exit 1 on hard problems")
+    return parser
+
+
+def _add_init_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--all", action="store_true", help="write every assistant rules file")
+    p.add_argument(
+        "--assistant",
+        action="append",
+        metavar="LIST",
+        help="comma-separated subset: copilot,cursor,agents,claude,windsurf",
+    )
+    p.add_argument("--mcp", action="store_true", help="also drop MCP connect config where absent")
+    p.add_argument(
+        "--scaffold", action="store_true", help="also write a correct instrument()+budget starter"
+    )
+    p.add_argument(
+        "--force", action="store_true", help="overwrite an owned file (.cursor/rules/cendor.mdc)"
+    )
+    p.add_argument("--dry-run", action="store_true", help="show what would change without writing")
+    p.add_argument("-y", "--yes", action="store_true", help=argparse.SUPPRESS)
+
+
+def _force_utf8() -> None:
+    """Our output uses em-dashes / bullets. A Windows console defaults to a non-UTF-8 code page,
+    which would raise UnicodeEncodeError on those — force UTF-8 (with a replace fallback)."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8", errors="replace")
+            except (ValueError, OSError):  # pragma: no cover - stream doesn't support it
+                pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    _force_utf8()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # Default to `init` when no subcommand is given (mirrors `npx @cendor/init`).
+    if not argv or (argv[0].startswith("-") and argv[0] not in ("-h", "--help", "-v", "--version")):
+        argv = ["init", *argv]
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    command = args.command or "init"
+    if command == "doctor":
+        return _cmd_doctor(args)
+    return _cmd_init(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())