diff --git a/.changeset/config.json b/.changeset/config.json index cd68275f..d94dbced 100644 --- a/.changeset/config.json +++ b/.changeset/config.json @@ -7,5 +7,5 @@ "access": "public", "baseBranch": "main", "updateInternalDependencies": "patch", - "ignore": ["@caplets/landing"] + "ignore": ["@caplets/landing", "@caplets/docs"] } diff --git a/.changeset/fresh-rings-attach.md b/.changeset/fresh-rings-attach.md new file mode 100644 index 00000000..56fc6b40 --- /dev/null +++ b/.changeset/fresh-rings-attach.md @@ -0,0 +1,5 @@ +--- +"@caplets/core": minor +--- + +Add remote attach URL configuration and update the native remote attach flow. diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 9d82c4d7..8b924b56 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -8,6 +8,7 @@ on: - .github/workflows/deploy.yml - alchemy.run.ts - apps/** + - infra/** - package.json - pnpm-lock.yaml - pnpm-workspace.yaml diff --git a/.github/workflows/pr-preview-deploy.yml b/.github/workflows/pr-preview-deploy.yml index dc833ce5..caa2c344 100644 --- a/.github/workflows/pr-preview-deploy.yml +++ b/.github/workflows/pr-preview-deploy.yml @@ -8,6 +8,7 @@ on: - .github/workflows/pr-preview-deploy.yml - alchemy.run.ts - apps/** + - infra/** - package.json - pnpm-lock.yaml - pnpm-workspace.yaml diff --git a/DESIGN.md b/DESIGN.md index 25b36829..3e731f9f 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -97,6 +97,8 @@ The system is product-first: precise, calm, capable. It should feel like an expe The physical scene is a developer reviewing an agent setup at a desk during focused work, with docs, terminal output, and a browser open side by side. The theme stays light and warm because this surface is read for long stretches, compared with documentation, and used during configuration rather than incident response. +The public landing page may invert into a dark aperture treatment for the hero, benchmark proof, and route-map storytelling. That exception is campaign art direction, not the default product UI theme: keep it precise, sparse, and tied to the capability-exposure metaphor rather than neon terminal cosplay. + **Key Characteristics:** - Warm light surfaces with ink-like text and a rare ember accent. diff --git a/README.md b/README.md index 304eb475..adf82fdd 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@

caplets.dev + ยท + docs.caplets.dev

@@ -38,6 +40,8 @@ Caplets can wrap: ## Quick Start +Full setup and configuration docs are available at [docs.caplets.dev](https://docs.caplets.dev/). + Install the CLI and wire it into your agent: ```sh @@ -170,6 +174,7 @@ tokens than direct vanilla MCP. Live runs are model- and environment-dependent; deterministic benchmark is the reproducible claim. See [docs/benchmarks/coding-agent.md](https://github.com/spiritledsoftware/caplets/blob/main/docs/benchmarks/coding-agent.md) for methodology and reproduction commands. +See [docs.caplets.dev/changelog](https://docs.caplets.dev/changelog/) for public release notes. ## Repository @@ -200,6 +205,7 @@ Package map: - `packages/pi` - native Pi extension - `packages/benchmarks` - deterministic and opt-in live benchmarks - `apps/landing` - public site at `caplets.dev` +- `apps/docs` - public docs site at `docs.caplets.dev` Long-lived docs: diff --git a/alchemy.run.ts b/alchemy.run.ts index efe5d07f..e1d5a405 100644 --- a/alchemy.run.ts +++ b/alchemy.run.ts @@ -10,7 +10,10 @@ const app = await alchemy("caplets", { password: process.env.ALCHEMY_PASSWORD!, }); -const { landingPageDomain, landingPageUrl } = buildAlchemyDomains(app.stage, { local: app.local }); +const { docsPageDomain, docsPageUrl, landingPageDomain, landingPageUrl } = buildAlchemyDomains( + app.stage, + { local: app.local }, +); export const landingPage = await Astro("landing-page", { cwd: "apps/landing", dev: { @@ -18,9 +21,17 @@ export const landingPage = await Astro("landing-page", { }, domains: [landingPageDomain, `www.${landingPageDomain}`], }); +export const docsPage = await Astro("docs-page", { + cwd: "apps/docs", + dev: { + command: "pnpm run dev -- --port 4322" + (process.env.SSH_CONNECTION ? " --host 0.0.0.0" : ""), + }, + domains: [docsPageDomain], +}); console.log({ "Landing Page URL": landingPageUrl, + "Docs Page URL": docsPageUrl, }); const [repositoryOwnerFromSlug, repositoryNameFromSlug] = @@ -35,20 +46,17 @@ if (pullRequestNumber) { throw new Error("Missing GitHub repository metadata for preview comment."); } + const shortSha = process.env.GITHUB_SHA?.slice(0, 7) ?? "unknown"; await GitHubComment("preview-comment", { owner: repositoryOwner, repository: repositoryName, issueNumber: pullRequestNumber, - body: `## ๐Ÿš€ Preview Deployed - -Your changes have been deployed to a preview environment: - -**๐ŸŒ Landing Page:** ${landingPageUrl} + body: `## Preview Deployed -Built from commit ${process.env.GITHUB_SHA?.slice(0, 7) ?? "unknown"} +Landing: ${landingPageUrl} +Docs: ${docsPageUrl} ---- -๐Ÿค– This comment updates automatically with each push.`, +Built from commit ${shortSha}`, }); } diff --git a/apps/docs/.gitignore b/apps/docs/.gitignore new file mode 100644 index 00000000..6240da8b --- /dev/null +++ b/apps/docs/.gitignore @@ -0,0 +1,21 @@ +# build output +dist/ +# generated types +.astro/ + +# dependencies +node_modules/ + +# logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + + +# environment variables +.env +.env.production + +# macOS-specific files +.DS_Store diff --git a/apps/docs/README.md b/apps/docs/README.md new file mode 100644 index 00000000..0882b8fd --- /dev/null +++ b/apps/docs/README.md @@ -0,0 +1,25 @@ +# Caplets Docs + +Astro Starlight documentation site for [docs.caplets.dev](https://docs.caplets.dev). + +Public docs live in `apps/docs/src/content/docs`. Root `docs/` is internal maintainer +documentation and is not routed into this site. + +Generated reference pages and the public changelog come from: + +- `schemas/caplets-config.schema.json` +- `schemas/caplet.schema.json` +- `packages/core/src/code-mode/runtime-api.d.ts` +- `CHANGELOG.md` + +## Commands + +Run from the repository root: + +```sh +pnpm docs:generate +pnpm docs:check +pnpm --filter @caplets/docs dev -- --port 4322 +pnpm --filter @caplets/docs typecheck +pnpm --filter @caplets/docs build +``` diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs new file mode 100644 index 00000000..094474f1 --- /dev/null +++ b/apps/docs/astro.config.mjs @@ -0,0 +1,64 @@ +// @ts-check +import starlight from "@astrojs/starlight"; +import tailwindcss from "@tailwindcss/vite"; +import { defineConfig } from "astro/config"; + +export default defineConfig({ + site: "https://docs.caplets.dev", + integrations: [ + starlight({ + title: "Caplets Docs", + logo: { + src: "./src/assets/caplets-icon.png", + alt: "Caplets", + }, + social: [ + { + icon: "github", + label: "GitHub", + href: "https://github.com/spiritledsoftware/caplets", + }, + ], + customCss: ["./src/styles/global.css"], + components: { + ThemeProvider: "./src/components/CapletsThemeProvider.astro", + ThemeSelect: "./src/components/CapletsThemeSelect.astro", + }, + editLink: { + baseUrl: "https://github.com/spiritledsoftware/caplets/edit/main/apps/docs/", + }, + sidebar: [ + { + label: "Get Started", + items: [ + { label: "Start here", link: "/" }, + { label: "Install", link: "/install/" }, + { label: "Configuration", link: "/configuration/" }, + ], + }, + { + label: "Use Caplets", + items: [ + { label: "Code Mode", link: "/code-mode/" }, + { label: "Add capabilities", link: "/capabilities/" }, + { label: "Agent integrations", link: "/agent-integrations/" }, + { label: "Remote attach", link: "/remote-attach/" }, + { label: "Troubleshooting", link: "/troubleshooting/" }, + ], + }, + { + label: "Reference", + items: [ + { label: "Configuration schema", link: "/reference/config/" }, + { label: "Code Mode API", link: "/reference/code-mode-api/" }, + { label: "Caplet files", link: "/reference/caplet-files/" }, + { label: "Changelog", link: "/changelog/" }, + ], + }, + ], + }), + ], + vite: { + plugins: [tailwindcss()], + }, +}); diff --git a/apps/docs/package.json b/apps/docs/package.json new file mode 100644 index 00000000..a47d6124 --- /dev/null +++ b/apps/docs/package.json @@ -0,0 +1,28 @@ +{ + "name": "@caplets/docs", + "version": "0.1.0", + "private": true, + "type": "module", + "scripts": { + "astro": "astro", + "build": "astro build", + "dev": "astro dev", + "preview": "astro preview", + "typecheck": "astro check" + }, + "dependencies": { + "@astrojs/check": "^0.9.9", + "@astrojs/starlight": "^0.40.0", + "@tailwindcss/vite": "^4.3.1", + "astro": "^6.4.6", + "sharp": "^0.34.5", + "tailwindcss": "^4.3.1", + "typescript": "^6.0.3" + }, + "devDependencies": { + "vite": "^7.3.5" + }, + "engines": { + "node": ">=24" + } +} diff --git a/apps/docs/public/favicon.svg b/apps/docs/public/favicon.svg new file mode 100644 index 00000000..cba5ac14 --- /dev/null +++ b/apps/docs/public/favicon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/apps/docs/src/assets/caplets-icon.png b/apps/docs/src/assets/caplets-icon.png new file mode 100644 index 00000000..4eebda4b Binary files /dev/null and b/apps/docs/src/assets/caplets-icon.png differ diff --git a/apps/docs/src/components/CapletsThemeProvider.astro b/apps/docs/src/components/CapletsThemeProvider.astro new file mode 100644 index 00000000..f46fe61a --- /dev/null +++ b/apps/docs/src/components/CapletsThemeProvider.astro @@ -0,0 +1,53 @@ +{/* This is intentionally inlined to avoid FOUC. */} + + + diff --git a/apps/docs/src/components/CapletsThemeSelect.astro b/apps/docs/src/components/CapletsThemeSelect.astro new file mode 100644 index 00000000..2a6d2b2d --- /dev/null +++ b/apps/docs/src/components/CapletsThemeSelect.astro @@ -0,0 +1,74 @@ +--- +import Select from "@astrojs/starlight/components/Select.astro"; +--- + + +