From da05114a36d6c6ba416f3be101ca7bc4323e69d1 Mon Sep 17 00:00:00 2001 From: HarshPopat23 Date: Fri, 23 Oct 2026 15:51:08 +0530 Subject: [PATCH] docs: add step-by-step Claude and Antigravity usage guides --- README.md | 20 +++- docs/antigravity.md | 210 ++++++++++++++++++++++++++++++++++++++ docs/claude-code-cloud.md | 95 +++++++++++++++++ docs/claude-code.md | 193 +++++++++++++++++++++++++++++++++++ docs/claude-web.md | 161 ++++++++++++++++++++++++----- docs/skills.md | 11 +- docs/usage.md | 70 +++++++++++++ skills/README.md | 8 +- 8 files changed, 733 insertions(+), 35 deletions(-) create mode 100644 docs/antigravity.md create mode 100644 docs/claude-code-cloud.md create mode 100644 docs/claude-code.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index 78e250c..99d435c 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ # SHContext -SHContext is a repository context generator under development. It will create a `context/` +SHContext is a repository context generator under development. It creates a `context/` directory that mirrors source folders and explains their responsibilities with source references and explicit coverage limits. -The CLI implements local `scan ` and `build ` with one -OpenAI provider, incremental `update `, plus offline `verify `. Builds collect inspected evidence, summarize folders from leaves +The CLI implements local `scan `, active-host generation through +`prepare`/`submit`/`finalize`, optional OpenAI API `build`/`update`, and offline +`verify ` and `query`. Builds collect inspected evidence, summarize folders from leaves to root, add conservative relationships and publish a mirrored `context/` tree. The reusable library exposes shared schemas, JS/TS analysis, generation and local context querying. Four execution roles run sequentially by default; bounded folder @@ -18,6 +19,15 @@ The current `0.1.0-alpha.1` candidate remains experimental. Start with the offline walkthrough. See [evaluation methods and results](docs/benchmarks.md), [organization freshness CI](docs/ci.md) and [release preparation](docs/release.md). +## Choose your environment + +Start with [the step-by-step usage guides](docs/usage.md): + +- [Claude Code terminal](docs/claude-code.md): local installation, first build, questions, changes, updates and recovery. +- [Claude web chat](docs/claude-web.md): four skill uploads, small source ZIPs, downloads and cross-chat updates. +- [Antigravity IDE](docs/antigravity.md): separate tool/source folders and an explicit local host-authoring workflow. +- [Claude Code on the web](docs/claude-code-cloud.md): cloud checkout/setup, distinct from ordinary Claude chat. + ## Use uploaded repositories in Claude web Build the web distribution with `npm run package:web -- /absolute/new/output` @@ -27,13 +37,13 @@ enable code execution, and attach a source-only repository ZIP. Ask: “Use context-web-build to generate context for frontend/src/lib/router from this Headlamp archive and return a downloadable context ZIP.” See [installation, runtime requirements and updates](docs/claude-web.md). -Actual Claude web account acceptance is [still pending](docs/claude-web-acceptance.md); +The bounded Claude web workflow has [actual account acceptance evidence](docs/claude-web-acceptance.md); the CLI/plugin installation below is separate. ## Install the workflow plugin Prepare the source checkout below, set its absolute path as `SHCONTEXT_HOME`, then -run these inside Claude Code after this change is merged: +run these inside Claude Code: ```text /plugin marketplace add HarshPopat23/SHContext diff --git a/docs/antigravity.md b/docs/antigravity.md new file mode 100644 index 0000000..c983577 --- /dev/null +++ b/docs/antigravity.md @@ -0,0 +1,210 @@ +# Antigravity IDE: generate context for a local repository + +Use Antigravity's agent as the author and SHContext's local CLI as the scanner, +validator and publisher. This guide covers two separate local checkouts, such as +Headlamp and SHContext, already opened or accessible in Antigravity. + +**Integration status:** SHContext ships a Claude Code plugin and Claude web +skills. It does not currently ship a dedicated Antigravity plugin or certify +Antigravity skill discovery. The supported building blocks here are the existing +host-mode commands. This is an explicit agent workflow, not a claim that the +Claude plugin's slash commands install into Antigravity. The local protocol is +exercised in tests; an actual Antigravity IDE session has not been acceptance-tested. + +## 1. Check prerequisites and prepare the tool + +You need an Antigravity account/model session with permitted local file and +terminal access, Git, Node 22.14+ on the 22 line or Node 24, and npm 10+. +The host account's normal allowance applies; no separate OpenAI generation key +is needed. Follow your organization's normal source-access settings. + +Example folders: `/work/SHContext`, `/work/headlamp`, and a private session parent +`/work/shcontext-sessions`. Use your existing clones, or run in the IDE terminal: + +```sh +cd /work +git clone https://github.com/HarshPopat23/SHContext.git +git clone https://github.com/kubernetes-sigs/headlamp.git +cd /work/SHContext +npm ci +node dist/cli/index.js --help +mkdir -p /work/shcontext-sessions +``` + +Do not install Headlamp's dependencies. In a Windows PowerShell terminal, use +`C:/work/...` paths and create the session parent with +`New-Item -ItemType Directory -Force C:/work/shcontext-sessions`. + +## 2. Give the agent the correct paths + +Open Headlamp in the IDE and make the SHContext checkout and session parent +accessible through the IDE's permitted workspace/file access. If access is denied, +use a dedicated parent workspace containing these checkouts or grant the required +folder access through the host UI. Do not work around an organization restriction. +Opening two folders does not automatically tell the agent which one to analyze. + +Use these roles explicitly in prompts: + +| Path | Role | +| ---------------------------------------- | ---------------------------------------- | +| `/work/SHContext` | Trusted tool and workflow documentation | +| `/work/headlamp/frontend/src/lib/router` | Selected source root | +| `/work/shcontext-sessions` | Existing parent for new private sessions | + +The target is the router folder, so output belongs inside its `context/` directory. +A GUI-launched agent may not inherit variables exported in an IDE terminal. +Give absolute paths in the prompt; do not assume `SHCONTEXT_HOME` is available. + +## 3. Select host mode with truthful provenance + +Inspect the target's configuration and exclusions. If there is no +`shcontext.config.json`, create it in the selected router folder: + +```json +{ + "version": 1, + "provider": { "id": "host", "model": "antigravity-session" } +} +``` + +Keep other existing settings. If a provider already exists, deliberately decide +whether to migrate it rather than overwriting the file. The label identifies the +host workflow; it is not an authenticated model ID. Do not use `claude-code-session` +for analysis actually authored in Antigravity. Changing provider/model labels +invalidates previous generation, so keep the chosen label stable for updates. + +Scan from the IDE terminal: + +```sh +node "/work/SHContext/dist/cli/index.js" scan "/work/headlamp/frontend/src/lib/router" +``` + +Inspect coverage and skipped files. Selecting a subfolder does not inherit parent +configuration, ignore rules or source dependencies. Go and other unsupported +languages are inventory-only; choose an appropriate JS/TS scope first. + +## 4. Ask the agent to perform the complete build + +Paste this into Antigravity's agent chat with your actual paths: + +```text +Generate SHContext context for this local repository folder. +Tool checkout: /work/SHContext +Selected source root: /work/headlamp/frontend/src/lib/router +Existing private session parent: /work/shcontext-sessions + +Read /work/SHContext/docs/host-generation.md for the implemented host protocol. +You are the active Antigravity author: use provider id host and provenance label +antigravity-session, preserving existing settings. If a different provider is +configured, stop and report the required migration instead of silently replacing it. + +Use a new session directory outside the selected source root. Run scan and +prepare. For each awaiting_draft request, read the full request and relevant +source, author a JSON response matching draft_schema, cite supplied evidence IDs, +and submit. Work sequentially from children to parents. Continue until ready, +then finalize and verify. Report output paths, coverage, accepted drafts and +uncertainty. Do not call a model API, run source/tests, install Headlamp +dependencies, edit final Markdown or commit generated output. +``` + +Do not send only “run shcontext build”: that command selects the optional API +workflow. Do not ask the agent to write final `CONTEXT.md` directly; it would omit +SHContext's validated publication/cache protocol. + +The agent should execute commands equivalent to: + +```sh +node "/work/SHContext/dist/cli/index.js" prepare "/work/headlamp/frontend/src/lib/router" --session "/work/shcontext-sessions/headlamp-router-1" +``` + +`headlamp-router-1` must be new; its parent must exist. When status is +`awaiting_draft`, the agent reads the returned `request_file` and writes +`response.json` in that session. It must copy current session/request IDs and +cover every supplied direct source once. Then: + +```sh +node "/work/SHContext/dist/cli/index.js" submit "/work/headlamp/frontend/src/lib/router" --session "/work/shcontext-sessions/headlamp-router-1" --draft "/work/shcontext-sessions/headlamp-router-1/response.json" +``` + +Repeat for each new request. Once status is `ready`: + +```sh +node "/work/SHContext/dist/cli/index.js" finalize "/work/headlamp/frontend/src/lib/router" --session "/work/shcontext-sessions/headlamp-router-1" +node "/work/SHContext/dist/cli/index.js" verify "/work/headlamp/frontend/src/lib/router" +``` + +These commands validate but do not author the summaries: the Antigravity agent +must supply its own evidence-grounded drafts. The empty envelope illustration in +the protocol guide is not a valid finished draft. No parallel workers are required. + +## 5. Read and query the result + +Open `headlamp/frontend/src/lib/router/context/CONTEXT.md`. Keep the manifest, +report and cache in `context/.shcontext/`; they support future updates. Review +source citations and partial-coverage findings. Mechanical freshness is not proof +that every explanation is accurate or that any tests ran. + +Ask the agent: + +```text +Use /work/SHContext to query context for +/work/headlamp/frontend/src/lib/router: Where are route URLs created? +Run the local query operation, check freshness, read relevant current source +and cite paths/lines. Label outside-scope or unresolved relationships. +Do not regenerate context or edit files. +``` + +The underlying read-only command is: + +```sh +node "/work/SHContext/dist/cli/index.js" query "Where are route URLs created?" --root "/work/headlamp/frontend/src/lib/router" --json +``` + +## 6. Refresh after an edit + +After editing source, verify should report stale (exit 1 for a controlled change). +Ask the agent to use the same host label and root but a **new** session, for example +`/work/shcontext-sessions/headlamp-router-2`: + +```text +Refresh existing SHContext context for /work/headlamp/frontend/src/lib/router. +Use /work/SHContext, provider host/model antigravity-session, and a new session +/work/shcontext-sessions/headlamp-router-2. Follow the host protocol with +prepare --update, author only requested drafts, submit, finalize and verify. +Report affected/regenerated/reused folders. Do not use the API update command, +change unrelated files or commit context. +``` + +The first command is: + +```sh +node "/work/SHContext/dist/cli/index.js" prepare "/work/headlamp/frontend/src/lib/router" --session "/work/shcontext-sessions/headlamp-router-2" --update +``` + +Submission/finalization use the same steps as the build, with the new session +path. An unchanged update can return `ready` immediately with zero new drafts; +it still needs finalize and verify. Preserve valid cached summaries rather than +rewriting them manually. + +## 7. Failures and native skills + +If the agent cannot access the tool/target, fix the allowed workspace paths first. +If Node or the built CLI is missing, prepare the trusted tool checkout. If the +host cannot execute commands or author the required JSON, this workflow is blocked; +plain prose summaries are not a validated SHContext result. + +Exit 2 at finalization/verification means partial coverage; exit 1 means failure +or non-fresh verification. Inspect diagnostics. Interrupted sessions can resume +with the same root/session/mode when inputs remain unchanged. Source/config/output +changes require a new session. Preserve unknown output, locks and journals; never +delete them just to get a passing result. See [host recovery](host-generation.md). + +Google documents workspace skills at `.agents/skills//SKILL.md` (legacy +`.agent/skills` also exists), with surface-specific global paths. That is the +host's discovery convention, not a declaration that SHContext ships an +Antigravity adapter. This guide deliberately uses explicit paths and the shared +protocol. Do not copy only Claude-specific SKILL.md files and assume their host +labels, slash namespaces or relative resources adapt automatically. See +[Google's skills reference](https://antigravity.google/docs/skills) and +[Google's skill-authoring codelab](https://codelabs.developers.google.com/getting-started-with-antigravity-skills) +if developing a separate host-specific skill later. diff --git a/docs/claude-code-cloud.md b/docs/claude-code-cloud.md new file mode 100644 index 0000000..032c79d --- /dev/null +++ b/docs/claude-code-cloud.md @@ -0,0 +1,95 @@ +# Claude Code on the web: use the cloud checkout + +This means **claude.ai/code**, where Claude Code works in a cloud environment. +For ordinary Claude chat with attached ZIPs, use [the web chat guide](claude-web.md). +A path on your laptop is not a path inside the cloud environment. + +Anthropic's [cloud guide][cloud] describes repository connection and environment +setup. Its [plugin installation guide][plugins] says cloud sessions do not load +plugins installed on your computer or those enabled only in repository settings. +This guide therefore uses SHContext's explicit host protocol, rather than claiming +that `/plugin install` or uploaded web skills configure a Code cloud session. +An actual SHContext cloud-session acceptance test has not been run. + +## 1. Connect the repository + +1. Open Claude Code on the web and use the host's onboarding to connect an + authorized repository, such as a Headlamp checkout/fork you can access. +2. Select the intended branch and cloud environment. Local unpushed edits may + not be present; inspect the actual checkout before generating context. +3. Confirm that the session has file/terminal access. Follow the organization's + normal policy for any setup downloads; do not assume unrestricted network. + +This does not require attaching the ordinary-chat source ZIP. The cloud checkout +is the source input. Account access and normal Claude usage limits still apply. + +## 2. Prepare SHContext in that environment + +Ask the agent to report `pwd`, the absolute Headlamp checkout path, +`node --version`, `npm --version` and `git --version`. Require Node 22.14+ on the 22 line +or Node 24, with npm 10+. Do not guess `/work/headlamp` or your laptop's tool path. + +Use the cloud environment's documented setup mechanism or permitted terminal +commands to clone a reviewed SHContext revision into a separate tool directory +and run `npm ci` there. GitHub/npm setup access is needed; if unavailable, report +that prerequisite instead of switching to an API or inventing an installed tool. +No Headlamp dependency install is needed. Do not store the tool inside the selected +router folder or a temporary plugin cache. Verify the built CLI with: + +```sh +node /absolute/cloud/SHContext/dist/cli/index.js --help +``` + +Use actual reported paths, not these placeholders. Keep the reviewed tool revision +consistent across build/update sessions, or expect generator invalidation. + +## 3. Generate with the active cloud session + +Send this prompt after substituting the actual cloud paths: + +```text +Use the SHContext host protocol in +/absolute/cloud/SHContext/docs/host-generation.md. +Tool checkout: /absolute/cloud/SHContext +Selected source root: /absolute/cloud/headlamp/frontend/src/lib/router +Private session parent: /absolute/cloud/shcontext-sessions + +Create the session parent if missing and select a new child session outside +source. Use provider host and provenance label claude-code-cloud-session. +Preserve existing configuration; report before changing an existing provider. +Run scan, prepare, author each requested structured draft from inspected evidence, +submit sequentially, finalize and verify. Include references, coverage and +uncertainty. Do not install Headlamp dependencies, run source/tests or commit. +``` + +The model label is declared provenance, not a discovered exact model ID. This +uses the active Claude session; no separate OpenAI generation key is needed. +The command contract and accepted draft schema are the same as +[the local host protocol](host-generation.md). The selected router root receives +`context/CONTEXT.md` and its owned manifest/report/cache. + +## 4. Ask, change, update and retain results + +Ask the cloud agent to run `query "your question" --root --json`, +check freshness and inspect cited current source. For a standalone check use +`verify `. Neither command should silently regenerate context. +After an edit, request `prepare --session +--update`, then agent-authored drafts, submit, finalize and verify. Keep the same +host label and scope. An unchanged update should request zero new drafts. + +Cloud files can outlive a command without being durable across environment resets. +Before ending, explicitly choose whether to download a full copy of `context/` +(including cache/manifest/report), or review and save it through your normal Git +branch/PR workflow. This guide does not authorize automatic commits or PRs in the +target repository. Private session state is not generated context to commit. +If the cloud environment expires, re-establish the tool/source paths and recover +only from state that actually remains. Do not claim a finished published result +from conversation history alone. + +If runtime/setup access or account policy blocks execution, report the missing +prerequisite. If context is invalid/unowned, preserve it and inspect the error. +For expected stale/partial exits and session recovery, follow +[verification](verification.md) and [host generation](host-generation.md). + +[cloud]: https://code.claude.com/docs/en/claude-code-on-the-web +[plugins]: https://code.claude.com/docs/en/plugins/install diff --git a/docs/claude-code.md b/docs/claude-code.md new file mode 100644 index 0000000..9ed1a0e --- /dev/null +++ b/docs/claude-code.md @@ -0,0 +1,193 @@ +# Claude Code terminal: install, build, ask, update + +This walkthrough uses the active Claude Code session for analysis. You need +Claude Code access, Git, Node **22.14+ on the 22 line or Node 24**, and npm 10+. +Check `node --version`, `npm --version`, `git --version` and `claude --version`. +Install/sign in to Claude Code using its [official setup guide][setup] if missing. +SHContext's recorded plugin-host check used Claude Code 2.1.308; newer host +behavior may differ. No separate model API key is needed for this workflow. + +The shell examples below use macOS/Linux/Git Bash syntax. PowerShell equivalents +for setup follow in step 2. Replace paths with your actual absolute paths. + +## 1. Keep the tool and repository separate + +Example layout: `/work/SHContext` is the tool, `/work/headlamp` is source, and +`/work/shcontext-sessions` holds private generation sessions. Existing clones are +fine. Otherwise create a work directory, then run: + +```sh +cd /work +git clone https://github.com/HarshPopat23/SHContext.git +git clone https://github.com/kubernetes-sigs/headlamp.git +cd /work/SHContext +npm ci +node dist/cli/index.js --help +``` + +Only install SHContext's dependencies. Headlamp does not need `npm install`, a +build or running tests to be analyzed. `npm ci` builds SHContext through its +prepare script. This alpha is not published as an npm registry install; do not +replace these commands with `npx shcontext`. + +## 2. Select the target and create a session parent + +In the same terminal that will start Claude: + +```sh +export SHCONTEXT_HOME="/work/SHContext" +export SHCONTEXT_REPO="/work/headlamp/frontend/src/lib/router" +mkdir -p /work/shcontext-sessions +node "$SHCONTEXT_HOME/dist/cli/index.js" scan "$SHCONTEXT_REPO" +``` + +The selected directory is the analysis root, not a filter within the whole +Headlamp repository. It controls output location and available configuration, +ignore rules and dependency targets. Parent configuration is not inherited. +Inspect scan coverage and exclusions before proceeding. Exit 2 means partial +coverage; read the report instead of treating that as complete analysis. + +PowerShell setup for an equivalent `C:/work` layout: + +```powershell +$env:SHCONTEXT_HOME = 'C:/work/SHContext' +$env:SHCONTEXT_REPO = 'C:/work/headlamp/frontend/src/lib/router' +New-Item -ItemType Directory -Force 'C:/work/shcontext-sessions' +node "$env:SHCONTEXT_HOME/dist/cli/index.js" scan "$env:SHCONTEXT_REPO" +``` + +When using later terminal examples in PowerShell, replace `$SHCONTEXT_HOME` with +`$env:SHCONTEXT_HOME`, and likewise for other environment variables. + +## 3. Load the five skills + +For the first session, use the local checkout directly: + +```sh +cd "$SHCONTEXT_REPO" +claude --plugin-dir "$SHCONTEXT_HOME" +``` + +This flag loads this checkout for that session; repeat it when starting another +session. Look for `/shcontext:context-build`, `context-update`, `context-query`, +`context-verify` and `context-benchmark` under the `shcontext` namespace. + +For persistent installation, run these commands **inside Claude Code** instead: + +```text +/plugin marketplace add /work/SHContext +/plugin install shcontext@shcontext-workflows +``` + +Use your tool checkout's actual path. A user-scope install affects your host's +plugin settings, not Headlamp source. After installation, follow the reload +instruction or start a fresh session. Check from a shell with +`claude plugin list --json`. The plugin adds instructions, not an installed tool +runtime: retain `SHCONTEXT_HOME` and its built checkout. For GitHub marketplace +installation and version pinning, see [the installation reference](skills.md). +Use either the local session flag or the persistent route to avoid duplicate +plugin versions. These routes follow Anthropic's [plugin creation][create] and +[installation][install] contracts. + +## 4. Ask Claude to build the first context + +Send this in Claude Code, replacing the three example paths if needed: + +```text +/shcontext:context-build +Tool checkout: /work/SHContext +Selected source root: /work/headlamp/frontend/src/lib/router +Session parent: /work/shcontext-sessions + +Use this active Claude session to analyze source and author structured drafts. +Create a missing shcontext.config.json with provider id host and model label +claude-code-session; preserve any existing configuration and ask before changing +an existing provider. Use a new session directory outside the selected root. +Run scan, prepare, submit each requested draft sequentially, finalize and verify. +Include source references, coverage and uncertainty. Do not install Headlamp's +dependencies, run its code/tests or commit context. Report the final output path. +``` + +If a configuration already selects OpenAI, deliberately choose whether to migrate +it before continuing. Preserve its other settings. A missing host configuration +is equivalent to this file in the selected router folder: + +```json +{ + "version": 1, + "provider": { "id": "host", "model": "claude-code-session" } +} +``` + +Claude reads bounded evidence and writes JSON drafts, children before parents. +SHContext renders Markdown only after validating the drafts and current source. +`prepare` alone is not completion. Expect `finalize` to report `published`, then +`verify` to report `fresh` and the actual coverage. Check: + +```sh +node "$SHCONTEXT_HOME/dist/cli/index.js" verify "$SHCONTEXT_REPO" +``` + +Open `frontend/src/lib/router/context/CONTEXT.md` in Headlamp. Keep the generated +manifest, report and cache. Outside-folder imports and unexecuted tests should be +labeled. Do not interpret the router-only context as whole-project coverage. + +## 5. Ask questions with current-source references + +```text +/shcontext:context-query +For /work/headlamp/frontend/src/lib/router, where are route URLs created? +Check context freshness, inspect the relevant source, and cite paths and lines. +Explain which parts of authentication enforcement are outside this scope. +Do not regenerate context. +``` + +The equivalent read-only terminal operation is: + +```sh +node "$SHCONTEXT_HOME/dist/cli/index.js" query "Where are route URLs created?" --root "$SHCONTEXT_REPO" --json +``` + +A stale/missing context result can still contain current-source candidates, but +Claude must label them. No match does not prove the implementation is absent. + +## 6. Change source, refresh and verify + +After a normal source edit, run verify again. A controlled input change should +produce stale with exit 1; do not chain the expected stale check to the update +with `&&`, because that would prevent the update from running. + +```text +/shcontext:context-update +Refresh existing context for /work/headlamp/frontend/src/lib/router using +/work/SHContext and a new session under /work/shcontext-sessions. +Use this Claude session, preserve the configured host provenance, regenerate +only affected summaries and report regenerated/reused folders. Finalize and +verify. Do not commit anything. +``` + +Then use `/shcontext:context-verify` for the same root. Repeating update without +source/configuration/generator changes should require zero new host drafts. +The optional benchmark skill exercises controlled evaluations in the complete +tool checkout; it is not a prerequisite for using your context. + +## 7. Recover or update the installation + +If a session is interrupted, use the same root, session path and mode to resume +`prepare`; see [the protocol](host-generation.md). If source/config/output changed +mid-session, preserve the old session/output and start a new session. Never edit +session IDs, generated Markdown, locks or journals to force verification through. +Finalize/verify exit 0 means complete/fresh, 2 means partial, and 1 means failure +or non-fresh verification. A mechanically fresh result does not prove prose true. + +If skills are missing, check the plugin path/namespace and reload. If the CLI is +missing, run `npm ci` in the trusted SHContext checkout, not the plugin cache. +To upgrade a reviewed checkout, update tool and plugin together, reinstall or +refresh the marketplace, and start a new host session. Generation-version changes +can invalidate the context cache. Do not rely on absolute paths from another +machine. For teams, document a reviewed commit and local paths rather than +committing a developer's `SHCONTEXT_HOME`. + +[setup]: https://code.claude.com/docs/en/setup +[create]: https://code.claude.com/docs/en/plugins/create +[install]: https://code.claude.com/docs/en/plugins/install diff --git a/docs/claude-web.md b/docs/claude-web.md index 8f58329..2d5cad8 100644 --- a/docs/claude-web.md +++ b/docs/claude-web.md @@ -13,22 +13,23 @@ multi-folder invalidation and rejection controls passed. See the detailed [web acceptance record](claude-web-acceptance.md); runtime availability and account policies still vary. -## Get and install the ZIPs +## 1. Download the four web skill ZIPs -A maintainer builds them from a prepared source checkout: +You do not need Claude Code or a terminal on your computer for the consumer +workflow. In the SHContext GitHub repository: -```sh -npm ci -npm run package:web -- /absolute/new/shcontext-web-distribution -``` +1. Open **Actions** and select a successful **CI** run for the reviewed revision + you intend to use. The run must include the **Claude web skill ZIPs** job. +2. In the run's artifacts, download **shcontext-web-skills**. GitHub may require + sign-in. This is an outer artifact ZIP, not itself a Claude skill. +3. Extract the outer artifact once. It contains four `context-web-*.zip` files, + `SHA256SUMS` and `web-distribution.json`. Upload the four inner ZIPs as-is; + **do not extract their contents**. Use a recent distribution containing the + [tested upload-format fixes](claude-web-acceptance.md), not a whole SHContext + repository download or the old dependency-tree packages. -Build prerequisites: Git, Node 22.14+ (22.x) or Node 24, npm 10+, Python 3.9+. -On Windows the packager uses `python`; elsewhere `python3`. Output must be a new -directory outside the checkout. Add `--require-clean` for review/release artifacts. -CI's **Claude web skill ZIPs** job uploads `shcontext-web-skills`, containing four -ZIPs, `SHA256SUMS` and `web-distribution.json`. Extract the outer GitHub artifact -wrapper and upload the individual skill ZIPs inside. No npm/marketplace publication -is implied. +If a maintainer supplies the four individual ZIPs directly, start at step 2 below. +No npm/marketplace publication is implied by the CI artifact. | Upload ZIP | Purpose | | ------------------------ | ----------------------------------------------------------- | @@ -37,6 +38,8 @@ is implied. | `context-web-verify.zip` | Read-only validity and freshness checks | | `context-web-query.zip` | Read-only repository questions and source retrieval | +## 2. Install them in the Claude account you will use + Enable **Code execution and file creation** in Claude's capabilities settings. Go to **Customize → Skills → Add skill → Upload skill**, upload each desired ZIP and enable it. Team/Enterprise policies may require administrator @@ -46,6 +49,10 @@ instructions and resources, following [the custom-skill format][create-skills]. Do not upload the source `skills-web/` folder, an npm tarball, the whole repository ZIP or the Claude Code plugin as a web skill. +Start a fresh chat after enabling the skills. If you use a different Claude +account, repeat installation in that account. Installing skills does not upload +Headlamp source and does not require an OpenAI key. + Consumer requirements: code execution, Python 3.9+ and **already available Node 22.14+ (22.x) or 24.x**. Each skill independently includes compiled SHContext, locked production JavaScript dependencies and their licenses. No npm, Git, @@ -56,7 +63,7 @@ are rejected until tested. Anthropic does not guarantee these exact runtime versions in every web session. Web network access varies by settings, so a GitHub URL alone is not source access [as documented][skills-overview]. -## Headlamp example +## 3. Prepare and attach a small Headlamp source ZIP Attach a source ZIP with `frontend/src/lib/router` present. GitHub's **Code → Download ZIP** can work within the bounds below. For a smaller trial, someone @@ -67,17 +74,72 @@ dependencies or build outputs: git -C /path/to/headlamp archive --format=zip --prefix=headlamp-source/ --output=/absolute/headlamp-router.zip HEAD frontend/src/lib/router LICENSE ``` -After enabling `context-web-build`, attach that ZIP and send: +That `git archive HEAD` command includes **committed files only**. It will not +include uncommitted edits when preparing an update. For the current working copy, +create a small ZIP from your local Headlamp checkout with Python 3 instead: + +```sh +cd /path/to/headlamp +python3 - <<'PYTHON' +from pathlib import Path +from zipfile import ZipFile, ZIP_DEFLATED +root = Path.cwd() +source = root / 'frontend/src/lib/router' +output = root.parent / 'headlamp-router-working-copy.zip' +assert source.is_dir() and not source.is_symlink(), 'Run from the Headlamp checkout' +assert not output.exists(), 'Choose a new output filename' +files = [] +for path in sorted(source.rglob('*')): + assert not path.is_symlink(), 'Do not archive symlinks' + parts = path.relative_to(source).parts + if any(part in {'context', '.shcontext', '.git', 'node_modules'} for part in parts): + continue + if path.is_file(): + files.append(path) +assert files, 'No source files found' +license_file = root / 'LICENSE' +assert not license_file.is_symlink(), 'Do not archive a linked license' +if license_file.is_file(): + files.append(license_file) +with ZipFile(output, 'x', ZIP_DEFLATED) as archive: + for path in files: + archive.write(path, 'headlamp-source/' + path.relative_to(root).as_posix()) +print(output) +PYTHON +``` + +Use a new filename for each snapshot. The working-copy script preserves +`frontend/src/lib/router` beneath the wrapper; the web helper still validates all +transport limits. On Windows use an installed Python 3 interpreter (`python` +where appropriate), or ask your IDE agent to create the equivalent source-only +ZIP with the same paths and exclusions. For a browser-only user, obtain this +small archive from a collaborator/IDE; a full GitHub Download ZIP may be too large. +Do not rename a rejected file to disguise its type. + +In a **new Claude chat**, attach the **source ZIP to the message**, not to +Customize → Skills. Seeing it in the attachment list is distinct from installing +a skill. + +## 4. Generate, verify and download context + +Send this prompt: ```text Use context-web-build on the attached Headlamp source ZIP. -Generate context for frontend/src/lib/router. Inspect the archive layout first. +Inspect the archive layout first and identify its wrapper directory. +Generate context for frontend/src/lib/router. Analyze the prepared evidence yourself, submit each structured draft, finalize and verify it, then return the downloadable context ZIP. State coverage, uncertainty and dependencies outside this scope. Do not request an OpenAI key or install the repository's dependencies. ``` +Claude should load `context-web-build`, check runtime compatibility, validate +and open the archive, then run prepare → Claude-authored drafts → submit → +finalize → verify → export. A statement that it read the source is not enough: +request the actual downloadable archive and final freshness/coverage result. +Stop on an incompatible runtime or rejected input instead of fabricating output. + The selected folder becomes the analysis root. `context/CONTEXT.md` describes it; descendants are mirrored below `context/`. To resolve Markdown source links locally, extract `context/` beside that selected source root, producing @@ -93,8 +155,31 @@ and evidence, which may be confidential for private repositories. It contains no source files, drafts, API keys or private chat/session state. Export is a separate step after fresh verification; the ZIP is not a source backup. -## Update or ask questions in another chat +## 5. Ask questions and verify without changing context + +Attach the source ZIP and the exported context ZIP, then ask: + +```text +Use context-web-query on these two archives for frontend/src/lib/router. +Where are route URLs created? Check freshness, inspect current source and cite +paths and line ranges. Identify dependencies outside this scope. +Do not regenerate context. +``` +For a standalone check: + +```text +Use context-web-verify on the attached source and context ZIPs for +frontend/src/lib/router. Report freshness, coverage and findings. +Do not regenerate or edit anything. +``` + +Query results are source/symbol/text retrieval, not guaranteed complete answers. +If context is stale or missing, label that result and any current-source findings. + +## 6. Refresh after code changes, including in a new chat + +Create a new source snapshot that actually includes your edits (see step 3). Attach **both** the updated source ZIP and the previous exported context ZIP. Keep the same selected subfolder; archive wrapper names may change. @@ -111,14 +196,25 @@ affected summaries. Old context can be valid but stale against updated source. An unchanged update requests zero drafts. Reuse does not depend on an earlier chat's filesystem. A changed selected subfolder requires a new build. -For read-only verification, attach both ZIPs and ask “Use context-web-verify to -check freshness and coverage; do not regenerate.” For questions ask “Use -context-web-query: where is route creation handled? Inspect current source, -give references and flag stale context.” Retrieval uses paths, symbols, text and -bounded dependency traversal, with no silent regeneration. Structural validation, -matching hashes and model review do not prove explanation accuracy. +Download the new context ZIP and use it as the previous output next time. Keep +the original until verification succeeds. The old and new archive wrappers may +differ, but the selected subfolder must match. Structural validation, matching +hashes and model review do not prove explanation accuracy. + +## 7. Troubleshoot uploads and interrupted work -## Bounds and failures +| Symptom | Next action | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Skill ZIP rejected | Use the individual packaged ZIP, not the outer artifact or repository ZIP. Current packages have 29 files, portable paths and no nested archives. | +| Source ZIP rejected or too large | Produce the router-only source ZIP in step 3; selecting a subfolder does not reduce the size of an uploaded whole-repository ZIP. | +| Skill does not activate | Enable it in this account, start a new chat and mention its exact name. Check organization policy if upload is unavailable. | +| Claude asks for an OpenAI key | Explicitly select `context-web-build`/`context-web-update`; the native web workflow must not switch to the API CLI. | +| Runtime unavailable | Report the observed Node/Python version and stop; the package does not supply a Node executable. | +| Context missing in a new chat | Attach both source and the complete previous output ZIP, including manifest/cache. Earlier chat files are not guaranteed available. | +| Usage limit or execution reset | Keep downloaded output; resume later with source plus previous context. Unpublished drafts may be lost and must not be claimed finalized. | +| Edited or invalid previous context | Preserve it and inspect the ownership error. Do not hand-edit a manifest to force reuse. | + +### Bounds and failure states | ZIP transport bound | Limit | | -------------------------- | ------------------------------------------------ | @@ -171,3 +267,20 @@ exercise build/update/reimport/query and failure states. These do not replace The upload contains at most 200 files and no nested archives. Compiled JavaScript bundles include locked production dependencies; their licenses and version inventory remain separate resources. No extraction or installation is required. + +## Package the web skills yourself (maintainers) + +In a prepared SHContext checkout, run: + +```sh +npm ci +npm run package:web -- /absolute/new/shcontext-web-distribution +``` + +Build requirements are Git, Node 22.14+ on the 22 line or Node 24, npm 10+, and Python 3.9+. +Use a new output directory outside the tool checkout; add `--require-clean` for +review/release artifacts. The packager uses `python` on Windows and `python3` +elsewhere. Consumers install the generated ZIPs, not the raw `skills-web/` source +folders. This producer setup is separate from uploading skills into Claude. + +For the other environments, return to [the host chooser](usage.md). diff --git a/docs/skills.md b/docs/skills.md index 55bda4b..b3a82d7 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -1,5 +1,8 @@ # Install the SHContext workflows +For a first installation, follow [the terminal walkthrough](claude-code.md). +The [environment chooser](usage.md) also links Antigravity and Claude Code cloud. + This guide covers the existing Claude Code/local distribution. For uploaded repositories in Claude web chat, use the separate [web skill ZIPs](claude-web.md). @@ -55,16 +58,16 @@ For a local checkout, launch Claude Code and run these **inside its session**: /plugin install shcontext@shcontext-workflows ``` -After this change is merged, the shared GitHub installation is: +The shared GitHub installation is: ```text /plugin marketplace add HarshPopat23/SHContext /plugin install shcontext@shcontext-workflows ``` -Before merge, append `#feat/claude-native-context` to the GitHub marketplace -source to install the PR branch. To pin a reviewed version, append `#` -instead. The local route tests exactly the files in that checkout. The marketplace +To pin a reviewed version, append `#` to the GitHub marketplace source. +For a preview, use the actual reviewed PR branch rather than assuming main +contains it. The local route tests exactly the files in that checkout. The marketplace entry uses `source: "./"`, relative to the marketplace root, and the plugin discovers the five directories under `skills/`. Neither file declares MCP servers or hooks. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..1d3e712 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,70 @@ +# Use SHContext in your coding assistant + +Choose the guide for the place where your agent actually runs. A local path in +one environment does not give another environment access to the repository. + +| Environment | Start here | Source input | Generation | +| ---------------------------------------- | ------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------- | +| Claude Code terminal | [Terminal walkthrough](claude-code.md) | Local checkout | Five local plugin skills; active Claude session writes drafts | +| Claude web chat at claude.ai | [Web chat walkthrough](claude-web.md) | Uploaded source ZIP | Four uploaded web skills; active chat writes drafts | +| Antigravity IDE | [Antigravity walkthrough](antigravity.md) | Local checkout available to the agent | Explicit local host protocol; agent writes drafts | +| Claude Code on the web at claude.ai/code | [Cloud session walkthrough](claude-code-cloud.md) | Checkout in its cloud environment | Explicit host protocol in that environment | + +**Claude web chat and Claude Code on the web are different products/surfaces.** +The ZIP upload route belongs to ordinary Claude chat. A terminal plugin installed +on your computer is not automatically available to a cloud Code session. + +## What every walkthrough produces + +For the Headlamp example, choose `headlamp/frontend/src/lib/router` as the +analysis root. The output lives at +`headlamp/frontend/src/lib/router/context/CONTEXT.md`, with child folders mirrored +under `context/` when present. The web workflow returns this tree inside a ZIP; +local workflows write it beside the selected source. + +Each summary includes purpose, files, interfaces, dependencies, tests, source +references and uncertainty. The manifest/report/cache under `context/.shcontext/` +are part of the output: keep them for freshness checks and incremental reuse. +They are different from private operational state under a target's root +`.shcontext/` or an outside session directory. + +Start small. Selecting the router folder does not establish the behavior of +Headlamp's entire authentication system. JS/TS structure is supported; other code +can be inventory-only. Unresolved imports remain unconfirmed, including `.js` +imports whose only possible target is a `.ts` file. See +[language and resolution limits](code-structure.md). + +## Keys, accounts and cost + +All four guides use `provider.id: host`. The active assistant analyzes evidence; +SHContext handles scanning, validation, freshness and publication. This requires +no separate OpenAI/Anthropic generation key, but consumes the host account's +normal allowance. A model label such as `antigravity-session` is declared +provenance, not authentication or an exact detected model ID. + +The plain `build` and `update` CLI commands are the separate optional OpenAI API +workflow. Host generation instead uses `prepare` → agent-authored JSON → `submit` +→ `finalize`. Do not substitute an API command when following these guides. +Verify and query are local operations. Account policy, permissions and rate limits +still apply; SHContext does not supply unlimited model access. + +## Support and evidence + +| Surface | Evidence and limits | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | +| Claude Code plugin | Official CLI installation checks and local host-protocol exercises; see [skill evaluation](skill-evaluation.md) | +| Claude web chat | Actual uploaded-skill/source, build/download/new-chat update and failure checks; see [web acceptance](claude-web-acceptance.md) | +| Antigravity | Documented use of the shared local protocol; no dedicated Antigravity plugin or actual IDE acceptance result is claimed | +| Claude Code cloud | Environment-specific setup instructions; no actual cloud-session acceptance result is claimed | + +Review citations against source. A `fresh` result validates integrity and source +identity, not every explanation or runtime behavior. Generated context is not +committed automatically; decide with your team whether reviewed context belongs +in Git. Do not commit secrets or private session state. + +## Further reading + +- [Host protocol and bounds](host-generation.md) +- [Configuration and scanner exclusions](scanner.md) +- [Freshness and recovery](verification.md) +- [Optional unattended API generation](generation.md) diff --git a/skills/README.md b/skills/README.md index 65e79b3..4fff9ed 100644 --- a/skills/README.md +++ b/skills/README.md @@ -9,5 +9,9 @@ through the root `.claude-plugin/plugin.json`; the marketplace is Follow the [installation, requirements and failure guide](../docs/skills.md). Prepare a complete SHContext checkout with `npm ci` and expose its absolute path as `SHCONTEXT_HOME`. Plugin installation alone does not install that runtime. -Build/changed update use the configured OpenAI provider; verify/query and the -controlled benchmark are local. MCP is not required for these CLI workflows. +Build/changed update use the active Claude Code host by default with no separate +model API key; OpenAI automation is optional. Verify/query and the controlled +benchmark are local. MCP is not required for these CLI workflows. + +Start with [the terminal walkthrough](../docs/claude-code.md), or use +[the environment chooser](../docs/usage.md) for Claude web chat and Antigravity.