From f897ae4a0ef60ff26617e8ee543be861cb38e830 Mon Sep 17 00:00:00 2001 From: dbpolito Date: Fri, 3 Apr 2026 11:05:44 -0300 Subject: [PATCH] docs: consolidate installation into getting-started - Add GitHub CLI prerequisites to README and getting-started documentation - Remove standalone installation doc and fold content into getting-started - Add logo configuration to web astro config - Update sidebar navigation to remove separate installation entry - Add sections for override capabilities and adapter support status --- README.md | 4 ++ packages/web/astro.config.mjs | 6 ++- .../src/content/docs/docs/getting-started.mdx | 20 +++++++- packages/web/src/content/docs/docs/index.mdx | 3 +- .../src/content/docs/docs/installation.mdx | 47 ------------------- 5 files changed, 29 insertions(+), 51 deletions(-) delete mode 100644 packages/web/src/content/docs/docs/installation.mdx diff --git a/README.md b/README.md index 2d2dce8..e8c3398 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,10 @@ Kompass keeps AI coding agents on course with token-efficient, composable workfl - Structured tools keep workflows grounded in repo and GitHub state: `changes_load`, `command_expansion` (resolve a slash command and return the expanded prompt for immediate delegation), `pr_load`, `pr_sync`, `ticket_load`, `ticket_sync`. - Reusable command-template components live in `packages/core/components/` and are documented in the components reference. +## Prerequisites + +- **GitHub CLI** (`gh`) must be installed and authenticated. Kompass uses `gh` for all GitHub operations (PRs, issues, reviews). Install from [cli.github.com](https://cli.github.com/) and run `gh auth login`. + ## Installation For OpenCode, add the adapter package to your config: diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs index 55cff69..fe97d3d 100644 --- a/packages/web/astro.config.mjs +++ b/packages/web/astro.config.mjs @@ -8,6 +8,11 @@ export default defineConfig({ title: "Kompass Docs", description: "Guided workflows for AI coding agents.", favicon: "/kompass-icon.png", + logo: { + src: "./public/kompass-icon.png", + alt: "Kompass", + replacesTitle: false + }, social: { github: "https://github.com/kompassdev/kompass" }, @@ -15,7 +20,6 @@ export default defineConfig({ sidebar: [ "docs", "docs/getting-started", - "docs/installation", { label: "Concepts", items: ["docs/concepts/modes", "docs/concepts/architecture"] diff --git a/packages/web/src/content/docs/docs/getting-started.mdx b/packages/web/src/content/docs/docs/getting-started.mdx index 1c96ea9..b99685f 100644 --- a/packages/web/src/content/docs/docs/getting-started.mdx +++ b/packages/web/src/content/docs/docs/getting-started.mdx @@ -3,6 +3,10 @@ title: Getting Started description: Install Kompass for OpenCode and start using the bundled workflow system. --- +## Prerequisites + +- **GitHub CLI** (`gh`) must be installed and authenticated. Kompass uses `gh` for all GitHub operations (PRs, issues, reviews). Install from [cli.github.com](https://cli.github.com/) and run `gh auth login`. + ## Quick start Kompass currently ships an OpenCode adapter package: `@kompassdev/opencode`. @@ -15,7 +19,7 @@ Add it to your OpenCode config: } ``` -## Add optional project config +## Optional project config If you want to customize commands, agents, tools, or defaults for a project, add one project override file. @@ -34,6 +38,15 @@ To start from the published base config: curl -fsSL https://raw.githubusercontent.com/kompassdev/kompass/main/kompass.jsonc -o .opencode/kompass.jsonc ``` +### What the override can control + +- shared validation guidance +- enabled commands and custom templates +- agent enablement and prompt overrides +- tool enablement and tool-name remapping +- component path overrides +- default base branch and adapter settings + ## Start using workflows Once the plugin is installed, you can use commands such as: @@ -59,6 +72,11 @@ opencode export - shared workflow logic stays in the Kompass package rather than your project repo - project overrides are layered on top of the bundled base config +## Current adapter support + +- **OpenCode**: supported now +- **Claude Code**: planned, not shipped yet + ## Next steps - Read [`OpenCode`](/docs/adapters/opencode/) for adapter-specific behavior. diff --git a/packages/web/src/content/docs/docs/index.mdx b/packages/web/src/content/docs/docs/index.mdx index bc57c91..eec7b94 100644 --- a/packages/web/src/content/docs/docs/index.mdx +++ b/packages/web/src/content/docs/docs/index.mdx @@ -24,8 +24,7 @@ Kompass is a shared workflow toolkit for AI coding agents. ## What to read next -- Start with [`Getting Started`](/docs/getting-started/) for the fastest path. -- Use [`Installation`](/docs/installation/) for config setup and override locations. +- Start with [`Getting Started`](/docs/getting-started/) for installation and first steps. - See [`OpenCode`](/docs/adapters/opencode/) for the current supported adapter. - Use [`Commands`](/docs/reference/commands/) and [`Tools`](/docs/reference/tools/) as the main reference. - See [`Workspace Development`](/docs/workspace/development/) if you are contributing to this repo. diff --git a/packages/web/src/content/docs/docs/installation.mdx b/packages/web/src/content/docs/docs/installation.mdx deleted file mode 100644 index 7674768..0000000 --- a/packages/web/src/content/docs/docs/installation.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Installation -description: Install Kompass, publish optional config, and understand override precedence. ---- - -## OpenCode installation - -Kompass is currently distributed for OpenCode as `@kompassdev/opencode`. - -Configure OpenCode to load the adapter: - -```json -{ - "plugin": ["@kompassdev/opencode"] -} -``` - -## Optional project override - -Project config is optional. If present, Kompass loads the first file that exists from this list: - -1. `.opencode/kompass.jsonc` -2. `.opencode/kompass.json` -3. `kompass.jsonc` -4. `kompass.json` - -The recommended file is `.opencode/kompass.jsonc`. - -## Bootstrap from the published base config - -```bash -curl -fsSL https://raw.githubusercontent.com/kompassdev/kompass/main/kompass.jsonc -o .opencode/kompass.jsonc -``` - -## What the override can control - -- shared validation guidance -- enabled commands and custom templates -- agent enablement and prompt overrides -- tool enablement and tool-name remapping -- component path overrides -- default base branch and adapter settings - -## Current adapter support - -- **OpenCode**: supported now -- **Claude Code**: planned, not shipped yet