docs(install): refactor of installation guides

docs/guides/README.md

@@ -2,18 +2,17 @@
 
 Practical how-to documentation for fullsend, organized by audience. For design documents and architectural context, see [docs/problems/](../problems/), [docs/ADRs/](../ADRs/), and [docs/architecture.md](../architecture.md).
 
-Structure decided in [ADR 0023](../ADRs/0023-user-documentation-structure.md).
-
 ## Getting started
 
 Guides for onboarding organizations and configuring GitHub — the first thing most users need.
 
-- [Installing fullsend](getting-started/installation.md) — End-user setup (inference + GitHub) and all-in-one admin install
-- [Setting up with pre-provisioned infrastructure](getting-started/github-setup.md) — GitHub-only setup when GCP infrastructure is already provisioned
+- [Getting Inference](getting-started/getting-inference.md)
+- [Configuring GitHub](getting-started/configuring-github.md)
+- [Organization Mode](getting-started/org-mode.md)
 
 ## Infrastructure
 
-Guides for platform operators who deploy and manage the GCP-side infrastructure (token mint, WIF, secrets).
+Advanced guides for platform operators who deploy and manage the GCP-side infrastructure (token mint, WIF, secrets).
 
 - [Mint service administration](infrastructure/mint-administration.md) — Deploying and managing the token mint Cloud Function
 - [Infrastructure reference](infrastructure/infrastructure-reference.md) — Token mint, WIF, and secrets deployment details

docs/guides/dev/cli-internals.md

