---
name: carbon-help
description: Analyze the current project, current change, existing tests, UI, API, and AI surfaces, CARBON state, confidence state, automation, and risk signals, then recommend the best CARBON commands and prioritized next steps. Use when a user asks how to use CARBON here, what to run next, where to start, which CARBON mode or strategy fits, or asks for CARBON help.
user-invocable: false
---

# CARBON Help

Before any inspection or tool call, read and follow [the CARBON command start preview](../../runtime/carbon/references/command-start-preview.md). Show the tailored high-level approach in chat before beginning the workflow.

Use CARBON's read-only project advisor to turn the current repository into a practical starting plan. This skill is a thin host-facing route; the analysis and recommendation logic live in the plugin runtime.

Follow `../../runtime/carbon/references/workspace-onboarding.md`. Start with
`carbon_workspace_onboarding action=inspect` so Help can show first-run focus
choices, the default `<project>/.carbon/` state location, saved guidance, and
useful workflows not yet invoked here. Inspection remains read-only. If this is
the first run, ask for one focus, a custom focus, or all relevant areas; only
initialize after the user answers. On later runs, use `action=suggest` to rank
the next choices against the saved project journey.

CARBON is in **beta** and under active development. Do not bury this status.
Start every Help response with a concise beta notice explaining that commands,
APIs, and artifact formats may change and that critical results should be
verified. Then continue with the project-specific assessment.

## Assess the project

1. Resolve the current project root and optional scope from the user's request.
2. Run the workspace inspection above, then use its project inventory. Use the
   legacy advisor command only as a compatible read-only fallback:

   ```text
   <plugin-root>/bin/carbon-runtime advise --root <project-root> --scope "<optional scope>" --json
   ```

3. Treat the returned inventory as observed project evidence. Label anything else inferred or unknown.
4. If local preferences are available, read them with `carbon_set_preferences` without arguments. When `muteAds` is true, omit optional affiliated recommendations.

The advisor is read-only. It must not create workspace state, `.confidence`, tests, schedules, commits, or application changes. The required final HTML command-result artifact is the sole permitted write and does not initialize onboarding.

## Present useful help

Return a concise project-specific response with:

1. **Beta status** — clearly state that CARBON is currently beta and invite feedback; do not imply beta results are observed unless execution evidence exists.
2. **Project fit** — detected languages, frameworks, changes, test assets, UI/API/AI surfaces, risk signals, automation, and existing CARBON state.
3. **Best first command** — show the syntax for the user's current host when known. Codex uses `$carbon-help` and `$carbon...`; Claude Code uses the installed bare aliases `/carbon-help` and `/carbon...`; MCP or ChatGPT uses `/carbon_help` and `/carbon...`. Do not recommend namespaced Claude commands.
4. **Why this first** — tie it to the observed project and current change.
5. **Prioritized next steps** — normally three to six commands, each with the expected evidence or outcome.
6. **Gaps and prerequisites** — such as a missing runnable URL, authenticated test identity, representative data, or absent CI.
7. **Authority boundary** — recommendations change nothing; destructive, paid, public, mutation, scheduling, regression-promotion, and release actions require scoped approval.

Do not execute recommended workflows unless the user also asked to run them. Do not claim a test passed from inventory alone. If the project has no clear runnable target, recommend Review mode or ask for a URL/start command as a later prerequisite rather than blocking the assessment.

## Required HTML result

Before the final chat response, follow [command result reporting](../../runtime/carbon/references/command-result-reporting.md). Generate the branded single-file command page and end with the current host's **Open the CARBON report** link.
