export interface CommandHelp { name: string; usage: string; question: string; purpose: string; useWhen: readonly string[]; doNotUseFor: readonly string[]; examples: readonly string[]; interpretation: readonly string[]; exitBehavior?: readonly string[]; nextSteps: readonly string[]; options: readonly CommandOptionHelp[]; } type CommandOptionHelp = CliOptionName | { name: CliOptionName; description?: string; }; declare const OPTION_HELP: { readonly config: { readonly flags: "-c, --config "; readonly description: "Read a repository-contained, non-symlink Renma .json or .jsonc config file."; }; readonly "fail-on": { readonly flags: "--fail-on "; readonly description: "Exit 1 when scan findings meet severity: low, medium, high, or critical."; }; readonly strict: { readonly flags: "--strict"; readonly description: "Fail on threshold findings, invalid Agent Skills, error diagnostics, blocking inspection-coverage issues, or incomplete applicable security analysis."; }; readonly entrypoint: { readonly flags: "--entrypoint "; readonly description: "Select one exact Skill ID or repository-relative SKILL.md path."; }; readonly focus: { readonly flags: "--focus "; readonly description: "Focus one asset by stable ID or path; required by composition and impact, and optional for discovery, executable, and skill-index."; }; readonly format: { readonly flags: "--format "; readonly description: "Output format for commands that accept --format."; }; readonly from: { readonly flags: "--from "; readonly description: "Git ref to use as the comparison baseline."; }; readonly base: { readonly flags: "--base "; readonly description: "Alias for --from; comparison baseline."; }; readonly "fail-on-status": { readonly flags: "--fail-on-status "; readonly description: "CI-report execution threshold: fail (default) or warn."; }; readonly help: { readonly flags: "-h, --help"; readonly description: "Show this help page without running the command."; }; readonly handoff: { readonly flags: "--handoff "; readonly description: "Read a caller-declared Skill authoring handoff, validate its structure, and apply its structural values. This is not proof of human review or domain truth."; }; readonly "include-owned": { readonly flags: "--include-owned"; readonly description: "Include flat owned asset details in ownership output."; }; readonly id: { readonly flags: "--id "; readonly description: "Set the scaffolded asset ID instead of deriving one."; }; readonly json: { readonly flags: "--json"; readonly description: "Shortcut for --format json where JSON is supported."; }; readonly lines: { readonly flags: "--lines "; readonly description: "Print an exact line range such as L10-L42 or 10-42."; }; readonly "max-context-bytes": { readonly flags: "--max-context-bytes "; readonly description: "Limit nearby context bytes for semantic split suggestions."; }; readonly "max-source-bytes": { readonly flags: "--max-source-bytes "; readonly description: "Limit source file bytes for semantic split suggestions."; }; readonly "omit-generated-at": { readonly flags: "--omit-generated-at"; readonly description: "Omit the BOM run-time generatedAt timestamp."; }; readonly "source-revision": { readonly flags: "--source-revision "; readonly description: "Record caller-provided revision provenance without Git verification."; }; readonly owner: { readonly flags: "--owner "; readonly description: "Owner value for commands that accept --owner."; }; readonly resources: { readonly flags: "--resources "; readonly description: "Create selected Skill-local directories: references,scripts,assets."; }; readonly tags: { readonly flags: "--tags "; readonly description: "Set comma-separated or repeated scaffold tags."; }; readonly title: { readonly flags: "--title "; readonly description: "Set scaffold title metadata."; }; readonly to: { readonly flags: "--to <ref>"; readonly description: "Comparison target. Defaults to HEAD for diff and ci-report."; }; readonly version: { readonly flags: "-v, --version"; readonly description: "Print the Renma package version."; }; readonly view: { readonly flags: "--view <view>"; readonly description: "Graph view: summary, workflow, full, layered, lens, composition, impact, discovery, or executable."; }; }; export type CliOptionName = keyof typeof OPTION_HELP; export declare const COMMAND_HELP: readonly [{ readonly name: "init"; readonly usage: "renma init [root]"; readonly question: "How can this repository record explicit Renma adoption?"; readonly purpose: "Init initializes repository-level Renma configuration. It does not create Skills or Context Assets. Init the repository; scaffold an asset."; readonly useWhen: readonly ["A repository wants to record explicit Renma adoption and pin its initial repository policy.", "You want a concise renma.config.jsonc with the initial fail-on severity, output format, and room for human-readable policy rationale."]; readonly doNotUseFor: readonly ["Creating a Skill, Context Asset, Context Lens, example asset, or asset directory.", "Replacing guide or scaffold in the Skill authoring sequence.", "Rewriting, normalizing, migrating, or validating an existing configuration file.", "Running scan, catalog, graph, readiness, or any interactive workflow."]; readonly examples: readonly ["renma init", "renma init .", "renma init path/to/repository"]; readonly interpretation: readonly ["When no conventional Renma configuration exists, init creates a concise renma.config.jsonc and prints next steps.", "An existing renma.config.jsonc or renma.config.json is never modified, even when it is empty, malformed, or customized. A legacy .renma.json produces a rename error instead of being ignored.", "When multiple conventional files exist, init reports the ambiguity and changes none of them.", "Repositories can use Renma defaults without running init; initialization records explicit repository policy."]; readonly nextSteps: readonly ["For an existing repository, run renma scan . and renma catalog . --format markdown.", "To create a new Skill, use renma guide skill, clarify only if needed, establish the smallest intended asset graph as a creation-gate requirement, declare the gate passed only after every requirement is established and no Blocking decision remains, run renma scaffold skill once, then complete and validate the asset."]; readonly options: readonly ["help"]; }, { readonly name: "scan"; readonly usage: "renma scan [path] [options]"; readonly question: "What concrete problems should be fixed?"; readonly purpose: "Scan is usually the first command when improving existing skills or context assets. It reports concrete findings and deterministic diagnostics without editing files."; readonly useWhen: readonly ["You need the first actionable view of repository problems.", "You are preparing or verifying a patch for skills, contexts, prompts, or agent-facing docs.", "A downstream tool or coding agent needs JSON guidance, repair constraints, and verification steps."]; readonly doNotUseFor: readonly ["Automatically rewriting files or applying fixes.", "An agent inventing owners, references, source-of-truth documents, or product rules.", "Selecting runtime context for an LLM or assembling task prompts."]; readonly examples: readonly ["renma scan .", "renma scan . --format json", "renma scan . --fail-on high", "renma scan . --fail-on high --strict"]; readonly interpretation: readonly ["Text output is a human-readable finding list.", "JSON output includes structured diagnostics, review bundles, and guidance intended for downstream tools and coding agents.", "Agent Skills migration commands use structured command and args fields in JSON; text display paths use POSIX shell quoting when needed.", "When repair constraints or verification steps are present, follow them instead of broadening the edit.", "Without --strict, scan exits according to the active finding threshold. Strict mode additionally rejects invalid Agent Skills, error diagnostics, blocking inspection-coverage issues, and applicable YAML frontmatter-comment analysis that could not be completed safely.", "Strict mode does not generally make warnings, suppressed findings, or other unsupported or non-analyzable security-analysis states fatal.", "Inspection coverage reports whether expected first-class agent-facing paths were actually inspected. Renma does not follow symlinks."]; readonly exitBehavior: readonly ["0: No finding reaches the active threshold; in strict mode, strict evaluation passes.", "1: The active finding threshold is reached, or strict evaluation fails.", "A valid scan report is still emitted to stdout on exit 1.", "Exit 2 and 3 follow the global CLI contract; run renma --help for caller-correctable and unexpected failure handling."]; readonly nextSteps: readonly ["Inspect evidence before editing.", "Use suggest-metadata only when metadata retrofit or Skill migration work is needed.", "Prepare a minimal reviewable patch that preserves supported semantics.", "Rerun scan with --fail-on high and any relevant structural commands after editing."]; readonly options: readonly ["config", "fail-on", "strict", { readonly name: "format"; readonly description: "Output format: text or json. Defaults to text."; }, "json", "help"]; }, { readonly name: "catalog"; readonly usage: "renma catalog [path] [options]"; readonly question: "What assets and metadata exist?"; readonly purpose: "Catalog inventories discovered assets and normalized metadata so reviewers can see the repository evidence Renma found."; readonly useWhen: readonly ["You need IDs, kinds, owners, lifecycle states, hashes, tags, declared dependencies, or context relationships.", "You want inventory evidence before changing metadata or references.", "You need stable JSON or Markdown asset inventory for review."]; readonly doNotUseFor: readonly ["Treating inventory as a problem list by itself.", "Deciding what context an agent should consume at runtime.", "Proving that a declared dependency is semantically correct."]; readonly examples: readonly ["renma catalog . --format markdown", "renma catalog . --format json"]; readonly interpretation: readonly ["Catalog output is deterministic inventory evidence.", "Missing, duplicate, or unresolved metadata may appear as diagnostics, but catalog is not a substitute for scan.", "Dependencies are declared relationships discovered from repository metadata and references."]; readonly exitBehavior: readonly ["0: The catalog report contains no error diagnostics.", "1: The generated catalog report contains an error diagnostic; the valid report is still emitted to stdout.", "Exit 2 and 3 follow the global CLI contract; run renma --help for caller-correctable and unexpected failure handling."]; readonly nextSteps: readonly ["Run graph to inspect relationships.", "Run readiness for repository-level summary.", "Run scan for concrete findings to fix."]; readonly options: readonly ["config", { readonly name: "format"; readonly description: "Output format: json or markdown. Defaults to json."; }, "json", "help"]; }, { readonly name: "graph"; readonly usage: "renma graph [path] [options]"; readonly question: "How are assets and executables connected?"; readonly purpose: "Graph shows declared structural relationships between assets and an explicit executable relationship projection, including focused views around one node."; readonly useWhen: readonly ["You need to inspect dependencies, references, unresolved targets, or isolation.", "You want a one-hop neighborhood with --focus for one asset ID or path.", "You want to inspect which scripts a Skill invokes or which Skills use a script.", "You need Markdown, JSON, or Mermaid evidence for review."]; readonly doNotUseFor: readonly ["It does not select context for an LLM.", "It does not prove that a dependency is semantically correct.", "Deleting isolated assets without human review."]; readonly examples: readonly ["renma graph . --format markdown", "renma graph . --view layered --format mermaid", "renma graph . --view discovery --format markdown", "renma graph . --focus contexts/testing/boundary-value-analysis.md --view full", "renma graph . --focus skill.testing.spec-review --view composition --format json", "renma graph . --focus context.shared-api --view impact --format markdown", "renma graph . --view executable --focus skill.release-prep --format markdown", "renma graph . --view executable --focus tools/check-changelog.sh --format markdown"]; readonly interpretation: readonly ["Edges represent declared relationships Renma can resolve or report as unresolved.", "Unexpected isolation is evidence to review, not automatic permission to delete an asset.", "Focused output filters to the matched asset and directly connected neighbors.", "The composition view resolves the complete explicit required and optional closure and requires --focus.", "The impact view resolves reverse explicit composition to required and optional declared dependents; it reports neither runtime usage nor breakage and requires --focus.", "The discovery view derives cycle-safe reachability from explicit published entrypoints through usable declared continuations, with descriptive partial coverage and authoritative adopted coverage; optional focus keeps repository-wide adoption and coverage while filtering visible arrays and summary counts to one Skill's direct neighborhood.", "The executable view shows canonical Skill/script invocation and script dependency edges separately from deterministic Skill-local structural containment; optional focus supports either a Skill ID/path or executable path."]; readonly exitBehavior: readonly ["0: The graph report contains no error diagnostics.", "1: The generated graph report contains an error diagnostic; the valid report is still emitted to stdout.", "Exit 2 and 3 follow the global CLI contract; run renma --help for caller-correctable and unexpected failure handling."]; readonly nextSteps: readonly ["Use catalog to inspect the assets behind graph nodes.", "Use scan to fix concrete relationship findings.", "Rerun graph after metadata or reference changes."]; readonly options: readonly ["config", { readonly name: "format"; readonly description: "Output format: json, markdown, or mermaid. Defaults to json. JSON defaults to the full view; non-JSON formats default to the summary view."; }, "json", "view", "focus", "help"]; }, { readonly name: "execution-contract"; readonly usage: "renma execution-contract [repository] --entrypoint <skill-id-or-SKILL.md-path> [options]"; readonly question: "What executable relationships are statically possible from one Skill?"; readonly purpose: "Execution contract emits an experimental portable JSON artifact containing the canonical executable closure and exact bounded static evidence for one Skill."; readonly useWhen: readonly ["An external runtime tracer or correlator needs deterministic repository evidence to bind to later.", "You need direct and transitive repository-script relationships from one exact Skill entrypoint.", "You need unresolved evidence, lifecycle state, content hashes, a Renma-calculated selected-evidence digest, and bounded-analysis facts without runtime observation."]; readonly doNotUseFor: readonly ["Proving that a relationship executed or must execute.", "Authorizing a suspended or revoked Skill, or any command execution.", "Importing observations, verifying conformance, or asking Renma to inspect Git revision state."]; readonly examples: readonly ["renma execution-contract . --entrypoint skill.release-prep --format json", "renma execution-contract . --entrypoint skills/release-prep/SKILL.md --source-revision <git-sha> --format json"]; readonly interpretation: readonly ["The experimental schema is renma.experimental-execution-contract.v1 and carries no long-term compatibility promise.", "Every invokes relationship has expectation possible; containment remains separate structural placement.", "The command collects one repository snapshot and derives every field from that snapshot.", "The always-present evidence digest binds the selected deterministic evidence projection without inspecting Git or checkout-root state.", "A caller-supplied source revision is recorded verbatim and marked unverified by Renma.", "Zero unresolved rows does not prove complete runtime behavior because the static analyzers are intentionally bounded."]; readonly exitBehavior: readonly ["0: The execution-contract report contains no error diagnostics.", "1: The generated execution-contract report contains an error diagnostic; the valid report is still emitted to stdout.", "Exit 2 and 3 follow the global CLI contract; run renma --help for caller-correctable and unexpected failure handling."]; readonly nextSteps: readonly ["Use the embedded evidence digest for selected-evidence identity and bind the exact serialized JSON externally with SHA-256 when a correlator needs artifact identity.", "Use a caller-created detached worktree when generating historical evidence.", "Treat runtime observation import and conformance verification as later phases."]; readonly options: readonly ["config", "entrypoint", "source-revision", { readonly name: "format"; readonly description: "Output format: json. Defaults to json."; }, "json", "help"]; }, { readonly name: "skill-index"; readonly usage: "renma skill-index [path] [options]"; readonly question: "Where can static Skill Discovery begin and continue?"; readonly purpose: "Skill index emits a compact static view of visible Skills, explicit published entrypoints, declared continuations, reachability, coverage, structural candidates, and exact repository evidence."; readonly useWhen: readonly ["A human or agent needs to find the repository's explicit Skill Discovery starting points.", "You need canonical renma.skill-index.v1 JSON for automation or compact Markdown for review.", "You want one exact Skill's direct declared neighborhood without changing repository-wide coverage facts."]; readonly doNotUseFor: readonly ["Interpreting task text, recommending or ranking the best Skill, or fuzzy search.", "Loading Context, assembling a prompt, invoking a Skill, or executing a workflow.", "Inferring undeclared routes, creating metadata, or writing a generated index file."]; readonly examples: readonly ["renma skill-index .", "renma skill-index . --format json", "renma skill-index . --json", "renma skill-index . --focus skill.release-prep --format markdown"]; readonly interpretation: readonly ["Markdown is the default; JSON uses the canonical renma.skill-index.v1 schema.", "Coverage is repository-scoped. Summary counts and visible ID arrays are projection-scoped when --focus is present.", "Focus accepts only one exact effective Skill ID or repository-relative SKILL.md path and retains direct incoming and outgoing declarations.", "Repository diagnostics and Discovery diagnostics remain separate.", "The command reads one shared repository snapshot and writes only to stdout."]; readonly exitBehavior: readonly ["0: Repository and Discovery diagnostics are warning-only or clear.", "1: An error exists in either diagnostic collection; the valid Skill Index report is still emitted to stdout.", "Exit 2 and 3 follow the global CLI contract; run renma --help for caller-correctable and unexpected failure handling."]; readonly nextSteps: readonly ["Open the referenced source SKILL.md and apply its description and routing conditions to the current request.", "Follow only a declared continuation whose source Skill conditions support it.", "Use graph --view discovery when a graph-shaped JSON, Markdown, or Mermaid projection is needed."]; readonly options: readonly ["config", { readonly name: "format"; readonly description: "Output format: markdown or json. Defaults to markdown."; }, "json", "focus", "help"]; }, { readonly name: "trust-graph"; readonly usage: "renma trust-graph [path] [options]"; readonly question: "What trust-relevant evidence is connected to each asset?"; readonly purpose: "Trust graph connects deterministic evidence such as ownership, lifecycle, policy, references, dependencies, and diagnostics."; readonly useWhen: readonly ["A reviewer or downstream tool needs traceable trust-relevant evidence per asset.", "You need to connect owners, lifecycle status, effective policy fingerprints, dependencies, and diagnostics.", "You want a stable evidence layer for human review."]; readonly doNotUseFor: readonly ["It is not a subjective trust score.", "It does not certify that an asset is trustworthy.", "Runtime policy enforcement, prompt assembly, or telemetry."]; readonly examples: readonly ["renma trust-graph . --format markdown", "renma trust-graph . --format json"]; readonly interpretation: readonly ["Trust Graph v2 is the only supported contract; there is no v1 compatibility mode.", "The report connects evidence; it does not decide trust for you.", "Missing owner, lifecycle, policy, or diagnostic evidence should be reviewed in context.", "JSON is the source of truth for downstream tooling; Markdown is for human review."]; readonly nextSteps: readonly ["Use scan for concrete diagnostics.", "Use ownership when owner coverage needs deeper review.", "Use readiness for repository-level summary."]; readonly options: readonly ["config", { readonly name: "format"; readonly description: "Output format: json or markdown. Defaults to json."; }, "json", "help"]; }, { readonly name: "readiness"; readonly usage: "renma readiness [path] [options]"; readonly question: "Is the repository broadly prepared for agent-facing use?"; readonly purpose: "Readiness provides a repository-level scorecard and health summary derived from deterministic repository evidence."; readonly useWhen: readonly ["You need a broad maintainer or CI summary after scan, catalog, or graph review.", "You want repository-level checks for ownership, graph resolution, lifecycle, context lens governance, and selected findings.", "You need Markdown for review or JSON for automation."]; readonly doNotUseFor: readonly ["Replacing scan when you need concrete findings.", "Deciding whether an agent should consume a particular context asset at runtime.", "Claiming what an LLM actually used."]; readonly examples: readonly ["renma readiness . --format markdown", "renma readiness . --format json"]; readonly interpretation: readonly ["Scan gives concrete findings; readiness gives a broad repository summary.", "Readiness scores and checks are static repository review signals.", "Security posture and context lens summaries remain deterministic evidence, not runtime decisions."]; readonly exitBehavior: readonly ["0: Readiness level is ready, including Ready with advisories.", "1: Readiness level is needs_attention or not_ready.", "The readiness report is still emitted to stdout on exit 1.", "Exit 2 and 3 follow the global CLI contract; run renma --help for caller-correctable and unexpected failure handling."]; readonly nextSteps: readonly ["Use scan to fix specific findings behind readiness failures.", "Use catalog and graph to inspect inventory or relationship causes.", "Rerun readiness after the patch."]; readonly options: readonly ["config", { readonly name: "format"; readonly description: "Output format: json or markdown. Defaults to json."; }, "json", "help"]; }, { readonly name: "bom"; readonly usage: "renma bom [path] [options]"; readonly question: "What declared repository context manifest should be reviewed?"; readonly purpose: "BOM prints a declared repository evidence snapshot combining catalog, graph, lifecycle, hashes, diagnostics, readiness, and security posture evidence."; readonly useWhen: readonly ["Reviewers or CI consumers need one manifest of declared repository context evidence.", "You need a PR artifact that combines inventory, dependencies, diagnostics, readiness, lifecycle, hashes, and security posture.", "You need structured JSON generated from deterministic repository evidence or compact Markdown for review."]; readonly doNotUseFor: readonly ["Reporting what an LLM actually consumed.", "It is not telemetry, prompt assembly, runtime context selection, or agent execution.", "Normalizing every repository or environment-dependent metadata value."]; readonly examples: readonly ["renma bom . --format json", "renma bom . --format markdown", "renma bom . --format json --omit-generated-at"]; readonly interpretation: readonly ["Repository Context BOM v3 is the current contract; v2 consumers must migrate the embedded Readiness check collection.", "The BOM is a declared repository manifest, not a runtime usage report or telemetry.", "--omit-generated-at only removes the run-time generation timestamp.", "With the same checkout path, config path, repository contents, Renma version, and UTC evaluation date, repeated --omit-generated-at JSON runs should be byte-identical.", "The option does not remove freshness metadata, suppress freshness diagnostics, normalize absolute root or configPath values, hide file moves, or make output portable across runners."]; readonly exitBehavior: readonly ["0: The BOM report contains no error diagnostics.", "1: The generated BOM report contains an error diagnostic; the valid report is still emitted to stdout.", "Exit 2 and 3 follow the global CLI contract; run renma --help for caller-correctable and unexpected failure handling."]; readonly nextSteps: readonly ["Review diagnostics and readiness sections before merging.", "Use scan, catalog, or graph for focused follow-up.", "Store JSON when automation needs the source of truth."]; readonly options: readonly ["config", { readonly name: "format"; readonly description: "Output format: json or markdown. Defaults to json."; }, "json", "omit-generated-at", "help"]; }, { readonly name: "ownership"; readonly usage: "renma ownership [path] [options]"; readonly question: "Where is ownership missing or concentrated?"; readonly purpose: "Ownership helps review owner coverage, unowned assets, and concentration by declared owner."; readonly useWhen: readonly ["You need to find assets without owner metadata.", "You want to review what one owner is responsible for.", "You need ownership coverage evidence for governance review."]; readonly doNotUseFor: readonly ["Renma should not invent or assign an owner from paths, prose, Git history, or guesses.", "Replacing human or source-of-truth confirmation for missing ownership.", "Treating unowned assets as automatic failures in every repository."]; readonly examples: readonly ["renma ownership . --format markdown", "renma ownership . --include-owned", "renma ownership . --owner qa-platform --format json"]; readonly interpretation: readonly ["Ownership output reports declared owner metadata and coverage.", "Missing ownership normally requires confirmation from a human or an existing source of truth.", "Owner filters keep repository-level totals while adding owner-specific details."]; readonly exitBehavior: readonly ["0: The ownership report contains no error diagnostics.", "1: The generated ownership report contains an error diagnostic; the valid report is still emitted to stdout.", "Exit 2 and 3 follow the global CLI contract; run renma --help for caller-correctable and unexpected failure handling."]; readonly nextSteps: readonly ["Confirm missing owners before editing metadata.", "Use suggest-metadata when preparing a metadata-only retrofit.", "Rerun ownership and scan after ownership changes."]; readonly options: readonly ["config", { readonly name: "format"; readonly description: "Output format: json or markdown. Defaults to json."; }, "json", "include-owned", { readonly name: "owner"; readonly description: "Show owner-specific declared asset details while preserving repository-level coverage totals."; }, "help"]; }, { readonly name: "diff"; readonly usage: "renma diff [path] (--from <ref> | --base <ref>) [--to <ref>] [options]"; readonly question: "What deterministic repository evidence changed between refs?"; readonly purpose: "Diff compares deterministic repository evidence between Git refs for context and skill review."; readonly useWhen: readonly ["You need to review readiness, asset, graph, check, or finding changes before merging.", "A pull request changes skills, contexts, metadata, or agent-facing docs.", "You want JSON or Markdown evidence over repository governance changes."]; readonly doNotUseFor: readonly ["A generic source-code diff.", "Determining what an LLM consumed at runtime.", "Replacing human review of semantic changes."]; readonly examples: readonly ["renma diff . --base origin/main", "renma diff . --from main --to HEAD", "renma diff . --from origin/main --to HEAD --format markdown"]; readonly interpretation: readonly ["The report compares Renma evidence generated at two refs.", "Supply one comparison baseline with --from or its --base alias; using both is an error. --to defaults to the Git ref HEAD.", "Added or removed findings show deterministic review signal changes, not arbitrary source hunks."]; readonly exitBehavior: readonly ["0: The requested comparison was generated successfully, regardless of whether the report contains changes or regressions.", "Diff does not use exit 1 merely because evidence changed.", "Exit 2 and 3 follow the global CLI contract; run renma --help for caller-correctable and unexpected failure handling."]; readonly nextSteps: readonly ["Use ci-report when a PR-oriented summary is needed.", "Use scan or graph on the working tree to investigate changed evidence.", "Summarize changed evidence and remaining uncertainty for reviewers."]; readonly options: readonly ["config", "from", "base", "to", { readonly name: "format"; readonly description: "Output format: json or markdown. Defaults to json."; }, "json", "help"]; }, { readonly name: "ci-report"; readonly usage: "renma ci-report [path] (--from <ref> | --base <ref>) [--to <ref>] [options]"; readonly question: "What should a CI or PR reviewer inspect?"; readonly purpose: "CI report produces a pull-request-oriented summary from deterministic Renma evidence."; readonly useWhen: readonly ["CI needs a PASS, WARN, or FAIL status with review-focused details.", "A PR reviewer needs readiness, graph, finding, and declared Skill Discovery changes summarized.", "You want Markdown for a PR comment or JSON for automation."]; readonly doNotUseFor: readonly ["Replacing human review.", "A full generic code diff.", "Certifying that all semantic changes are correct."]; readonly examples: readonly ["renma ci-report . --base origin/main", "renma ci-report . --from main --to HEAD --format markdown", "renma ci-report . --from origin/main --to HEAD --format json", "renma ci-report . --from origin/main --to HEAD --fail-on-status warn"]; readonly interpretation: readonly ["The report combines deterministic evidence for review.", "Supply one comparison baseline with --from or its --base alias; using both is an error. --to defaults to the Git ref HEAD.", "Skill Discovery changes are observation-only and do not affect CI status or exits.", "The failure threshold changes execution policy, not report status, and is never read from repository configuration.", "Reviewers should still inspect meaningful semantic changes."]; readonly exitBehavior: readonly ["With the default --fail-on-status fail, PASS and WARN exit 0; FAIL exits 1.", "With --fail-on-status warn, PASS exits 0; WARN and FAIL exit 1.", "A valid CI report is still emitted to stdout on exit 1.", "Exit 2 and 3 follow the global CLI contract; run renma --help for caller-correctable and unexpected failure handling."]; readonly nextSteps: readonly ["Fix or explain new failures and warnings.", "Use diff for the underlying evidence comparison.", "Rerun ci-report after updating the branch."]; readonly options: readonly ["config", "from", "base", "to", "fail-on-status", { readonly name: "format"; readonly description: "Output format: json or markdown. Defaults to markdown."; }, "json", "help"]; }, { readonly name: "inspect"; readonly usage: "renma inspect <file> [options]"; readonly question: "What is the outline or exact line slice of one file?"; readonly purpose: "Inspect provides deterministic classification plus a compact outline or exact line slice of a single file."; readonly useWhen: readonly ["You need to inspect one asset before editing without reading the whole repository.", "A coding agent needs a deterministic outline or exact line range.", "You want Context Lens or relationship hints for one file when repository context can be inferred."]; readonly doNotUseFor: readonly ["Selecting runtime context for an LLM.", "Assembling prompts for task execution.", "Replacing scan, catalog, or graph for repository-wide evidence."]; readonly examples: readonly ["renma inspect skills/testing/spec-review/SKILL.md", "renma inspect skills/testing/spec-review/SKILL.md --lines L10-L42", "renma inspect contexts/testing/boundary-value-analysis.md --format json"]; readonly interpretation: readonly ["Without --lines, output includes classification even when the file is not a catalog entry; governance remains a separate evidence section.", "With --lines, output is an exact source slice.", "Inspect is an inspection helper, not a runtime context selector or prompt assembler."]; readonly nextSteps: readonly ["Use scan for concrete findings before or after edits.", "Use catalog or graph if one-file inspection reveals relationship questions.", "Cite exact lines when summarizing edits for review."]; readonly options: readonly [{ readonly name: "format"; readonly description: "Output format: text or json. Defaults to json."; }, "json", "lines", "help"]; }, { readonly name: "guide"; readonly usage: "renma guide <topic> [options]"; readonly question: "What is the smallest justified asset graph for a new Skill?"; readonly purpose: "Guide prints a deterministic, non-editing authoring contract that tells a consuming LLM to evaluate the creation gate and clarify unresolved Blocking human truth only when needed before generation or an intentional asset-boundary redesign. Skill is the only supported topic."; readonly useWhen: readonly ["You are about to create a Skill or ask a coding agent to create one.", "You need to establish an authoring contract from a brief request without requiring an upfront plan-quality specification.", "You are intentionally reconsidering Skill or Context boundaries, file or resource placement, source representation, scripts or other support, or the asset graph.", "You need Renma asset, metadata, responsibility, and conciseness boundaries before scaffolding.", "An external authoritative source may justify a separate Context Asset even when no other Skill reuses it yet."]; readonly doNotUseFor: readonly ["Conducting the conversation, asking the user questions directly, retaining session state, accepting a natural-language task, calling an LLM, or designing the Skill automatically.", "Creating or editing files, fetching URLs, or inspecting a repository.", "Inferring owners, policies, dependencies, domain facts, or runtime Context selection.", "Claiming scan creates Context Assets or proves semantic correctness and source authority."]; readonly examples: readonly ["renma guide skill", "renma guide skill --format prompt", "renma guide skill --format json", "renma guide skill --json"]; readonly interpretation: readonly ["Prompt is the compact default execution contract; JSON is the complete deterministic structured reference, and both derive from the same guidance data.", "Guide JSON uses renma.skill-authoring-guide.v2. Consumers must branch on schemaVersion and must not apply v1 phase-order, mandatory-clarification, fixed-batch, or last-phase human-review assumptions to v2.", "The default prompt tells the consuming LLM to inspect applicable user-provided artifacts, repository evidence, and permitted authoritative source content; separate Confirmed, Proposed, and Unresolved support from Blocking, Reversible default, and Deferred progression; evaluate the creation gate; and ask only about unresolved Blocking authoring decisions that still require human truth.", "Clarification is not required when the request and applicable evidence establish every gate requirement. Small focused question batches are an adaptive default rather than a fixed correctness rule; retain blockers without requiring their complete presentation in every response.", "The creation gate may be declared passed only after every gate requirement is established, including the smallest justified asset structure, and no Blocking authoring decision remains. This is an observable dependency, not a prescribed internal reasoning sequence.", "Do not ask a downstream authoring decision when its meaningful answer depends on an unresolved upstream decision; investigate or resolve the prerequisite first without persisting a decision graph, frontier, rounds, or conversation state.", "Classify unknown scope before progression: authoring decisions may block the gate, while runtime task unknowns should be detected, reported with evidence and impact, or treated as runtime-stage blockers under the Skill's authored ask, report, defer, or stop policy when the next execution stage depends on them. A task-instance fact does not enter the authoring blocker set; re-enter clarification only when its handling policy or asset boundary is unresolved.", "Decision themes and disposition summaries are optional working aids. Preserve evidence and the distinction between blocking decisions, reversible defaults, deferred decisions, and runtime findings without requiring a particular reasoning sequence or progress format.", "Output is deterministic for the installed Renma version and is written only to stdout.", "The command works without an existing repository and performs no filesystem or network operations.", "The guide establishes Renma boundaries; platform-native Skill authoring guidance may refine semantics only after the creation gate passes and within the agreed structure.", "A user-designated URL confirms intended authority, not source-content facts; authoring-time consultation depends on the current request, tools, and environment, while finished-Skill runtime access requires an evidence-backed effective security-policy decision.", "If the finished Skill may recursively follow references discovered inside an external source, the prompt directs the consumer to consult and apply externalTraversalRules from the complete JSON reference before passing the creation gate.", "A deterministic finding is not automatically a deterministic repair; follow Diagnostics v2 constraints, investigate repeated context, and re-enter the creation gate before any newly justified asset-boundary change."]; readonly nextSteps: readonly ["Investigate relevant evidence, evaluate the creation gate, clarify only unresolved Blocking human truth when needed, and retain unresolved decisions instead of inventing or hiding answers.", "Establish the smallest non-redundant asset graph as a gate requirement; declare the gate passed only after every requirement is established and no Blocking authoring decision remains, then record a renma.skill-authoring-handoff.v1 exchange artifact.", "Run renma scaffold skill <agreed-path> --handoff <handoff.json>, then separately scaffold or reuse only justified Context Assets.", "Complete the focused workflow and run renma scan . --fail-on high.", "Classify findings, inspect applicable evidence, re-enter the gate for boundary changes, apply only uniquely supported repairs, rerun, and require human review."]; readonly options: readonly [{ readonly name: "format"; readonly description: "Output format: prompt or json. Defaults to prompt."; }, "json", "help"]; }, { readonly name: "scaffold"; readonly usage: "renma scaffold <skill|context|context_lens> <path> [options]"; readonly question: "How can a new asset start from a deterministic structure?"; readonly purpose: "Scaffold creates deterministic starter structures for one explicitly requested Skill, Context Asset, or Context Lens after its responsibility and asset boundary have been decided. It does not initialize repository-level configuration. A Skill is a focused workflow entrypoint, Context is independently maintained knowledge, and a Context Lens is purpose-specific interpretation of declared Context."; readonly useWhen: readonly ["You are creating a new skill, context asset, or context lens.", "You want a starter file or prompt with expected metadata and sections.", "You need a deterministic starting point before authoring content."]; readonly doNotUseFor: readonly ["Generating a complete production-ready skill or context.", "Inventing domain knowledge merely to fill the template.", "Replacing author-provided purpose, routing boundaries, inputs, completion criteria, verification, or references.", "Using context_lens as generic persona storage, a prompt template, or a runtime routing rule.", "Creating a Context Lens when no existing Context Asset needs purpose-specific interpretation."]; readonly examples: readonly ["renma scaffold skill skills/testing/spec-review/SKILL.md --owner qa-platform", "renma scaffold skill skills/testing/spec-review/SKILL.md --handoff /tmp/spec-review-handoff.json", "renma scaffold context contexts/testing/boundary-value-analysis.md --owner qa-platform", "renma scaffold context_lens lenses/testing/spec-review-boundary-values.md --owner qa-platform", "renma scaffold skill skills/testing/spec-review/SKILL.md --owner qa-platform --format prompt", "renma scaffold skill skills/testing/spec-review/SKILL.md --owner qa-platform --resources references,scripts,assets"]; readonly interpretation: readonly ["File mode creates the scaffold file at the target path and refuses to overwrite existing files.", "Prompt and JSON modes print to stdout instead of creating the scaffold file.", "--handoff is optional and supported only for Skill scaffolds. The file may be outside the repository and is consumed without network access.", "A supplied handoff is caller-declared authoring evidence. Renma validates its shape, zero declared Blocking decisions, target agreement, identity, and asset-graph consistency; it does not prove that clarification or human review occurred, every blocker was discovered, sources are authoritative, or domain claims are true.", "With --handoff, the positional target remains the explicit side-effect boundary and must match assetGraph.skill.path after safe normalization. Do not combine --handoff with --id, --title, --owner, --tags, or --resources.", "Proposed reversible defaults and Unresolved Deferred decisions may remain when progression.blocking is empty.", "--resources creates only selected empty directories and never placeholder files.", "Generated scaffold content is a starting structure, not a complete asset.", "Renma reports only its own exact generated Skill and Context starter markers as High findings. Replace every marker before the strict release or CI scan; this deterministic check does not certify general semantic completeness.", "For Skills, first use renma guide skill to establish the smallest asset structure and repository boundaries; use platform-native Skill authoring guidance only to refine semantics within those boundaries.", "Correctness importance alone does not justify a Context Asset without an independent maintenance or governance boundary.", "A finished Skill may access a reviewed external source only when its workflow and effective security policy explicitly permit it; scaffold generation itself performs no network operations.", "For Context Lenses, replace every placeholder purpose, applies_to target, focus, and expected output with repository-grounded values; applies_to must resolve to real Context Assets.", "Domain knowledge must come from evidence or human input."]; readonly nextSteps: readonly ["Review and complete the generated content with evidence-backed details.", "Run renma scan . --fail-on high --strict, replace any exact Renma scaffold markers, fix relevant diagnostics, and rerun the scan.", "Use https://github.com/KazuCocoa/renma/blob/main/docs/authoring-guide.md for placement decisions and https://github.com/KazuCocoa/renma/blob/main/docs/context-lens.md for Lens semantics.", "Have a human review meaningful semantic content before merging."]; readonly options: readonly [{ readonly name: "format"; readonly description: "Output format: file, prompt, or json. Defaults to file. File mode writes the scaffold to the target path and requires --owner for direct scaffolds; a Skill --handoff supplies its owner. Prompt and JSON modes print to stdout instead of creating the target file."; }, { readonly name: "owner"; readonly description: "Set owner metadata on the scaffold. Required when --format file is used. A Skill --handoff supplies its owner instead."; }, "id", "title", "tags", "resources", "handoff", "help"]; }, { readonly name: "suggest-metadata"; readonly usage: "renma suggest-metadata <file> [options]"; readonly question: "How can a coding agent prepare a metadata retrofit or one-way Skill migration?"; readonly purpose: "Suggest metadata emits classification and an explicit decision for one existing target. Pre-0.16 Renma Skill targets use the one-way migration path to Agent Skills; canonical Agent Skills support an explicit owner retrofit; ordinary Skill-local support may return a successful no-proposal result."; readonly useWhen: readonly ["An asset lacks compact metadata and you want a reviewable metadata patch.", "A Skill with pre-0.16 Renma fields needs an Agent Skills plus metadata.renma.* conversion proposal.", "A skill.md or *.skill.md entrypoint needs its required rename or move reported.", "A canonical Agent Skill needs an explicit metadata.renma.owner candidate from --owner.", "You need guidance that preserves the existing Markdown body and semantics.", "A human explicitly provides an owner with --owner or the asset already declares one."]; readonly doNotUseFor: readonly ["Editing the file automatically.", "Converting a canonical Agent Skill back to pre-0.16 Renma frontmatter.", "Silently resolving blocked, conflicting, duplicate, or unknown migration input.", "Changing the Markdown body or asset semantics unless explicitly requested.", "Inferring an owner without evidence."]; readonly examples: readonly ["renma suggest-metadata skills/testing/spec-review/SKILL.md --format prompt", "renma suggest-metadata skills/testing/spec-review/SKILL.md --owner qa-platform --format json", "renma suggest-metadata skills/testing/spec-review.skill.md --format json"]; readonly interpretation: readonly ["The command prints to stdout and does not edit the target file.", "For Skill targets, canonical frontmatter is omitted when migration is unsafe or ambiguous.", "Historical skill.md and *.skill.md filename forms report the required rename or move in structured output.", "A path migration is blocked when the target exists separately or the rendered target Skill remains specification-invalid.", "For canonical Agent Skills, --owner can propose a metadata retrofit without reverse migration.", "Skill-local support without explicit override evidence returns no-proposal and does not manufacture independent metadata.", "Repository tools and unknown paths do not receive fabricated Context Asset candidates.", "Without --owner, do not add owner metadata unless the asset already declares one or a maintainer confirms it.", "Preserve existing Markdown body and semantics for a metadata-only retrofit.", "For Skills, metadata review is only one part of authoring review; use platform-native Skill authoring guidance for the trigger description, instructions, workflow, constraints, and completion criteria."]; readonly nextSteps: readonly ["Review the output; apply only an available, intended, evidence-backed metadata or migration candidate.", "If no proposal is available, preserve the source unless a separate intentional authoring change is reviewed.", "After intended changes, run renma scan . --fail-on high, fix relevant diagnostics, and rerun the scan.", "Report any missing owner, reference, or source-of-truth uncertainty."]; readonly options: readonly [{ readonly name: "format"; readonly description: "Output format: prompt or json. Defaults to prompt. The command prints to stdout and does not edit the target file."; }, "json", { readonly name: "owner"; readonly description: "Explicitly provide an owner candidate. Renma must not infer an owner when this option is absent."; }, "help"]; }, { readonly name: "suggest-semantic-split"; readonly usage: "renma suggest-semantic-split <file> [options]"; readonly question: "How can a coding agent prepare a reviewable semantic split?"; readonly purpose: "Suggest semantic split packages bounded source material and instructions for drafting a semantic split."; readonly useWhen: readonly ["A Markdown asset is too large or mixes multiple responsibilities.", "A coding agent needs bounded source context and deterministic helper commands.", "You want a prompt or JSON review bundle before proposing a split."]; readonly doNotUseFor: readonly ["Editing files automatically.", "Splitting merely to satisfy a size metric when boundaries are not semantically meaningful.", "Dropping meaning, references, metadata, or review context."]; readonly examples: readonly ["renma suggest-semantic-split docs/large-runbook.md", "renma suggest-semantic-split docs/large-runbook.md --format json", "renma suggest-semantic-split docs/large-runbook.md --max-source-bytes 32768"]; readonly interpretation: readonly ["The command prints to stdout and does not edit files.", "A split must preserve meaning and references.", "The resulting patch requires review."]; readonly nextSteps: readonly ["Draft bounded files only when the proposed boundaries are meaningful.", "Preserve references and summarize uncertainty.", "Run scan, catalog, graph, and readiness after editing."]; readonly options: readonly [{ readonly name: "format"; readonly description: "Output format: prompt or json. Defaults to prompt. The command prints to stdout and does not edit files."; }, "json", "max-source-bytes", "max-context-bytes", "help"]; }]; export type CommandName = (typeof COMMAND_HELP)[number]["name"]; export declare function isCommandName(value: string): value is CommandName; /** Return the documented option names accepted by one command. */ export declare function commandOptionNames(name: CommandName): CliOptionName[]; /** Return the authoritative help contract for one registered command. */ export declare function commandHelpDefinition(name: CommandName): CommandHelp; export declare function renderGlobalHelp(version: string): string; export declare function renderCommandHelp(name: CommandName, version: string): string; export {};