@@ -71,7 +71,7 @@ The `admin install` command performs all setup in a single invocation. The `mint
 | Phase 4: WIF provisioning | `fullsend inference provision` | GCP project (inference): `roles/iam.workloadIdentityPoolAdmin`, `roles/resourcemanager.projectIamAdmin` |
 | Phases 5-7: GitHub setup + enrollment | `fullsend github setup` | GitHub only |
 
-The typical handoff: a GCP admin runs `mint deploy`, `mint enroll`, and `inference provision`, then passes the mint URL and WIF provider resource name to a GitHub maintainer who runs `github setup --mint-url=... --inference-wif-provider=...`. See [Setting up with pre-provisioned infrastructure](../getting-started/github-setup.md).
+The typical handoff: a GCP admin runs `mint deploy`, `mint enroll`, and `inference provision`, then passes the mint URL and WIF provider resource name to a GitHub maintainer who runs `github setup --mint-url=... --inference-wif-provider=...`. See [Setting up with pre-provisioned infrastructure](../../reference/github-setup.md).
 
 ### Token Resolution Chain
 
@@ -530,8 +530,8 @@ var executableFiles = map[string]struct{}{
 ## See Also
 
 - [Local Development](local-dev.md) — Development environment setup
-- [Installing fullsend](../getting-started/installation.md) — End-user setup and all-in-one admin install
-- [Setting up with pre-provisioned infrastructure](../getting-started/github-setup.md) — GitHub-only setup guide
+- [Installing fullsend](../../reference/installation.md) — End-user setup and all-in-one admin install
+- [Setting up with pre-provisioned infrastructure](../../reference/github-setup.md) — GitHub-only setup guide
 - [Mint service administration](../infrastructure/mint-administration.md) — Deploying and managing the token mint
 - [Infrastructure Reference](../infrastructure/infrastructure-reference.md) — Infrastructure details
 - [Customizing Agents](../user/customizing-agents.md) — User customization guide

docs/guides/getting-started/README.md

@@ -0,0 +1,8 @@
+# README
+
+This section contains easy and to the point guides to help you
+set up Fullsend. These are intended to be read in a certain order:
+
+- [Getting Inference](getting-inference.md)
+- [Configuring GitHub](configuring-github.md)
+- [Organization Mode](org-mode.md)

docs/guides/getting-started/configuring-github.md

@@ -0,0 +1,53 @@
+# Configuring GitHub For Fullsend
+
+The goal of this document is that you configure Fullsend for your GitHub repository.
+
+## Prerequisites
+
+* You have your WIF provider URL from [Getting Inference](getting-inference.md).
+* Download the latest [fullsend](https://github.com/fullsend-ai/fullsend/releases) CLI.
+* Download the latest [gh](https://cli.github.com/) CLI and authenticate with it.
+
+## Installing GitHub Applications
+
+In order to use Fullsend install the following applications to your organization
+and provide them permissions to the repository you want to install Fullsend to.
+
+| Role | Installation URL |
+|------|-----------------|
+| fullsend | <https://github.com/apps/fullsend-ai-fullsend/installations/new> |
+| triage | <https://github.com/apps/fullsend-ai-triage/installations/new> |
+| coder | <https://github.com/apps/fullsend-ai-coder/installations/new> |
+| review | <https://github.com/apps/fullsend-ai-review/installations/new> |
+| retro | <https://github.com/apps/fullsend-ai-retro/installations/new> |
+| prioritize | <https://github.com/apps/fullsend-ai-prioritize/installations/new> |
+
+## Configuring GitHub
+
+Run the command:
+
+```bash
+fullsend github setup <org>/<repo> \
+  --inference-project "<gcp-project>" \
+  --inference-wif-provider "<wif-provider-url>"
+```
+
+Where `<org>/<repo>` refers to the GitHub organization and repository you want to enable inference
+for, `<gcp-project>` is your GCP project name, and `<wif-provider-url>` is the WIF Provider URL
+created at [Getting Inference](getting-inference.md).
+
+The command creates files, secrets and variables in your repository.
+
+## Testing Fullsend
+
+After installing open a new issue or comment `/fs-triage` in an open issue. Then visit the
+Actions tab to see the Fullsend workflow in action. In some minutes the
+`fullsend-ai-triage` bot should post a comment in the issue.
+
+## Next steps
+
+* Read [Organization installation mode](org-mode.md) to learn how to share GCP project with other repositories
+within your GitHub organization.
+* Read the [Default Agents](../../agents/README.md) section to learn about the default agents Fullsend
+ships with.
+* Explore other sections of this documentation for more information.

docs/guides/getting-started/getting-inference.md

@@ -0,0 +1,78 @@
+# Getting Inference For Fullsend
+
+The goal of this document is that you acquire a WIF provider URL to pass to the next step
+of the process ([Configuring GitHub](configuring-github.md)).
+
+Currently Fullsend only supports GCP Vertex AI inference using Workload Identity Federation (WIF).
+WIF grants short-lived tokens to requesters that meet certain requirements. In the case of Fullsend
+these requirements are to provide an OIDC Token signed by GitHub with their origin (org, repository
+and other details). If the WIF finds the request valid, it provides a short lived token.
+
+You may need to create a new GCP project or reuse one. The output of this process is a WIF provider
+URL resembling:
+
+```text
+projects/<number>/locations/global/workloadIdentityPools/<pool-name>/providers/<provider-name>
+```
+
+Where `<number>` is the number of the GCP project. This URL may be provided to you if there is
+someone handling GCP projects in your organization. Otherwise you may need to create a GCP
+project and configure it yourself.
+
+## Prerequisites
+
+* Download the latest [gcloud](https://docs.cloud.google.com/sdk/docs/install-sdk) CLI and
+authenticate with it.
+* Download the latest [fullsend](https://github.com/fullsend-ai/fullsend/releases) CLI.
+
+## Create a GCP project
+
+Head over to [GCloud](https://console.cloud.google.com/) and create a new project. Then
+enable the following APIs:
+
+```bash
+gcloud services enable \
+  iam.googleapis.com \
+  cloudresourcemanager.googleapis.com \
+  aiplatform.googleapis.com \
+  --project="$GCP_PROJECT"
+```
+
+**Note**: enable Anthropic's models Opus and Sonnet as well.
+
+Then give yourself the roles `roles/iam.workloadIdentityPoolAdmin`
+and `roles/resourcemanager.projectIamAdmin`.
+
+## Configure inference in your GCP project
+
+Run the command to configure provision for your GitHub repository:
+
+```bash
+fullsend inference provision <org>/<repo> --project <gcp-project>
+```
+
+Where `<org>/<repo>` refers to the GitHub organization and repository you want to enable inference
+for, and `<gcp-project>` is your GCP project name. The output resembles:
+
+```text
+⚡ fullsend <version>
+  Autonomous agentic development for GitHub organizations
+
+→ Provisioning WIF for repo-scoped inference: <org>/<repo>
+
+  • Provisioning WIF infrastructure
+  ✓ WIF infrastructure ready
+
+    WIF Provider: projects/<number>/locations/global/workloadIdentityPools/fullsend-inference/providers/gh-<org>-<repo>
+
+    Pass this value to the GitHub setup command:
+      fullsend github setup <org>/<repo> \
+        --inference-project=<gcp-project> \
+        --inference-wif-provider=projects/<number>/locations/global/workloadIdentityPools/fullsend-inference/providers/gh-<org>-<repo>
+```
+
+The important piece of information is the `WIF Provider` which you need to pass to the next step.
+
+## Next steps
+
+Head over to [Configuring GitHub](configuring-github.md) to use your WIF provider URL.

docs/guides/getting-started/org-mode.md

@@ -0,0 +1,93 @@
+# Installing Fullsend in Organization Mode
+
+The goal of this document is that you install Fullsend for your whole
+GitHub organization, so different repositories share inference and infrastructure.
+
+**Note**: this document assumes you already read and used [Getting Inference](getting-inference.md)
+and [Configuring GitHub](configuring-github.md). If that is not the case, read those guides first.
+
+## Differences With Repository Installation
+
+When you install Fullsend in Organization Mode there are a few key differences:
+
+* `fullsend inference provision` is executed once for the whole organization.
+* GitHub workflows are executed in a `.fullsend` repository within the organization.
+* Individual repositories need to be enrolled to be able to execute Fullsend.
+
+
+## Getting Inference For The Organization
+
+Similar to the command ran at [Getting Inference](getting-inference.md) you need to run:
+
+```bash
+fullsend inference provision <org> --project <gcp-project>
+```
+
+Where `<org>` is the GitHub organization and `<gcp-project>` is your GCP project.
+
+```text
+⚡ fullsend <version>
+  Autonomous agentic development for GitHub organizations
+
+→ Provisioning WIF for org-scoped inference: <org>
+
+  • Provisioning WIF infrastructure
+  ✓ WIF infrastructure ready
+
+    WIF Provider: projects/<number>/locations/global/workloadIdentityPools/fullsend-inference/providers/github-oidc
+
+    Pass this value to the GitHub setup command:
+      fullsend github setup <org> \
+        --inference-project=<gcp-project> \
+        --inference-wif-provider=projects/<number>/locations/global/workloadIdentityPools/fullsend-inference/providers/github-oidc
+```
+
+Note down the `WIF Provider` URL which is used in the next step to configure the organization.
+
+## Configure GitHub Apps
+
+If you previously ran the [Configuring GitHub](configuring-github.md) guide the Fullsend apps you
+installed are configured just for a single repository. Change the permissions so they can access
+all repositories or `.fullsend` (not created yet) and any other repository you want to enable
+Fullsend for.
+
+## Configure GitHub
+
+Now similar to the command executed on [Configuring GitHub](configuring-github.md), execute:
+
+```bash
+fullsend github setup <org> \
+  --inference-project <gcp-project> \
+  --inference-wif-provider <wif-provider-url>
+```
+
+Where `<org>` is the GitHub organization, `<gcp-project>` is your GCP project and `<wif-provider-url>` is
+the URL from the previous step.
+
+This command creates a `.fullsend` repository in your organization and starts a workflow that enrolls
+repositories if needed.
+
+
+## Enroll Repositories
+
+After installing enroll repositories by running:
+
+```bash
+fullsend github enroll <org> <repo> [<repo>...]
+```
+
+This changes the `config.yaml` present in the `.fullsend` repository and that starts a workflow there.
+The workflow adds or removes the `.github/workflows/fullsend.yaml` of the repositories.
+
+## Testing Fullsend
+
+After merging the `.github/workflows/fullsend.yaml` workflow in the enrolled repositories, open
+a new issue or comment `/fs-triage` in an issue of one of the enrolled repositories to see Fullsend in
+action.
+
+
+## Next Steps
+
+* Read the [Default Agents](../../agents/README.md) section to learn about the default agents Fullsend
+ships with.
+* Explore other sections of this documentation for more information.

docs/guides/infrastructure/infrastructure-reference.md

@@ -1,6 +1,6 @@
 # Infrastructure Reference
 
-This guide provides implementation details for fullsend's infrastructure components: the OIDC token mint, Workload Identity Federation (WIF), and secrets deployment. For basic installation instructions, see the [Installation Guide](../getting-started/installation.md).
+This guide provides implementation details for fullsend's infrastructure components: the OIDC token mint, Workload Identity Federation (WIF), and secrets deployment. For basic installation instructions, see the [Installation Guide](../../reference/installation.md).
 
 ## Token Mint (OIDC) — GCF Cloud Function
 
@@ -185,7 +185,7 @@ During installation, the GCF provisioner creates:
 
 ## GitHub Secrets & Variables Deployment
 
-> Individual values can be updated with `fullsend github set <target> <key> <value>`. See [Setting up with pre-provisioned infrastructure](../getting-started/github-setup.md) for the full GitHub management guide.
+> Individual values can be updated with `fullsend github set <target> <key> <value>`. See [Setting up with pre-provisioned infrastructure](../../reference/github-setup.md) for the full GitHub management guide.
 
 Secrets and variables are deployed at different scopes depending on the installation mode.
 
@@ -303,7 +303,7 @@ The GCF provisioner avoids redundant Cloud Function deployments by computing a S
 
 ## See Also
 
-- [Installation Guide](../getting-started/installation.md) — Setup instructions (end-user and all-in-one)
+- [Installation Guide](../../reference/installation.md) — Setup instructions (end-user and all-in-one)
 - [Mint service administration](mint-administration.md) — Deploying and managing the token mint
-- [Setting up with pre-provisioned infrastructure](../getting-started/github-setup.md) — GitHub-only setup guide
+- [Setting up with pre-provisioned infrastructure](../../reference/github-setup.md) — GitHub-only setup guide
 - [Local Development](../dev/local-dev.md) — Developer setup

docs/guides/infrastructure/mint-administration.md

@@ -2,7 +2,7 @@
 
 This guide covers deploying and managing the fullsend token mint Cloud Function. The mint is the OIDC token exchange service that lets GitHub Actions workflows authenticate as GitHub Apps — it is infrastructure that serves all enrolled organizations and repositories.
 
-> **This guide is for platform operators** who deploy, manage, or troubleshoot the token mint Cloud Function. If you are an end user setting up fullsend for your organization, see [Installing fullsend](../getting-started/installation.md) instead — the mint is typically deployed once by a platform operator, and organizations are enrolled as needed.
+> **This guide is for platform operators** who deploy, manage, or troubleshoot the token mint Cloud Function. If you are an end user setting up fullsend for your organization, see [Installing fullsend](../../reference/installation.md) instead — the mint is typically deployed once by a platform operator, and organizations are enrolled as needed.
 
 ## Hosted mint
 
@@ -127,7 +127,7 @@ fullsend mint enroll acme-corp --project="$GCP_PROJECT"
 fullsend mint enroll acme-corp/my-repo --project="$GCP_PROJECT"
 ```
 
