Release v0.1.0-rc.1

Co-authored-by: Ravindra Barthwal <p8ndotai@gmail.com>
Amp-Thread-ID: https://ampcode.com/threads/T-01a0d921-e915-746a-b8b0-530e5568dace

Author: ampagent

apps/docs/astro.config.mjs

@@ -1,7 +1,8 @@
-import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
+import { defineConfig } from "astro/config";
 
 export default defineConfig({
+  base: "/docs",
   integrations: [
     starlight({
       title: "dx docs",
@@ -39,6 +40,18 @@ export default defineConfig({
               label: "Models and providers",
               slug: "deployment/models-providers",
             },
+            {
+              label: "GitHub source access",
+              slug: "deployment/github-source",
+            },
+            {
+              label: "Bitbucket source access",
+              slug: "deployment/bitbucket-source",
+            },
+            {
+              label: "GitHub Copilot",
+              slug: "deployment/github-copilot",
+            },
             {
               label: "Upgrade and recovery",
               slug: "operations/upgrade-recovery",

apps/docs/scripts/check-content.mjs

@@ -5,7 +5,11 @@ import { fileURLToPath } from "node:url";
 
 const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
 const built = process.argv.includes("--built");
-const scanRoot = resolve(root, built ? "dist" : "src/content/docs");
+const rootArgument = process.argv.indexOf("--root");
+const scanRoot =
+  rootArgument === -1
+    ? resolve(root, built ? "dist" : "src/content/docs")
+    : resolve(process.argv[rootArgument + 1] ?? "");
 const scannedExtensions = new Set(
   built ? [".css", ".html", ".js", ".json", ".svg"] : [".md", ".mdx"],
 );
@@ -34,6 +38,14 @@ const prohibited = [
     pattern: new RegExp(`(?<!&)\\b${forbiddenAssistantName}\\b(?!;)`, "gi"),
   },
   { label: "private commit SHA", pattern: /\b[0-9a-f]{40}\b/gi },
+  {
+    label: "unfinished content marker",
+    pattern: /\b(?:TODO|TBD|Track [A-D]|not implemented)\b/gi,
+  },
+  {
+    label: "obsolete release language",
+    pattern: /\b(?:pre-release|prerelease|rehearsal|clean-room)\b/gi,
+  },
 ];
 
 const walk = async (directory) => {
@@ -65,7 +77,10 @@ const builtLinkTarget = (sourcePath, href) => {
   const sourceRoute = `/${relative(scanRoot, sourcePath).replace(/index[.]html$/, "")}`;
   const url = new URL(href, `https://docs.invalid${sourceRoute}`);
   if (url.origin !== "https://docs.invalid") return undefined;
-  const pathname = decodeURIComponent(url.pathname);
+  const pathname = decodeURIComponent(url.pathname).replace(
+    /^\/docs(?=\/|$)/,
+    "",
+  );
   const direct = resolve(scanRoot, pathname.replace(/^\//, ""));
   const candidates = pathname.endsWith("/")
     ? [resolve(direct, "index.html")]
@@ -119,7 +134,10 @@ for (const path of files) {
       );
       continue;
     }
-    const slug = href.replace(/^\//, "").replace(/\/$/, "");
+    const slug = href
+      .replace(/^\/docs(?=\/|$)/, "")
+      .replace(/^\//, "")
+      .replace(/\/$/, "");
     const candidates = slug
       ? [
           resolve(scanRoot, `${slug}.md`),

apps/docs/scripts/check-content.test.ts

@@ -1,5 +1,7 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 
@@ -17,6 +19,30 @@ describe("docs content checks", () => {
     expect(result.stdout).toContain("docs source and internal links passed");
   });
 
+  it.each([
+    "TODO: finish this",
+    "TBD",
+    "Pending Track C integration",
+    "This is not implemented.",
+    "pre-release instructions",
+    "external clean-room check",
+  ])("rejects unfinished release content: %s", (contents) => {
+    const fixture = mkdtempSync(resolve(tmpdir(), "dx-docs-content-"));
+    writeFileSync(resolve(fixture, "page.md"), contents);
+    const script = fileURLToPath(
+      new URL("./check-content.mjs", import.meta.url),
+    );
+    const result = spawnSync(process.execPath, [script, "--root", fixture], {
+      encoding: "utf8",
+    });
+    rmSync(fixture, { recursive: true, force: true });
+
+    expect(result.status).toBe(1);
+    expect(result.stderr).toMatch(
+      /unfinished content marker|obsolete release language/,
+    );
+  });
+
   it("typechecks through the workspace gate without generated Astro state", () => {
     const generatedDirectory = fileURLToPath(
       new URL("../.astro", import.meta.url),

apps/docs/src/content/docs/contributing/guide.md

@@ -34,6 +34,5 @@ contributing.
 
 ## Documentation style
 
-Write instructions a reader can execute. Mark unreleased behavior instead of
-presenting it as current. Use placeholders only when an owning schema or command
-has not landed, and name the integration that must replace the placeholder.
+Write instructions a reader can execute. Describe behavior that exists in the
+current release. Link to the owning schema or command when exact input matters.

apps/docs/src/content/docs/deployment/bitbucket-source.md

@@ -0,0 +1,93 @@
+---
+title: Bitbucket source access
+description: Register a Bitbucket Cloud OAuth consumer for private repositories and pull requests.
+---
+
+Bitbucket integration is optional. Public Git URLs work without it. Configure a
+Bitbucket Cloud OAuth consumer when users need private repository discovery,
+checkout, pushes, or pull request operations.
+
+## Register the OAuth consumer
+
+You need administrative access to a Bitbucket Cloud workspace. Follow
+Atlassian's [OAuth consumer
+guide](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/).
+
+1. Open the workspace's **Settings → OAuth consumers** and choose **Add
+   consumer**.
+2. Enter a name and the deployment origin as the website.
+3. Set the callback URL to
+   `<deployment-origin>/v1/integrations/bitbucket/oauth/callback`.
+4. Select **Account: Read**, **Repositories: Write**, and **Pull requests:
+   Write**. Leave unrelated permissions off.
+5. Save the consumer and copy its generated key and secret.
+
+For dxcode.dev, the callback is:
+
+```text
+https://dxcode.dev/v1/integrations/bitbucket/oauth/callback
+```
+
+The `account` scope lets dx identify the user and inspect accessible workspaces.
+`repository:write` includes repository read and HTTPS push access.
+`pullrequest:write` includes pull request read, create, update, approve, decline,
+and merge access. Atlassian defines these scopes in the [Bitbucket OAuth 2.0
+reference](https://developer.atlassian.com/cloud/bitbucket/oauth-2#bitbucket-oauth-2-0-scopes).
+
+## Create the installer JSON
+
+The consumer key is the `clientId`. The installer accepts this exact object:
+
+```json
+{
+  "version": 1,
+  "clientId": "replace-with-consumer-key",
+  "clientSecret": "replace-with-consumer-secret",
+  "callbackUrl": "https://dx.example.com/v1/integrations/bitbucket/oauth/callback"
+}
+```
+
+The callback must use HTTPS and exactly match the deployment origin and path.
+Extra fields are rejected. Do not commit this JSON or expose the consumer
+secret.
+
+Run `pnpm dx:deploy`, answer **Yes** to **Configure Bitbucket OAuth**, and paste
+the object at the hidden **Bitbucket OAuth JSON** prompt. Noninteractive runs set
+`integrations` to include `bitbucket` and supply the object through
+`DX_INTEGRATION_BITBUCKET_OAUTH`.
+
+## Connect and verify
+
+1. Open **Settings → Integrations → Bitbucket** in dx.
+2. Choose **Connect** and authorize the consumer as the Bitbucket user whose
+   repositories should be available.
+3. Create a project from a private Bitbucket repository.
+4. Verify checkout from the default branch and create or update a pull request
+   from an agent branch.
+
+dx refreshes expiring access tokens. **Refresh** rechecks the account and
+repository list. Disconnecting in dx deletes its stored authorization and stops
+local access. It does not revoke the grant at Bitbucket; use Bitbucket's app
+authorization settings for provider-side revocation.
+
+## Rotate or remove access
+
+Create a replacement consumer, then run `pnpm dx:deploy -- --rotate`, choose
+Bitbucket, and provide its JSON. Users must reconnect. Verify access before
+deleting the old consumer. To remove Bitbucket from a deployment, remove
+`bitbucket` from `integrations`, rerun, disconnect stored connections in dx, and
+delete or revoke the consumer in Bitbucket.
+
+## Troubleshooting
+
+- **Configuration rejected:** confirm the object has only the four documented
+  fields and the callback exactly matches the deployed HTTPS origin.
+- **Authorization returns an error:** compare the callback in Bitbucket with the
+  JSON, then start **Connect** again. Authorization state expires after ten
+  minutes and cannot be reused.
+- **Repositories are missing:** confirm the authorizing user has access and the
+  consumer has Account read, Repositories write, and Pull requests write.
+- **Connection expires:** choose **Reconnect**. Unused Bitbucket refresh tokens
+  expire, and provider-side revocation also requires a new authorization.
+- **Disconnect still appears in Bitbucket:** revoke dx from Bitbucket's app
+  authorization settings after disconnecting locally.

apps/docs/src/content/docs/deployment/configuration.md

@@ -34,7 +34,7 @@ Do not use a global API key. Keep account IDs and tokens out of committed config
 
 v0.1.0 has no local or alternative production workspace adapter. The deployment
 needs an E2B API key and immutable template identities for every enabled profile.
-See [E2B profiles](/deployment/e2b-profiles/).
+See [E2B profiles](/docs/deployment/e2b-profiles/).
 
 ## `deploy.selfhost.json`
 
@@ -50,7 +50,7 @@ The wizard writes this nonsecret JSON file:
   "zone": "example.com",
   "allowSignup": false,
   "workersAi": true,
-  "githubCopilotClientId": "optional-public-client-id",
+  "githubCopilotClientId": "optional-oauth-app-client-id",
   "modelDeploymentProviders": "optional,comma-separated,ids",
   "modelEndpointAllowlist": "optional,comma-separated,origins",
   "dxdBinary": ".dx/release/dxd-linux-x64",
@@ -75,10 +75,18 @@ The matching secret environment inputs are
 `DX_INTEGRATION_GITHUB_APP`, `DX_INTEGRATION_BITBUCKET_OAUTH`, and
 `SARVAM_API_KEY`.
 
-The first wizard run asks for a hidden administrator password and confirmation;
-an empty first response generates one. A successful deploy stores the URL,
-email, and password in ignored `.dx/secrets/selfhost-admin.txt` with mode `0600`.
-Use `pnpm dx:deploy -- --reset-admin` to replace the password explicitly.
+The first self-host wizard run asks for a hidden administrator password and
+confirmation. An empty first response generates one. A successful deploy
+stores the URL, email, and password in ignored
+`.dx/secrets/selfhost-admin.txt` with mode `0600`. Use
+`pnpm dx:deploy -- --reset-admin` to replace the password explicitly.
+
+The GitHub App and Bitbucket consumer values are strict JSON secrets supplied
+through hidden prompts or environment variables. See [GitHub source
+access](/docs/deployment/github-source/) and [Bitbucket source
+access](/docs/deployment/bitbucket-source/) for their exact schemas. The Copilot
+value is the client ID of an operator-owned GitHub OAuth App; see [GitHub
+Copilot](/docs/deployment/github-copilot/).
 
 ## Cost review and cancellation
 

apps/docs/src/content/docs/deployment/e2b-profiles.md

@@ -3,7 +3,7 @@ title: E2B profiles
 description: Size and maintain the E2B templates used by dx workspaces.
 ---
 
-dx v0.1.0 defines three workspace profiles:
+dx defines three workspace profiles:
 
 | Profile | vCPU | Memory | Disk | Suggested use |
 | --- | ---: | ---: | ---: | --- |

apps/docs/src/content/docs/deployment/github-copilot.md

@@ -0,0 +1,93 @@
+---
+title: GitHub Copilot
+description: Configure device authorization for personal GitHub Copilot subscriptions.
+---
+
+GitHub Copilot is an optional personal model connection. It is separate from
+the GitHub App used for source repositories. Each user authorizes their own
+Copilot subscription.
+
+:::caution[Compatibility limitation]
+GitHub documents the OAuth device flow used for authorization, but it does not
+publish a supported Copilot inference API for this integration. dx currently
+uses compatibility endpoints and headers observed in GitHub's developer tools.
+GitHub can change or block that behavior. Treat Copilot as optional and keep a
+documented model route through a supported provider.
+:::
+
+## Register an OAuth App
+
+Create an operator-owned GitHub OAuth App. Do not copy a client ID from another
+application. Follow GitHub's [OAuth App registration
+guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app).
+
+1. Open **Settings → Developer settings → OAuth apps → New OAuth App**.
+2. Set the application name and homepage URL. Use `<deployment-origin>` for the
+   homepage.
+3. Set the authorization callback URL to `<deployment-origin>/`. GitHub requires
+   this registration field, although device authorization does not redirect to
+   it.
+4. Enable **Device Flow**.
+5. Keep expiring user access tokens enabled, then register the app.
+6. Copy the OAuth App's client ID. dx does not need or accept its client secret.
+
+GitHub's [device flow
+reference](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow)
+documents the endpoints, polling interval, code expiry, and token refresh flow.
+
+For dxcode.dev, both homepage and callback use `https://dxcode.dev`, with a
+trailing slash accepted for the callback field.
+
+`DX_GITHUB_COPILOT_CLIENT_ID` is this OAuth App client ID. During device
+authorization, dx requests the documented `read:user` scope from
+`https://github.com/login/device/code`, directs the user to
+`https://github.com/login/device`, and polls
+`https://github.com/login/oauth/access_token`.
+
+## Configure the deployment
+
+Run `pnpm dx:deploy`, answer **Yes** to **Configure GitHub Copilot sign-in**, and
+enter the client ID at **GitHub Copilot OAuth client ID**. This value is an
+identifier, not a secret. Noninteractive runs set `githubCopilotClientId` in
+`deploy.selfhost.json`.
+
+Without a nonempty client ID, Copilot authorization endpoints return
+unavailable and users cannot start the connection flow. Other model providers
+continue to work.
+
+## Connect and verify
+
+1. Confirm the GitHub account has an active Copilot subscription.
+2. Open **Settings → Model routing** in dx and choose **Connect GitHub Copilot**.
+3. Open the displayed `https://github.com/login/device` link and enter the
+   one-time code.
+4. Return to dx and wait for the connection to complete.
+5. Assign an available Copilot model to one agent slot and run a small prompt.
+
+dx encrypts the resulting personal OAuth credential. Refresh rechecks the
+GitHub identity, subscription access, and model catalog. Disconnect is blocked
+while a model route still uses the connection; remove those routes first.
+
+## Rotate or disconnect
+
+To replace the OAuth App, update `githubCopilotClientId` in
+`deploy.selfhost.json` and rerun `pnpm dx:deploy`. Ask users to disconnect and
+authorize through the replacement app, then delete the old OAuth App after
+verification. A user disconnects from **Settings → Model routing** after
+removing routes that use the subscription. They can also revoke the grant in
+GitHub's application settings.
+
+## Troubleshooting
+
+- **Connect is unavailable:** set a nonempty `githubCopilotClientId` and rerun
+  the deployment.
+- **Device code fails:** confirm Device Flow is enabled on the same OAuth App
+  whose client ID was deployed, then start a new code. Codes expire and cannot
+  be reused.
+- **GitHub authorizes but no models appear:** confirm the signed-in account has
+  Copilot access. Organization policy can restrict models.
+- **Inference fails after a successful connection:** the compatibility API may
+  have changed or rejected the client. Use another configured provider; a
+  successful OAuth grant does not prove Copilot inference compatibility.
+- **Disconnect is blocked:** remove every model route that uses the Copilot
+  connection, then disconnect again.