Closes #106: Rewrite HOME.md and Setup.md for external customer-facing audience

README.md

@@ -2,7 +2,7 @@
 
 [![An agent that runs in your GitHub, not ours. Open source. Your runners, your secrets. A human merges.](docs/assets/simplycubed-code.png)](https://simplycubed.com/code?utm_source=github&utm_medium=readme&utm_campaign=code)
 
-An autonomous coding agent that lives inside your own GitHub. You file an issue, it opens a pull request, and a human decides whether to merge.
+SimplyCubed Code is an autonomous coding agent you install into your own GitHub. Your team files an issue, the agent prepares a pull request in your repository, and one of your reviewers decides whether it ships.
 
 > Beta, at `v0.1.9`. Product overview: [simplycubed.com/code](https://simplycubed.com/code?utm_source=github&utm_medium=readme&utm_campaign=code). See [Status](#status).
 
@@ -16,25 +16,37 @@ That runs the whole loop, including the model and your own gate. It makes no Git
 
 `simplycubed init --workflow` also writes a self-test into your repository. Dispatch it once and it checks, in your own runner, that the App token resolves to a bot, that it can read what it needs, and that it is denied Actions administration. The install fails if that denial does not hold. Delete the workflow once it passes.
 
-## What it is
+## Product overview
 
-SimplyCubed Code turns a GitHub issue into a pull request without a person writing the code. A human files an issue describing the change; the agent implements it against the repo's own quality gate and opens a pull request for a human to merge. When a human then requests changes on that pull request, a fixer role reads the feedback, addresses it, re-runs the gate, and pushes back to the same branch for another look.
+SimplyCubed Code turns a GitHub issue into a proposed code change inside your own environment. Your team keeps the repository, runners, secrets, and branch protection rules. The agent does the implementation work, but it never merges its own pull requests.
 
-It proposes. It does not dispose. The agent never pushes to `main` and never merges its own work. A person is always the one who clicks merge.
+For a customer team, the model is simple:
 
-The part that makes it different from hosted coding agents is where it runs. Everything happens inside your own GitHub Actions, on your runners, using your minutes and your secrets. SimplyCubed hosts nothing, runs no server on your behalf, and never sees your code or your credentials. Compare that to tools like Copilot's coding agent, Devin, or Codex cloud, which run the model against your code on someone else's infrastructure.
+- Your developers describe work in GitHub issues.
+- SimplyCubed Code implements against the repository's existing quality gate, such as `make check`.
+- The agent opens or updates a pull request for human review.
+- Your team keeps final control over merge, release, and production access.
+
+The product is designed for teams that want autonomous implementation without handing their source code or GitHub credentials to a hosted vendor runtime. Everything runs in your own GitHub Actions environment, on your runners, using your secrets.
+
+## Why teams use it
+
+- It runs inside your GitHub, not SimplyCubed's infrastructure.
+- It uses your repository's existing quality gate instead of inventing its own definition of done.
+- It is built for a human-review workflow, not auto-merge automation.
+- It keeps permissions narrow: the agent can propose changes, but not deploy or merge them.
 
 ## How it works
 
-The loop is issue to pull request, driven entirely through GitHub.
+The customer workflow is issue to pull request, driven entirely through GitHub.
 
 1. A human files an issue and applies the `sc:go` label. That label is the only thing a person applies to start the work.
 2. The agent implements the change on a branch and runs the repo's own quality gate, using the gate's output to guide each retry until it passes or it stops and asks for a human.
 3. Once the gate passes, the agent opens a pull request and hands it back to a human.
 4. A human reviews. If they request changes, a fixer role reads the feedback, makes the changes, re-runs the gate, and pushes back to the same pull request for another look. Only feedback left against the current head is addressed, so the loop never re-litigates a comment it already handled.
 5. A human merges. The agent does not.
 
-An automated reviewer runs before step 4 if you turn it on (`review: true`, off by default). It comments; it never approves and never merges. Step 5 is a human either way.
+An automated reviewer can also run before human review if you turn on `review: true`. It comments on the change; it does not approve and it does not merge.
 
 ### Label lifecycle
 
@@ -78,11 +90,11 @@ flowchart LR
 
 A plain comment in the conversation box is not a review. To run the fixer from a review, submit it through **Files changed → Review changes**. Every path checks that the person has write access before anything else happens.
 
-## Running in your own GitHub
+## Deployment model
 
-The whole thing runs on GitHub Actions, event-driven, with no server and no VM for SimplyCubed to operate. When you install the app and file issues, the work executes on your runners inside your organization.
+SimplyCubed Code is deployed into your GitHub organization. There is no SimplyCubed-hosted control plane managing your repositories for you. When your team installs the GitHub App and adds the workflow, the work runs on your runners inside your account.
 
-### What it can do to your repo, and what stops it
+### What it can do, and what stops it
 
 It can open a pull request against a branch. That is the strongest action available to it.
 
@@ -95,20 +107,20 @@ What stops it, roughly in order of how much you should trust each one:
 5. Neither engine's "dangerous" bypass flag is set. When a change cannot be made under those constraints, the run stops and a human finishes it. [Why](docs/faq.md).
 6. No deploy credentials, and no path to production. Your branch protection rules decide what happens once the pull request exists.
 
-What this buys you:
+What that means for customers:
 
 - Your code stays in your repos. SimplyCubed never receives it.
 - Your model provider keys, the GitHub App's private key, and any other secrets stay in your GitHub secret store. They are read by your own Actions runs and never transit our infrastructure.
 - It does not use the engines' "dangerous" bypass flags, and does not receive a GitHub token in the model's shell. When a change cannot be made under those constraints, the run stops and a human finishes it. See the [FAQ](docs/faq.md).
 - The agent holds no deploy credentials and has no path to production. The most it can do is open a pull request against a branch. A human and your branch protection rules decide what happens next.
 
-Setup files are written locally by `simplycubed init` and merged by a human, because the runtime holds no `workflows` permission and cannot add its own workflow files.
+Setup files are generated locally by `simplycubed init` and then merged by a human, because the runtime holds no `workflows` permission and cannot add or update workflow files on its own.
 
 The GitHub App identity is `simplycubed-code[bot]`. That bot is the single audit signal for everything the agent does.
 
 ## Getting started
 
-Start with the adopter quickstart in [docs/setup.md](docs/setup.md). It covers the shipped path from CLI install to the first issue-driven pull request, including where the Azure endpoint and key live for local CLI runs versus GitHub Actions.
+Start with [docs/setup.md](docs/setup.md). It walks through customer installation in a repository you control, from CLI install through the first issue-driven pull request.
 
 ## Installation
 
@@ -123,9 +135,7 @@ That prints `0.1.7`. Pre-1.0 releases follow semver with the usual caveat: minor
 versions may still change behavior. Pin the tag you have validated rather than
 floating on `@latest`.
 
-Then follow the [quickstart in `docs/setup.md`](docs/setup.md) to write the repo
-config, add the caller workflow, set the Azure values, and open the first pull
-request.
+Then follow the [setup guide in `docs/setup.md`](docs/setup.md) to add the repository config, install the GitHub workflow, set the required credentials, and run the first issue through the system.
 
 ## Install into your GitHub
 

docs/setup.md

@@ -1,17 +1,26 @@
 # Setup
 
-This is the adopter path that exists today: install the CLI, write the repo
-config and caller workflow into your own repository, set the Azure values in the
-right places, and let GitHub Actions drive issues to pull requests.
+This guide shows how to install SimplyCubed Code in a repository you control so
+it can turn issues into pull requests inside your own GitHub environment.
 
-## Quickstart
+You will:
 
-Prerequisites:
+- install the `simplycubed` CLI
+- generate the repository config and GitHub workflow files
+- connect your GitHub App and model credentials
+- run a one-time self-test
+- hand the first issue to the agent
 
-- Go installed locally so you can run `go install`.
-- `gh` authenticated against the repository you want to onboard.
-- Write access on that repository.
-- An Azure OpenAI endpoint and API key.
+## Before you begin
+
+You need:
+
+- Go installed locally so you can run `go install`
+- `gh` authenticated against the repository you want to onboard
+- write access on that repository
+- an Azure OpenAI endpoint and API key
+
+## Install and configure
 
 1. Install the CLI:
 
@@ -20,83 +29,100 @@ go install github.com/simplycubed/code/cmd/simplycubed@v0.1.9
 simplycubed version
 ```
 
-2. In the target repository, generate the starter files and labels:
+2. In the target repository, generate the setup files and labels:
 
 ```sh
 simplycubed init --workflow
 ```
 
-That writes three files and creates the `sc:*` labels through your local `gh`
-auth:
+That creates the `sc:*` labels through your local `gh` session and writes three
+files into your repository:
 
 - `.github/simplycubed.yml`, the repository config
-- `.github/workflows/simplycubed.yml`, the caller workflow
-- `.github/workflows/simplycubed-selftest.yml`, an install check you run once
-  and then delete The files are local
-changes in your repository; nothing is merged or installed remotely for you.
+- `.github/workflows/simplycubed.yml`, the workflow that runs SimplyCubed Code
+- `.github/workflows/simplycubed-selftest.yml`, a one-time installation check
+
+These are local file changes in your repository. Nothing is merged or installed
+remotely for you.
 
 3. Edit `.github/simplycubed.yml` and set a real gate that is already green on
-your default branch. A minimal example is:
+your default branch. A minimal customer setup looks like this:
 
 ```yaml
 labelPrefix: sc
 gate: make check
 ```
 
-### Run it locally first
+### Optional: prove it locally first
 
-Before wiring Actions, you can prove the loop works from your terminal with the
-same config file:
+Before wiring GitHub Actions, you can prove the loop works from your terminal
+with the same config file:
 
 ```sh
 export AZURE_OPENAI_ENDPOINT="https://<resource>.openai.azure.com"
 export AZURE_OPENAI_API_KEY="<key>"
 simplycubed run owner/repo#N --repo-dir .
 ```
 
-4. In the GitHub repository settings, add:
+4. Create and install the GitHub App identity, then add the required repository
+settings.
+
+Create the `simplycubed-code` GitHub App with `Contents`, `Issues`, and `Pull
+requests` permissions only, disable the webhook, set install visibility to `Any
+account`, and install it on the repository.
+
+Then add these repository settings:
 
 - Variable: `SIMPLYCUBED_GH_APP_CLIENT_ID`, the App Client ID, the `Iv23` string on the App settings page
 - Secret: `SIMPLYCUBED_GH_APP_PRIVATE_KEY`
 - Variable: `AZURE_OPENAI_ENDPOINT`
 - Secret: `AZURE_OPENAI_API_KEY`
 
 The Actions runtime authenticates as the `simplycubed-code` GitHub App, so the
-App ID and private key are required. Create the App with `Contents`, `Issues`,
-and `Pull requests` permissions only, webhook disabled, install visibility `Any
-account`, then install it on the repository. Store the private key as the full
-PEM contents, including the `-----BEGIN` and `-----END` lines.
+App ID and private key are required. Store the private key as the full PEM
+contents, including the `-----BEGIN` and `-----END` lines.
 
 Each job mints its own installation token for that repository, so the agent
-authors commits, pull requests, and comments as `simplycubed-code[bot]`, and its
-pull requests receive their own CI runs. A personal access token is not an
+authors commits, pull requests, and comments as `simplycubed-code[bot]`, and
+its pull requests receive their own CI runs. A personal access token is not an
 alternative: the reusable workflow accepts App credentials only.
 
 5. Commit the generated config and workflow files in the target repository, open
 a setup pull request, and merge it yourself. Setup files are written locally by
 `simplycubed init` and merged by a human, because the runtime holds no
 `workflows` permission and cannot add its own workflow files.
 
-6. Check the install before trusting it:
+6. Run the installation self-test before you rely on the workflow:
 
 ```sh
 gh workflow run simplycubed-selftest
 ```
 
-That runs in your own runner and reports whether the App token resolves to a
-bot, whether it is correctly denied Actions administration, whether a commit is
-possible, and whether the engine can start there. Delete the workflow once it
-passes; normal operation goes through the App and the `sc:go` label.
+That runs in your own environment and reports whether the App token resolves to
+a bot, whether it is correctly denied Actions administration, whether a commit
+is possible, and whether the engine can start there. Delete the self-test
+workflow once it passes; normal operation goes through the App and the `sc:go`
+label.
 
 7. File an issue that describes a small change and apply the `sc:go` label.
 
 8. Wait for the workflow to open a pull request. Review it like any other PR:
 
-- Merge it yourself if it is good.
-- Or request changes; the fixer loop will address feedback on the current head
-  and push back to the same branch.
+- merge it yourself if it is good
+- or request changes; the fixer loop will address feedback on the current head
+  and push back to the same branch
+
+That is the first end-to-end customer path: issue -> PR -> human merge.
+
+## Day-to-day use
+
+Once setup is complete, your team uses SimplyCubed Code through normal GitHub
+workflows:
 
-That is the first end-to-end path: issue -> PR -> human merge.
+- apply `sc:go` to an issue to start implementation
+- review the pull request the agent opens
+- request changes if needed; the fixer loop pushes updates back to the same PR
+- merge it yourself when it meets your standards
 
 ## Where each value goes
 
@@ -170,9 +196,9 @@ Use the same endpoint and key in both places, but wire them differently.
 
 For local runs such as `simplycubed run owner/repo#123`, the CLI reads:
 
-- `AZURE_OPENAI_ENDPOINT` from your shell environment.
-- `AZURE_OPENAI_API_KEY` from your shell environment.
-- The repo gate and label prefix from `.github/simplycubed.yml`.
+- `AZURE_OPENAI_ENDPOINT` from your shell environment
+- `AZURE_OPENAI_API_KEY` from your shell environment
+- the repo gate and label prefix from `.github/simplycubed.yml`
 
 Example:
 
@@ -201,16 +227,16 @@ For the hosted-in-your-GitHub path, the caller workflow in your repository
 passes:
 
 - `vars.AZURE_OPENAI_ENDPOINT` to the reusable workflow input
-  `azure-openai-endpoint`.
+  `azure-openai-endpoint`
 - `secrets.AZURE_OPENAI_API_KEY` to the reusable workflow secret
-  `azure-openai-api-key`.
+  `azure-openai-api-key`
 - `vars.SIMPLYCUBED_GH_APP_CLIENT_ID` to the reusable workflow input
-  `github-app-client-id`.
+  `github-app-client-id`
 - `secrets.SIMPLYCUBED_GH_APP_PRIVATE_KEY` to the reusable workflow secret
-  `github-app-private-key`.
+  `github-app-private-key`
 
-The reusable workflow installs the CLI, exports the endpoint and key for the job,
-and runs `simplycubed run` or `simplycubed address`.
+The reusable workflow installs the CLI, exports the endpoint and key for the
+job, and runs `simplycubed run` or `simplycubed address`.
 
 That hosted path is still Codex-on-Azure only. The reusable workflow installs
 the Codex CLI, not the Claude CLI, and its inputs and secrets still require the