@gonkagate/claude-code-setup 0.2.0

package/docs/security.md

@@ -0,0 +1,38 @@
+# Security Notes
+
+## Secret entry
+
+The recommended install flow is interactive:
+
+```bash
+npx @gonkagate/claude-code
+```
+
+The setup-style alias `npx @gonkagate/claude-code-setup` runs the same interactive installer.
+
+The installer asks for the API key through a hidden prompt. It intentionally rejects `--api-key ...` arguments so secrets do not end up in shell history or process lists.
+
+## Where the key is stored
+
+Claude Code reads environment variables from its settings files. That means the GonkaGate API key is stored in the Claude Code settings file you choose:
+
+- `~/.claude/settings.json`
+- `.claude/settings.local.json`
+
+This repo does not write `.env` files and does not modify shell startup files. It also writes the target settings file with owner-only permissions and locks backup files down to owner-only permissions too.
+
+## Local scope hygiene
+
+If you choose `local` scope inside a git repository, the installer first checks whether `.claude/settings.local.json` is already tracked by git. If it is already tracked, the installer offers to either stop tracking that file and continue local setup, or switch to `user` scope instead of writing a secret into a still-tracked file.
+
+If you choose the stop-tracking recovery path, the installer runs `git rm --cached` for `.claude/settings.local.json`, keeps the file in your working tree, and adds local ignore rules before writing the secret-bearing settings file. That stages the file removal from version control, which is usually the right outcome for a repo-local secrets file.
+
+For untracked local installs, the installer adds `.claude/settings.local.json` and its timestamped backup pattern to the repo's `.git/info/exclude` before writing the file so secret-bearing local settings do not immediately show up in git.
+
+If your team already manages ignores another way, that is still fine. The important rule is that `.claude/settings.local.json` must stay uncommitted.
+
+The installer also refuses local setup through a symlinked path component on the way to `.claude/settings.local.json`, including a symlinked `.claude` directory or a symlinked local settings file. That prevents a repository from redirecting the secret-bearing write to some other tracked or non-local location.
+
+## Backup behavior
+
+Before overwriting an existing target settings file, the installer creates a timestamped backup next to it. If something looks wrong afterward, restore from that backup and rerun the installer.

package/docs/show-and-tell-discussion.md

