From 3ab825ae984f59f7f68483d03a390c24ef3b19df Mon Sep 17 00:00:00 2001 From: Hector Martinez Date: Wed, 10 Jun 2026 16:55:22 +0200 Subject: [PATCH] docs(install): refactor of installation guides Signed-off-by: Hector Martinez --- docs/guides/README.md | 9 +- docs/guides/dev/cli-internals.md | 6 +- docs/guides/getting-started/README.md | 8 ++ .../getting-started/configuring-github.md | 53 +++++++++++ .../getting-started/getting-inference.md | 78 ++++++++++++++++ docs/guides/getting-started/org-mode.md | 93 +++++++++++++++++++ .../infrastructure-reference.md | 8 +- .../infrastructure/mint-administration.md | 8 +- .../infrastructure/private-repositories.md | 2 +- docs/guides/user/bugfix-workflow.md | 4 +- docs/guides/user/customizing-agents.md | 2 +- docs/guides/user/running-agents-locally.md | 2 +- docs/reference/README.md | 7 ++ .../github-setup.md | 10 +- .../installation.md | 18 ++-- web/docs/README.md | 2 +- 16 files changed, 274 insertions(+), 36 deletions(-) create mode 100644 docs/guides/getting-started/README.md create mode 100644 docs/guides/getting-started/configuring-github.md create mode 100644 docs/guides/getting-started/getting-inference.md create mode 100644 docs/guides/getting-started/org-mode.md create mode 100644 docs/reference/README.md rename docs/{guides/getting-started => reference}/github-setup.md (97%) rename docs/{guides/getting-started => reference}/installation.md (96%) diff --git a/docs/guides/README.md b/docs/guides/README.md index 5987135b98..057aa34292 100644 --- a/docs/guides/README.md +++ b/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 diff --git a/docs/guides/dev/cli-internals.md b/docs/guides/dev/cli-internals.md index c964086fc8..91ab200ede 100644 --- a/docs/guides/dev/cli-internals.md +++ b/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 diff --git a/docs/guides/getting-started/README.md b/docs/guides/getting-started/README.md new file mode 100644 index 0000000000..e79060c99b --- /dev/null +++ b/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) diff --git a/docs/guides/getting-started/configuring-github.md b/docs/guides/getting-started/configuring-github.md new file mode 100644 index 0000000000..60225d3175 --- /dev/null +++ b/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 | | +| triage | | +| coder | | +| review | | +| retro | | +| prioritize | | + +## Configuring GitHub + +Run the command: + +```bash +fullsend github setup / \ + --inference-project "" \ + --inference-wif-provider "" +``` + +Where `/` refers to the GitHub organization and repository you want to enable inference +for, `` is your GCP project name, and `` 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. diff --git a/docs/guides/getting-started/getting-inference.md b/docs/guides/getting-started/getting-inference.md new file mode 100644 index 0000000000..b31dc0c0aa --- /dev/null +++ b/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//locations/global/workloadIdentityPools//providers/ +``` + +Where `` 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 / --project +``` + +Where `/` refers to the GitHub organization and repository you want to enable inference +for, and `` is your GCP project name. The output resembles: + +```text +⚡ fullsend + Autonomous agentic development for GitHub organizations + +→ Provisioning WIF for repo-scoped inference: / + + • Provisioning WIF infrastructure + ✓ WIF infrastructure ready + + WIF Provider: projects//locations/global/workloadIdentityPools/fullsend-inference/providers/gh-- + + Pass this value to the GitHub setup command: + fullsend github setup / \ + --inference-project= \ + --inference-wif-provider=projects//locations/global/workloadIdentityPools/fullsend-inference/providers/gh-- +``` + +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. diff --git a/docs/guides/getting-started/org-mode.md b/docs/guides/getting-started/org-mode.md new file mode 100644 index 0000000000..c40c7e4f71 --- /dev/null +++ b/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 --project +``` + +Where `` is the GitHub organization and `` is your GCP project. + +```text +⚡ fullsend + Autonomous agentic development for GitHub organizations + +→ Provisioning WIF for org-scoped inference: + + • Provisioning WIF infrastructure + ✓ WIF infrastructure ready + + WIF Provider: projects//locations/global/workloadIdentityPools/fullsend-inference/providers/github-oidc + + Pass this value to the GitHub setup command: + fullsend github setup \ + --inference-project= \ + --inference-wif-provider=projects//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 \ + --inference-project \ + --inference-wif-provider +``` + +Where `` is the GitHub organization, `` is your GCP project and `` 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 [...] +``` + +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. diff --git a/docs/guides/infrastructure/infrastructure-reference.md b/docs/guides/infrastructure/infrastructure-reference.md index abe116f439..4b43275c72 100644 --- a/docs/guides/infrastructure/infrastructure-reference.md +++ b/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 `. 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 `. 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 diff --git a/docs/guides/infrastructure/mint-administration.md b/docs/guides/infrastructure/mint-administration.md index 6a2cb5f688..b541c71873 100644 --- a/docs/guides/infrastructure/mint-administration.md +++ b/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 diff --git a/docs/guides/infrastructure/private-repositories.md b/docs/guides/infrastructure/private-repositories.md index 01a2f1f374..79fba19e90 100644 --- a/docs/guides/infrastructure/private-repositories.md +++ b/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 diff --git a/docs/guides/user/bugfix-workflow.md b/docs/guides/user/bugfix-workflow.md index a2afc6cc98..b5ec7594e5 100644 --- a/docs/guides/user/bugfix-workflow.md +++ b/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 diff --git a/docs/guides/user/customizing-agents.md b/docs/guides/user/customizing-agents.md index 4891f96257..ac2b03bb5f 100644 --- a/docs/guides/user/customizing-agents.md +++ b/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) diff --git a/docs/guides/user/running-agents-locally.md b/docs/guides/user/running-agents-locally.md index 52fcfcf306..105eebc7c1 100644 --- a/docs/guides/user/running-agents-locally.md +++ b/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 diff --git a/docs/reference/README.md b/docs/reference/README.md new file mode 100644 index 0000000000..9fd2842f5d --- /dev/null +++ b/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) diff --git a/docs/guides/getting-started/github-setup.md b/docs/reference/github-setup.md similarity index 97% rename from docs/guides/getting-started/github-setup.md rename to docs/reference/github-setup.md index a973d0a81c..9cbb7068bd 100644 --- a/docs/guides/getting-started/github-setup.md +++ b/docs/reference/github-setup.md @@ -12,7 +12,7 @@ For the all-in-one setup that provisions both GCP and GitHub in a single command - **GitHub CLI** (`gh`) authenticated — the installer runs a preflight check and tells you which scopes are missing. When prompted, run the `gh auth refresh -s ` command it suggests. - **fullsend CLI** — download the latest binary from [GitHub Releases](https://github.com/fullsend-ai/fullsend/releases) - **From your Mint service provider admin** (currently GCP-managed; other providers planned): - - Token mint URL (`--mint-url`) — the HTTPS endpoint of the deployed mint Cloud Function. If you are using the fullsend hosted mint, the URL is `https://fullsend-mint-gljhbkcloq-uc.a.run.app` (see [Hosted mint](../infrastructure/mint-administration.md#hosted-mint)). + - Token mint URL (`--mint-url`) — the HTTPS endpoint of the deployed mint Cloud Function. If you are using the fullsend hosted mint, the URL is `https://fullsend-mint-gljhbkcloq-uc.a.run.app` (see [Hosted mint](../guides/infrastructure/mint-administration.md#hosted-mint)). - **From your Inference provider admin** (currently GCP Agent Platform, formerly Vertex AI; other providers planned): - GCP project ID (`--inference-project`) — the project where Agent Platform is enabled (e.g., `my-gcp-project`) - WIF provider resource name (`--inference-wif-provider`) — the full resource path, e.g., `projects/123456789/locations/global/workloadIdentityPools/fullsend-inference/providers/github-oidc` (note: the leading number is the GCP **project number**, not the project ID string; your GCP admin can find it with `gcloud projects describe --format='value(projectNumber)'`) @@ -26,7 +26,7 @@ This guide covers the **GitHub Maintainer** role. The GCP-side work (token mint | Role | What they do | Covered in | |------|-------------|------------| -| **GCP Admin (Mint)** | Deploy token mint, enroll orgs | [Mint service administration](../infrastructure/mint-administration.md) | +| **GCP Admin (Mint)** | Deploy token mint, enroll orgs | [Mint service administration](../guides/infrastructure/mint-administration.md) | | **GCP Admin (Inference)** | Provision WIF and Agent Platform access | [Installing fullsend — standalone commands](installation.md#standalone-commands) | | **GitHub Maintainer (org)** | Configure GitHub org — Apps, config repo, enrollment | **This guide** | | **GitHub Maintainer (repo)** | Configure a single repo — secrets, variables, shim workflow | **This guide** ([per-repo setup](#per-repo-setup)) | @@ -254,6 +254,6 @@ Use `admin install` when one person has both GCP and GitHub access. Use the stan ## See Also - [Installing fullsend](installation.md) — End-user setup (inference + GitHub) and all-in-one admin install -- [Mint service administration](../infrastructure/mint-administration.md) — Deploying and managing the token mint -- [Infrastructure Reference](../infrastructure/infrastructure-reference.md) — Token mint, WIF, and secrets details -- [CLI Internals](../dev/cli-internals.md) — Command structure and implementation details +- [Mint service administration](../guides/infrastructure/mint-administration.md) — Deploying and managing the token mint +- [Infrastructure Reference](../guides/infrastructure/infrastructure-reference.md) — Token mint, WIF, and secrets details +- [CLI Internals](../guides/dev/cli-internals.md) — Command structure and implementation details diff --git a/docs/guides/getting-started/installation.md b/docs/reference/installation.md similarity index 96% rename from docs/guides/getting-started/installation.md rename to docs/reference/installation.md index 35e0aa6015..6b3e585bd1 100644 --- a/docs/guides/getting-started/installation.md +++ b/docs/reference/installation.md @@ -35,7 +35,7 @@ Your setup path depends on what GCP infrastructure is already in place and how m | **[GitHub-only setup](github-setup.md)** | Both GCP inference and mint are pre-provisioned | GitHub org access + GCP config values from your admin (no GCP credentials needed) | | **[All-in-one admin install](#all-in-one-admin-install)** | You manage everything — GCP mint, inference, and GitHub | Full GCP + GitHub access | -> **Mint service note:** The token mint is fully self-hostable, but most users currently use the mint service hosted by the fullsend team. Work is in progress to offer this as a secure, trusted public service — reducing the need for per-org enrollment. See [Mint service administration](../infrastructure/mint-administration.md) for self-hosting details. +> **Mint service note:** The token mint is fully self-hostable, but most users currently use the mint service hosted by the fullsend team. Work is in progress to offer this as a secure, trusted public service — reducing the need for per-org enrollment. See [Mint service administration](../guides/infrastructure/mint-administration.md) for self-hosting details. --- @@ -86,7 +86,7 @@ This is the standard path for organizations using a hosted mint service. You pro ### Step 1: Request mint enrollment -Contact your mint service admin and request enrollment for your GitHub organization. They will run `fullsend mint enroll ` on the mint project (see [Mint service administration](../infrastructure/mint-administration.md)). Once enrolled, they will provide you with the mint URL. +Contact your mint service admin and request enrollment for your GitHub organization. They will run `fullsend mint enroll ` on the mint project (see [Mint service administration](../guides/infrastructure/mint-administration.md)). Once enrolled, they will provide you with the mint URL. ### Step 2: Provision inference access @@ -265,7 +265,7 @@ The installer automatically detects when the deployed mint function is up-to-dat ### Multi-org setup -A single token mint can serve multiple GitHub organizations. See [Mint service administration — Multi-org setup](../infrastructure/mint-administration.md#multi-org-setup) for the complete multi-org workflow. +A single token mint can serve multiple GitHub organizations. See [Mint service administration — Multi-org setup](../guides/infrastructure/mint-administration.md#multi-org-setup) for the complete multi-org workflow. ### Vendoring the CLI binary @@ -414,7 +414,7 @@ When a platform operator has pre-provisioned shared public GitHub Apps and a tok > **Tip:** For GitHub-only setup without GCP access, use `fullsend github setup` instead of `admin install`. See [Setting up with pre-provisioned infrastructure](github-setup.md). -> This section documents the **SaaS installation profile** defined in [ADR 0033 §6](../../ADRs/0033-per-repo-installation-mode.md#6-credential-models). If you are reusing apps from your own prior per-org installation, see [Reusing existing infrastructure](#reusing-existing-infrastructure) instead. +> This section documents the **SaaS installation profile** defined in [ADR 0033 §6](../ADRs/0033-per-repo-installation-mode.md#6-credential-models). If you are reusing apps from your own prior per-org installation, see [Reusing existing infrastructure](#reusing-existing-infrastructure) instead. **Prerequisites:** @@ -601,7 +601,7 @@ The `admin install` command performs all setup in a single invocation. For organ | GCP Admin (Mint) | `fullsend mint unenroll ` | Remove an org or repo from the mint | | GCP Admin (Mint) | `fullsend mint status` | Inspect mint state and PEM health | -See [Setting up with pre-provisioned infrastructure](github-setup.md) for the complete GitHub maintainer guide and [Mint service administration](../infrastructure/mint-administration.md) for the mint admin guide. +See [Setting up with pre-provisioned infrastructure](github-setup.md) for the complete GitHub maintainer guide and [Mint service administration](../guides/infrastructure/mint-administration.md) for the mint admin guide. ### Per-command IAM role breakdown @@ -735,7 +735,7 @@ All reusable workflows pass these inputs automatically. ## See Also - [Setting up with pre-provisioned infrastructure](github-setup.md) — GitHub-only setup when GCP is already provisioned -- [Mint service administration](../infrastructure/mint-administration.md) — Deploying and managing the token mint -- [Infrastructure Reference](../infrastructure/infrastructure-reference.md) — Token mint, WIF, and secrets deployment details -- [Enabling fullsend on private repositories](../infrastructure/private-repositories.md) — Additional guardrails for private repos -- [CLI Internals](../dev/cli-internals.md) — Command structure and implementation details +- [Mint service administration](../guides/infrastructure/mint-administration.md) — Deploying and managing the token mint +- [Infrastructure Reference](../guides/infrastructure/infrastructure-reference.md) — Token mint, WIF, and secrets deployment details +- [Enabling fullsend on private repositories](../guides/infrastructure/private-repositories.md) — Additional guardrails for private repos +- [CLI Internals](../guides/dev/cli-internals.md) — Command structure and implementation details diff --git a/web/docs/README.md b/web/docs/README.md index 18825422ce..4b39825373 100644 --- a/web/docs/README.md +++ b/web/docs/README.md @@ -18,7 +18,7 @@ Design and behavior are described in the [docs browser design spec](../../docs/s Shared links should use the **`#/`** fragment so navigation stays in the docs SPA without path segments under `/docs/`. - **Document:** `/docs/#/` - Example: `/docs/#/guides/getting-started/installation` — `routeKey` matches the manifest path to the Markdown file (POSIX-style segments, no leading slash in the fragment). + `routeKey` matches the manifest path to the Markdown file (POSIX-style segments, no leading slash in the fragment). - **Heading / in-page target:** `/docs/#/::` The **`::`** delimiter separates the document key from the heading **slug** (the `id` of the target element in the rendered page). It is not part of the slug itself; it only appears in the URL fragment so the app can load the right page and scroll to the right anchor.