Polish public repository hygiene

.github/ISSUE_TEMPLATE/config.yml

@@ -1,4 +1,4 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
 contact_links:
   - name: Security-sensitive report
     url: https://github.com/AmeerJ97/grok-cli-vertex/security/advisories/new

.github/pull_request_template.md

@@ -8,8 +8,10 @@
 
 ## Verification
 
+- [ ] `bun run format`
 - [ ] `bun run typecheck`
 - [ ] `bun run lint`
+- [ ] `bun run test`
 - [ ] `bun run build:binary`
 - [ ] Relevant tests:
 - [ ] Manual smoke, if applicable:

CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+Thanks for helping improve `grok-cli-vertex`. This fork is Vertex-first, with
+the inherited native xAI path kept for compatibility and comparison.
+
+## Project Direction
+
+- Prefer Vertex AI behavior unless a change is explicitly about the native xAI
+  fallback or upstream compatibility.
+- Keep backend-specific behavior behind `src/providers/` and the
+  `GrokProviderAdapter` contract.
+- Use typed capability errors for unsupported provider features instead of
+  letting unsupported endpoints fail late.
+- Keep public docs honest that this project is community-built and is not an
+  official xAI or Google product.
+
+## Local Setup
+
+```bash
+bun install
+bun run typecheck
+bun run test
+bun run build
+```
+
+For changes that touch runtime behavior, also run the narrow test file while
+iterating:
+
+```bash
+bunx --bun vitest run path/to/file.test.ts
+```
+
+Vertex mode requires Google Application Default Credentials and a project id:
+
+```bash
+gcloud auth application-default login
+GROK_PROVIDER=vertex GROK_VERTEX_PROJECT_ID=my-gcp-project bun run dev
+```
+
+Native xAI fallback testing still requires `GROK_API_KEY`.
+
+## Pull Requests
+
+- Start from current `main`.
+- Keep PRs focused and avoid mixing code, docs, dependency, and release changes
+  unless they are part of one behavior change.
+- Include the commands you actually ran in the PR body.
+- Add or update tests for provider behavior, storage migrations, tool loops,
+  CLI flags, and user-visible error handling.
+- Update README, CLI help, or docs when behavior changes.
+- Call out any provider-specific risk, especially when changing shared agent or
+  UI code that can affect both Vertex and native xAI modes.
+
+## Issue Triage
+
+Useful reports include:
+
+- OS and terminal emulator
+- Bun version
+- Provider mode (`vertex` or `xai`)
+- Relevant non-secret environment variables
+- Reproduction steps and logs
+
+Do not include API keys, Google Cloud project secrets, Telegram tokens, session
+transcripts, or private repository data in public issues.
+
+## Branch Hygiene
+
+Merged PR branches are normally deleted on GitHub. Local branches may remain as
+private working references, but new public polish or maintenance work should use
+a fresh branch from current `main`.

README.md

@@ -1,8 +1,9 @@
 # grok-cli-vertex: a Vertex AI-focused Grok coding agent
 