@@ -0,0 +1,80 @@
+Hi everyone,
+
+## What we built
+
+We made `@gonkagate/claude-code`, a small open source installer for people who want to use Claude Code with Gonka through GonkaGate.
+
+It solves a boring problem on purpose. Most people do not want to export env vars by hand, edit shell profiles, or create a `.env` file just to get Claude Code talking to a gateway.
+
+So we kept the flow short. You run one command, enter a `gp-...` API key in a hidden prompt, choose a model, choose a scope, and then Claude Code is ready to use.
+
+- Repo: https://github.com/GonkaGate/gonkagate-claude-code
+- Website: https://gonkagate.com/en
+
+## Why we built it
+
+The gateway setup itself is not especially hard. The annoying part is first-time setup in Claude Code.
+
+That is the part people still end up wiring by hand more often than they should. If someone already has a `gp-...` API key, getting to a normal `claude` workflow should not involve touching shell config.
+
+## Quick start
+
+```bash
+npx @gonkagate/claude-code
+```
+
+## What the installer does
+
+- Asks for a hidden `gp-...` API key
+- Lets you choose a supported model from the curated list
+- Writes Claude Code settings in `user` or `local` scope
+- Leaves unrelated Claude Code settings alone
+- Creates a backup before replacing an existing settings file
+- Does not touch shell profiles or create `.env` files
+- Helps keep local secret-bearing settings out of git during project-local setup
+
+## Gateway host and transport
+
+Under the hood, the installer points Claude Code at the GonkaGate gateway host:
+
+`https://api.gonkagate.com`
+
+For Claude Code, that means the Anthropic-compatible endpoint on that host.
+
+The same GonkaGate host also serves OpenAI-compatible `/v1/*` routes for OpenAI-style clients, but this installer is specifically for Claude Code. It sets up the Claude-side Anthropic flow and leaves the OpenAI path alone.
+
+## Models right now
+
+We are keeping the public Claude Code model list small for now, but one detail is worth making explicit.
+
+GonkaGate does not decide which models exist on Gonka Network. As an OpenAI-compatible provider and an Anthropic-compatible provider, we serve what is actually available in the network.
+
+So the model list in this installer is not a custom catalog we fully control. It is a curated list of network-available models that we have patched into this Claude Code flow.
+
+Right now there is one supported option: `qwen3-235b`.
+
+As new models show up in Gonka Network, we will patch the utility and add them here.
+
+## Demo
+
+[![See the installer in action](https://raw.githubusercontent.com/GonkaGate/gonkagate-claude-code/main/.github/assets/gonkagate-claude-code-demo.gif)](https://raw.githubusercontent.com/GonkaGate/gonkagate-claude-code/main/.github/assets/gonkagate-claude-code-demo.mp4)
+
+## More links
+
+- npm package: https://www.npmjs.com/package/@gonkagate/claude-code
+- README: https://github.com/GonkaGate/gonkagate-claude-code#readme
+- Troubleshooting: https://github.com/GonkaGate/gonkagate-claude-code/blob/main/docs/troubleshooting.md
+- Security notes: https://github.com/GonkaGate/gonkagate-claude-code/blob/main/docs/security.md
+- How it works: https://github.com/GonkaGate/gonkagate-claude-code/blob/main/docs/how-it-works.md
+- Changelog: https://github.com/GonkaGate/gonkagate-claude-code/blob/main/CHANGELOG.md
+- Issues and feedback: https://github.com/GonkaGate/gonkagate-claude-code/issues
+
+## Feedback
+
+If you are using Gonka with local coding tools, the feedback we would care about most is:
+
+- Which developer tools we should support next
+- Where the onboarding still feels rough or confusing
+- Which models you would actually want to use in this Claude Code flow as they appear on Gonka Network
+
+If anything in the setup still feels awkward in practice, that is what we want to hear about. We will keep adjusting it based on what people actually run into.

package/docs/troubleshooting.md

@@ -0,0 +1,106 @@
+# Troubleshooting
+
+## `/status` still shows Anthropic
+
+If Claude Code still shows direct Anthropic auth or the wrong upstream after install:
+
+1. Run `claude auth logout`
+2. Restart `claude`
+3. Run `/status` again
+
+The installer writes Claude Code settings, but an existing direct login can still be what you are seeing until you log out once.
+
+## Model unavailable
+
+This installer writes the selected model from its curated GonkaGate-supported registry.
+
+Today that curated list contains one option:
+
+- `qwen3-235b` -> `qwen/qwen3-235b-a22b-instruct-2507-fp8`
+
+If that model is unavailable, the likely cause is a backend deployment or model availability mismatch. This installer does not expose custom base URL or arbitrary custom model overrides, so the right next step is GonkaGate support or the backend troubleshooting docs in `gonka-proxy`.
+
+## Model removed from the curated list later
+
+If a model disappears from the curated list in a future release of this installer:
+
+1. Rerun the installer
+2. Choose from the current curated list, or pass a current key with `--model <model-key>`
+
+Manual edits to force an old or unsupported model id are outside the supported setup flow.
+
+## Want to switch models
+
+Rerun the installer and choose a different curated model when prompted.
+
+You can also skip the interactive model prompt with:
+
+```bash
+npx @gonkagate/claude-code --model <model-key>
+```
+
+The setup-style alias accepts the same options:
+
+```bash
+npx @gonkagate/claude-code-setup --model <model-key>
+```
+
+Only current curated keys are accepted.
+
+## Corrupted settings file
+
+If the target settings file contains invalid JSON, the installer stops without overwriting it.
+
+Restore from the timestamped backup next to the settings file, or fix the JSON manually, then rerun the installer.
+
+## Want repo-only setup
+
+Rerun the installer and choose `local` scope. That writes `.claude/settings.local.json` in the current repository instead of editing your global `~/.claude/settings.json`.
+
+## `.claude/settings.local.json` is already tracked by git
+
+For `local` scope, the installer now detects when `.claude/settings.local.json` is already a tracked file in the repository and offers a recovery choice.
+
+The recommended option is to stop tracking that file and continue. The installer will:
+
+- run `git rm --cached` for `.claude/settings.local.json`
+- keep the file in your working tree
+- add local exclude entries so the file stays uncommitted going forward
+
+If that repository intentionally versions `.claude/settings.local.json`, choose `user` scope instead.
+
+You can still do the stop-tracking step manually if you prefer:
+
+```bash
+git rm --cached -- .claude/settings.local.json
+```
+
+## Local install refused because the target path uses a symlink
+
+For `local` scope, the installer now rejects a symlinked path component anywhere on the way to `.claude/settings.local.json`, including a symlinked `.claude` directory or a symlinked `.claude/settings.local.json`.
+
+That safety check prevents a repository from redirecting your API key into some other location that git might track.
+
+Replace the symlink with a real `.claude` directory, then rerun the installer.
+
+## Manual settings edits
+
+Manual edits to the Claude Code settings file are possible, but they are outside the supported public install flow for this repo.
+
+If you want to get back to a supported state, rerun the installer instead of hand-editing model ids or gateway values.
+
+## Want to undo the install
+
+You have two safe options:
+
+1. Restore the backup created by the installer.
+2. Remove the GonkaGate-managed keys from the target settings file:
+   - `ANTHROPIC_BASE_URL`
+   - `ANTHROPIC_AUTH_TOKEN`
+   - `ANTHROPIC_MODEL`
+   - `ANTHROPIC_DEFAULT_OPUS_MODEL`
+   - `ANTHROPIC_DEFAULT_SONNET_MODEL`
+   - `ANTHROPIC_DEFAULT_HAIKU_MODEL`
+   - `CLAUDE_CODE_SUBAGENT_MODEL`
+
+If you previously removed `ANTHROPIC_API_KEY`, add back whatever auth method you actually want before relaunching Claude Code.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@gonkagate/claude-code-setup",
+  "version": "0.2.0",
+  "description": "Setup-style alias for the GonkaGate Claude Code installer.",
+  "homepage": "https://github.com/GonkaGate/gonkagate-claude-code#readme",
+  "bugs": {
+    "url": "https://github.com/GonkaGate/gonkagate-claude-code/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GonkaGate/gonkagate-claude-code.git"
+  },
+  "type": "module",
+  "bin": {
+    "claude-code-setup": "bin/gonkagate-claude-code.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "gonkagate",
+    "gonka",
+    "gonka ai",
+    "gonka-network",
+    "gonka blockchain",
+    "gonka-api",
+    "gonka gateway",
+    "claude-code",
+    "claude code",
+    "claude-code-setup",
+    "setup"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
+    "commander": "^13.1.0",
+    "write-file-atomic": "^5.0.1"
+  }
+}