brass-runtime 1.16.0 → 1.17.0

package/docs/agent-global-usage.md

@@ -0,0 +1,180 @@
+# Brass Agent global usage and workspace discovery
+
+`brass-agent` is meant to run from **any project**, not only from the `brass-runtime` checkout.
+
+The runtime checkout is where the CLI is built. The workspace is whichever project you run the CLI against.
+
+```txt
+brass-runtime checkout
+  -> builds/installs brass-agent
+
+any other project
+  -> run brass-agent here
+  -> agent discovers that project as the workspace
+```
+
+## Install the CLI globally for local development
+
+From the `brass-runtime` checkout:
+
+```bash
+npm run agent:link
+```
+
+This runs:
+
+```bash
+npm run build
+npm link
+```
+
+After that, `brass-agent` should be available on your `PATH` from any folder:
+
+```bash
+brass-agent --where
+brass-agent --doctor
+brass-agent --preset inspect
+```
+
+To remove the global CLI link/install:
+
+```bash
+npm run agent:unlink
+```
+
+This command is idempotent: it is okay if the package is not currently linked or installed globally.
+
+## Use it in another project
+
+```bash
+cd /path/to/another-project
+brass-agent --where
+brass-agent --init --init-profile google
+brass-agent --doctor
+brass-agent --preset inspect
+```
+
+`--where` prints the workspace root the agent will use.
+
+## Workspace auto-discovery
+
+By default, `brass-agent` treats `--cwd` as a **starting directory**, not necessarily the final workspace root.
+
+It searches upward for the nearest workspace marker:
+
+```txt
+.brass-agent.json
+brass-agent.config.json
+package.json
+pnpm-workspace.yaml
+turbo.json
+nx.json
+.git
+```
+
+Examples:
+
+```bash
+cd /repo/packages/api/src/routes
+brass-agent --where
+```
+
+May resolve to:
+
+```txt
+workspace: /repo/packages/api
+marker: package.json
+```
+
+Then config discovery, env-file loading, package-manager detection, validation commands, context discovery, and patch application all use that resolved workspace.
+
+## Disable workspace discovery
+
+If you intentionally want the exact current folder:
+
+```bash
+brass-agent --no-discover-workspace --where
+```
+
+or:
+
+```bash
+brass-agent --no-discover-workspace --cwd ./some/subdir "inspect this folder"
+```
+
+## VS Code with a global CLI
+
+If the CLI is globally linked, the VS Code extension can just use:
+
+```json
+{
+  "brassAgent.command": "brass-agent"
+}
+```
+
+To install the extension and write that setting into the current workspace:
+
+```bash
+npm run agent:vscode:install:global
+```
+
+That script now links the CLI globally first, then installs the VS Code extension with `brassAgent.command = "brass-agent"`.
+
+To remove the global VS Code setup and the global CLI link/install:
+
+```bash
+npm run agent:vscode:uninstall:global
+```
+
+To force a full clean global reinstall:
+
+```bash
+npm run agent:vscode:reinstall:global
+```
+
+For a different workspace:
+
+```bash
+node scripts/install-vscode-extension.mjs \
+  --use-global-command \
+  --workspace /path/to/another-project
+```
+
+This is the best setup when you want one local Brass Agent installation and many workspaces.
+
+## Absolute local CLI path
+
+For development of the agent itself, the installer may write an absolute command:
+
+```json
+{
+  "brassAgent.command": "/path/to/brass-runtime/dist/agent/cli/main.cjs"
+}
+```
+
+That works too, but it is less portable than `brass-agent`.
+
+## Recommended daily workflow
+
+Once globally linked:
+
+```bash
+cd /path/to/project
+brass-agent --where
+brass-agent --doctor
+brass-agent --preset inspect
+brass-agent --preset typecheck
+brass-agent "fix the failing tests"
+```
+
+From VS Code:
+
+```txt
+Brass Agent -> Chat -> /inspect
+Brass Agent -> Chat -> /fix-tests
+```
+
+
+## VS Code auto-discovery
+
+The VS Code extension can now use `brassAgent.command = "auto"` and prefer its bundled CLI, so you can open any repo and use Brass Agent without linking the CLI globally. See [VS Code auto-discovery](./agent-vscode-auto-discovery.md).

package/docs/agent-init.md

@@ -0,0 +1,109 @@
+# Brass Agent init
+
+> For the end-to-end setup flow, see [Brass Agent install and configure](./agent-install-and-configure.md).
+
+`brass-agent --init` bootstraps a workspace for local Brass Agent usage without adding CI or release automation.
+
+It creates these files in `--cwd`:
+
+- `.brass-agent.json` — project-local policy/config.
+- `brass-agent.batch.json` — sample multi-goal workflow for `--batch-file`.
+- `.env.example` — example LLM environment variables; real secrets must stay outside git.
+- `BRASS_AGENT.md` — short local usage note for the repository.
+
+The command never writes real secrets and does not overwrite existing files unless `--force` or `--init-force` is passed.
+
+## Basic usage
+
+```bash
+brass-agent --init
+brass-agent --doctor
+```
+
+For development from the repository:
+
+```bash
+npm run agent:init
+npm run agent:init:dry-run
+```
+
+Initialize a different workspace:
+
+```bash
+brass-agent --init --cwd ../my-project
+```
+
+Preview without writing:
+
+```bash
+brass-agent --init --init-dry-run
+```
+
+Overwrite previously generated files:
+
+```bash
+brass-agent --init --force
+```
+
+## Profiles
+
+`--init-profile` selects how much LLM config is written.
+
+```bash
+brass-agent --init --init-profile default
+brass-agent --init --init-profile google
+brass-agent --init --init-profile openai-compatible
+brass-agent --init --init-profile fake
+```
+
+Profiles:
+
+- `default` leaves `config.llm` unset, so the CLI keeps its normal provider auto-detection and can fall back to fake mode.
+- `google` writes Gemini config using `GEMINI_API_KEY` and `gemini-2.5-flash`.
+- `openai-compatible` writes `/chat/completions` config using `BRASS_LLM_API_KEY` and `BRASS_LLM_ENDPOINT`.
+- `fake` writes an offline fake provider config for smoke tests.
+
+`--init-provider` is an alias for provider-oriented profiles:
+
+```bash
+brass-agent --init --init-provider google
+brass-agent --init --init-provider auto
+```
+
+`auto` maps to the `default` profile.
+
+## Generated config shape
+
+The generated `.brass-agent.json` is intentionally conservative:
+
+- default mode is `propose`;
+- approval mode is `auto`;
+- patch apply requires approval;
+- redaction is enabled;
+- context discovery excludes `.env*`, private keys, `node_modules`, build outputs, and `secrets/**`;
+- rollback safety is enabled for generated patches;
+- shell permissions inherit the built-in validation allowlist and explicitly deny dangerous commands like `rm *`, `git push *`, `git reset *`, and `git clean *`.
+
+The initializer also inspects `package.json` when present:
+
+- package manager is inferred from `packageManager` or lockfiles;
+- `includeTypecheck` is enabled only when common typecheck scripts exist;
+- `includeLint` is enabled only when common lint scripts exist;
+- the sample batch file includes only presets that make sense for the scripts it finds.
+
+## Recommended flow
+
+```bash
+brass-agent --init
+brass-agent --doctor
+brass-agent --preset inspect
+brass-agent --batch-file brass-agent.batch.json
+```
+
+For VS Code, run the local installer after init:
+
+```bash
+npm run agent:vscode:install
+```
+
+or install the `.vsix` manually from `extensions/vscode-brass-agent`.