-[CI](https://github.com/AmeerJ97/grok-cli-vertex/actions/workflows/typecheck.yml)
+[![CI](https://github.com/AmeerJ97/grok-cli-vertex/actions/workflows/typecheck.yml/badge.svg)](https://github.com/AmeerJ97/grok-cli-vertex/actions/workflows/typecheck.yml)
+[![Security Scan](https://github.com/AmeerJ97/grok-cli-vertex/actions/workflows/security.yml/badge.svg)](https://github.com/AmeerJ97/grok-cli-vertex/actions/workflows/security.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [npm package inherited from upstream](https://www.npmjs.com/package/grok-dev)
-[License: MIT](./LICENSE)
 [TypeScript](https://www.typescriptlang.org/)
 [Bun](https://bun.sh/)
 
@@ -18,6 +19,16 @@ Some native xAI paths remain because they are inherited from upstream and useful
 - [Demo script](docs/demo-script.md) — a short walkthrough for showing the project without exposing private credentials.
 - [Maintainer runbook](docs/maintainer-runbook.md) — local checks, PR policy, release flow, and troubleshooting.
 - [Roadmap](docs/roadmap.md) — near-term hardening work and explicit non-goals.
+- [Contributing](CONTRIBUTING.md) — local setup, PR expectations, provider-boundary guardrails, and issue triage.
+- [Security policy](SECURITY.md) — private vulnerability reporting and supported security scope.
+- [Public repo audit](docs/public-repo-audit.md) — current branch/repo hygiene notes and public polish follow-ups.
+
+## Project status
+
+This repository is public and early-maintainer-led. The default branch is kept
+Vertex-first, CI-verified, and dependency-monitored with Dependabot. Public
+issues are appropriate for reproducible bugs and focused feature requests;
+security-sensitive reports should use GitHub private vulnerability reporting.
 
 ## Upstream attribution
 
@@ -33,14 +44,19 @@ official distribution of the upstream project.
 curl -fsSL https://raw.githubusercontent.com/AmeerJ97/grok-cli-vertex/main/install.sh | bash
 ```
 
+The script-installed command is `grok-vertex` and the binary is installed under
+`~/.grok-vertex/bin`. This intentionally avoids clobbering the official x.ai
+CLI installed by `curl -fsSL https://x.ai/cli/install.sh | bash`, which owns
+`~/.grok/bin/grok` and the `grok` command.
+
 **Local source install** (requires Bun on PATH):
 
 ```bash
 bun install
 bun run build
 mkdir -p ~/.local/bin
-printf '#!/usr/bin/env bash\nexec %q/dist/index.js "$@"\n' "$PWD" > ~/.local/bin/grok
-chmod +x ~/.local/bin/grok
+printf '#!/usr/bin/env bash\nexec %q/dist/index.js "$@"\n' "$PWD" > ~/.local/bin/grok-vertex
+chmod +x ~/.local/bin/grok-vertex
 ```
 
 Do not use `npm install -g grok-dev` or `bun add -g grok-dev` for this Vertex
@@ -50,10 +66,10 @@ inherited npm package can be xAI-only and may ignore saved Vertex settings.
 **Self-management** (script-installed only):
 
 ```bash
-grok update
-grok uninstall
-grok uninstall --dry-run
-grok uninstall --keep-config
+grok-vertex update
+grok-vertex uninstall
+grok-vertex uninstall --dry-run
+grok-vertex uninstall --keep-config
 ```
 
 **Prerequisites:** a Google Cloud project with Vertex AI enabled, Application Default Credentials for local auth, and a modern terminal emulator for the interactive OpenTUI experience. Native xAI mode still requires a **Grok API key** from [x.ai](https://x.ai). Headless `--prompt` mode does not depend on terminal UI support. If you want host desktop automation via the built-in computer sub-agent, also enable **Accessibility** permission for your terminal app on macOS.
@@ -65,9 +81,12 @@ grok uninstall --keep-config
 **Interactive (default)** — launches the OpenTUI coding agent:
 
 ```bash
-grok
+grok-vertex
 ```
 
+If you also use the official x.ai CLI, reserve `grok` for that CLI and use
+`grok-vertex` for this fork.
+
 ### Supported terminals
 
 For the most reliable interactive OpenTUI experience, use a modern terminal emulator. We currently document and recommend:
@@ -82,18 +101,18 @@ Other modern terminals may work, but these are the terminal apps we currently re
 **Pick a project directory:**
 
 ```bash
-grok -d /path/to/your/repo
+grok-vertex -d /path/to/your/repo
 ```
 
 **Headless** — one prompt, then exit (scripts, CI, automation):
 
 ```bash
-grok --prompt "run the test suite and summarize failures"
-grok -p "show me package.json" --directory /path/to/project
-grok --prompt "refactor X" --max-tool-rounds 30
-grok --prompt "summarize the repo state" --format json
-grok --prompt "review the repo overnight" --batch-api
-grok --verify
+grok-vertex --prompt "run the test suite and summarize failures"
+grok-vertex -p "show me package.json" --directory /path/to/project
+grok-vertex --prompt "refactor X" --max-tool-rounds 30
+grok-vertex --prompt "summarize the repo state" --format json
+grok-vertex --prompt "review the repo overnight" --batch-api
+grok-vertex --verify
 ```
 
 `--batch-api` is inherited from the native xAI backend and is not available on
@@ -105,16 +124,16 @@ For a reproducible walkthrough, see [docs/demo-script.md](docs/demo-script.md).
 **Continue a saved session:**
 
 ```bash
-grok --session latest
-grok -s <session-id>
+grok-vertex --session latest
+grok-vertex -s <session-id>
 ```
 
 Works in interactive mode too—same flag.
 
 **Structured headless output:**
 
 ```bash
-grok --prompt "summarize the repo state" --format json
+grok-vertex --prompt "summarize the repo state" --format json
 ```
 
 `--format json` emits a newline-delimited JSON event stream instead of the
@@ -128,8 +147,8 @@ Grok ships a built-in `**computer**` sub-agent backed by `[agent-desktop](https:
 Ask for it in natural language, for example:
 
 ```bash
-grok "Use the computer sub-agent to take a screenshot of my host desktop and tell me what is open."
-grok "Use the computer sub-agent to launch Google Chrome, snapshot the UI, and tell me which refs correspond to the address bar and tabs."
+grok-vertex "Use the computer sub-agent to take a screenshot of my host desktop and tell me what is open."
+grok-vertex "Use the computer sub-agent to launch Google Chrome, snapshot the UI, and tell me which refs correspond to the address bar and tabs."
 ```
 
 Notes:
@@ -158,7 +177,7 @@ and updates CHANGELOG.md from the latest merged commits.
 Recurring schedules require the background daemon:
 
 ```bash
-grok daemon --background
+grok-vertex daemon --background
 ```
 
 Use `/schedule` in the TUI to browse saved schedules. One-time schedules start
@@ -168,13 +187,13 @@ daemon is active.
 **List Grok models and pricing hints:**
 
 ```bash
-grok models
+grok-vertex models
 ```
 
 **Pass an opening message without another prompt:**
 
 ```bash
-grok fix the flaky test in src/foo.test.ts
+grok-vertex fix the flaky test in src/foo.test.ts
 ```
 
 Media generation commands are inherited from the xAI backend. They are capability
@@ -222,7 +241,7 @@ GROK_API_KEY=your_key_here
 **CLI once:**
 
 ```bash
-grok -k your_key_here
+grok-vertex -k your_key_here
 ```
 
 **Saved in user settings** — `~/.grok/user-settings.json`:
@@ -273,10 +292,10 @@ This fork routes Grok traffic through **Google Cloud Vertex AI** as the preferre
 
 ```bash
 # CLI flag
-grok --provider vertex
+grok-vertex --provider vertex
 
 # Or via env var
-GROK_PROVIDER=vertex GROK_VERTEX_PROJECT_ID=my-gcp-project grok
+GROK_PROVIDER=vertex GROK_VERTEX_PROJECT_ID=my-gcp-project grok-vertex
 
 # Or save in ~/.grok/user-settings.json
 {
@@ -359,7 +378,7 @@ Send a voice note or audio attachment in Telegram and Grok will transcribe it wi
 Optional headless flow when you do not want the TUI open:
 
 ```bash
-grok telegram-bridge
+grok-vertex telegram-bridge
 ```
 
 Treat the bot token like a password.
@@ -432,8 +451,8 @@ All settings are saved in `~/.grok/user-settings.json` (user) and `.grok/setting
 Run `**/verify`** in the TUI or `**--verify`** on the CLI to verify your app locally:
 
 ```bash
-grok --verify
-grok -d /path/to/your/app --verify
+grok-vertex --verify
+grok-vertex -d /path/to/your/app --verify
 ```
 
 The agent inspects your project, figures out how to build and run it, spins up a sandbox, and produces a verification report with screenshots and video evidence. Works with any app type.
@@ -481,7 +500,7 @@ uses Google ADC and `GROK_VERTEX_PROJECT_ID`.
 export GROK_API_KEY=your_key_here
 
 # Or save to user settings
-grok -k your_key_here
+grok-vertex -k your_key_here
 ```
 
 Get native xAI API keys from [x.ai](https://x.ai).
@@ -563,6 +582,9 @@ bun run typecheck
 bun run lint
 ```
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full local setup, PR checklist,
+provider-boundary expectations, and issue-triage guidance.
+
 ---
 
 ## Trademarks

SECURITY.md

@@ -0,0 +1,51 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes target the current `main` branch and the latest release tag, when
+a release exists. Older local builds and unpublished development branches are
+not supported as separate security maintenance lines.
+
+## Reporting A Vulnerability
+
+Please report suspected vulnerabilities through GitHub private vulnerability
+reporting:
+
+https://github.com/AmeerJ97/grok-cli-vertex/security/advisories/new
+
+Use a public issue only for non-sensitive hardening requests. Do not post API
+keys, Google Cloud project secrets, Telegram bot tokens, session transcripts,
+or private repository contents in public issues.
+
+## Useful Report Details
+
+Include as much non-secret detail as possible:
+
+- Affected version, commit, or install method
+- Provider mode (`vertex` or native `xai`)
+- Operating system and terminal environment
+- Reproduction steps
+- Expected impact and whether credentials are required
+- Relevant logs with secrets redacted
+
+## Scope
+
+In scope:
+
+- Credential handling in Vertex and native xAI configuration paths
+- Local file, shell, MCP, LSP, hook, and sandbox behavior
+- Install, update, release, and dependency lifecycle behavior
+- Telegram remote-control authentication and pairing behavior
+
+Out of scope:
+
+- Vulnerabilities in upstream cloud provider services
+- Social engineering or phishing against maintainers
+- Denial-of-service reports that require unrealistic local resource exhaustion
+- Reports that depend on exposing intentionally provided local credentials
+
+## Disclosure Expectations
+
+Please give maintainers a reasonable chance to investigate before public
+disclosure. The project is community-maintained, so response times may vary, but
+security-sensitive reports will be handled separately from public issue triage.