-Enrollment does **not** grant Agent Platform (inference) access — use `fullsend inference provision` separately after enrollment. See [Installing fullsend](../getting-started/installation.md) for the end-user inference setup path.
+Enrollment does **not** grant Agent Platform (inference) access — use `fullsend inference provision` separately after enrollment. See [Installing fullsend](../../reference/installation.md) for the end-user inference setup path.
 
 ### Flags
 
@@ -414,7 +414,7 @@ gcloud functions logs read fullsend-mint \
 
 ## See Also
 
-- [Installing fullsend](../getting-started/installation.md) — End-user setup (inference + GitHub)
-- [Setting up with pre-provisioned infrastructure](../getting-started/github-setup.md) — GitHub-only setup when GCP is already provisioned
+- [Installing fullsend](../../reference/installation.md) — End-user setup (inference + GitHub)
+- [Setting up with pre-provisioned infrastructure](../../reference/github-setup.md) — GitHub-only setup when GCP is already provisioned
 - [Infrastructure Reference](infrastructure-reference.md) — Token mint, WIF, and secrets deployment details
 - [CLI Internals](../dev/cli-internals.md) — Command structure and implementation details

docs/guides/infrastructure/private-repositories.md

@@ -193,7 +193,7 @@ Not all private repos are equal. A repo containing open-source code that happens
 
 ## See also
 
-- [Installation guide](../getting-started/installation.md) — Initial fullsend setup
+- [Installation guide](../../reference/installation.md) — Initial fullsend setup
 - [Customizing agents](../user/customizing-agents.md) — Harness configuration and layered overrides
 - [Security threat model](../../problems/security-threat-model.md) — Threat priority and defense considerations
 - [#1189](https://github.com/fullsend-ai/fullsend/issues/1189) — Retro agent private content leak risk

docs/guides/user/bugfix-workflow.md

@@ -1,6 +1,6 @@
 # Bugfix workflow
 
-How fullsend handles a bug report from issue creation to merged fix, end to end. This guide is for developers working in a repo where fullsend is [installed and enrolled](../getting-started/installation.md).
+How fullsend handles a bug report from issue creation to merged fix, end to end. This guide is for developers working in a repo where fullsend is [installed and enrolled](../../reference/installation.md).
 
 ## Overview
 
@@ -167,5 +167,5 @@ Fullsend does not lock you out. The labels are the state machine, and you have f
 
 - [ADR 0002](../../ADRs/0002-initial-fullsend-design.md) — initial fullsend design (full workflow specification)
 - [Architecture overview](../../architecture.md) — component vocabulary and execution stack
-- [Installing fullsend](../getting-started/installation.md) — prerequisite: admin setup guide
+- [Installing fullsend](../../reference/installation.md) — prerequisite: admin setup guide
 - [Security threat model](../../problems/security-threat-model.md) — how fullsend thinks about security

docs/guides/user/customizing-agents.md

@@ -298,6 +298,6 @@ my-repo/
 
 ## See Also
 
-- [Installation Guide](../getting-started/installation.md) - Initial setup
+- [Installation Guide](../../reference/installation.md) - Initial setup
 - [Bugfix Workflow](bugfix-workflow.md) - How agents work together
 - [ADR 0035: Layered Content Resolution](../../ADRs/0035-layered-content-resolution.md)

docs/guides/user/running-agents-locally.md

@@ -240,7 +240,7 @@ fullsend run triage \
 ```
 
 Status comment behavior is configured via `status_notifications` in
-`config.yaml`. See the [installation guide](../getting-started/installation.md#status-notifications).
+`config.yaml`. See the [installation guide](../../reference/installation.md#status-notifications).
 
 ## Simulating Fullsend's real customization layers
 

docs/reference/README.md

@@ -0,0 +1,7 @@
+# README
+
+This section contains highly detailed documents that describe
+the software itself: commands, APIs, schemas, etc.
+
+- [Installation](installation.md)
+- [GitHub Setup](github-setup.md)