Skip to content

Commit 5e83ac6

Browse files
OmpragashOmpragash
authored
Publish complete agentctl documentation website (#1)
Publish the verified agentctl documentation site and its deterministic source importer.
2 parents d71dc4d + a01ba00 commit 5e83ac6

107 files changed

Lines changed: 14033 additions & 1 deletion

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/pages.yml‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
name: GitHub Pages
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
13+
concurrency:
14+
group: pages-${{ github.ref }}
15+
cancel-in-progress: true
16+
17+
env:
18+
NODE_VERSION: "24.4.1"
19+
PNPM_VERSION: "11.9.0"
20+
RUST_TOOLCHAIN: "1.88.0"
21+
22+
jobs:
23+
validate:
24+
runs-on: ubuntu-24.04
25+
defaults:
26+
run:
27+
shell: bash
28+
working-directory: site
29+
steps:
30+
- name: Check out Pages source
31+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
32+
with:
33+
path: site
34+
35+
- name: Check out canonical agentctl source
36+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
37+
with:
38+
repository: opensourceops/agentctl
39+
path: agentctl
40+
41+
- name: Install pinned Node.js
42+
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
43+
with:
44+
node-version: ${{ env.NODE_VERSION }}
45+
cache: pnpm
46+
cache-dependency-path: site/pnpm-lock.yaml
47+
48+
- name: Install pinned Rust and pnpm
49+
run: |
50+
set -euo pipefail
51+
rustup toolchain install "$RUST_TOOLCHAIN" --profile minimal --component rustfmt
52+
rustup default "$RUST_TOOLCHAIN"
53+
corepack enable
54+
corepack prepare "pnpm@$PNPM_VERSION" --activate
55+
56+
- name: Install site dependencies and browser
57+
run: |
58+
pnpm install --frozen-lockfile
59+
pnpm exec playwright install --with-deps chromium
60+
61+
- name: Verify canonical docs and final site artifact
62+
env:
63+
AGENTCTL_REPO: ${{ github.workspace }}/agentctl
64+
run: pnpm verify:agentctl
65+
66+
- name: Configure GitHub Pages
67+
if: github.event_name != 'pull_request'
68+
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
69+
70+
- name: Upload complete Pages artifact
71+
if: github.event_name != 'pull_request'
72+
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
73+
with:
74+
path: site/_site
75+
76+
deploy:
77+
if: github.event_name != 'pull_request'
78+
needs: validate
79+
runs-on: ubuntu-24.04
80+
permissions:
81+
pages: write
82+
id-token: write
83+
environment:
84+
name: github-pages
85+
url: ${{ steps.deployment.outputs.page_url }}
86+
steps:
87+
- name: Deploy GitHub Pages
88+
id: deployment
89+
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
node_modules/
2+
dist-agentctl/
3+
_site/
4+
.astro/
5+
playwright-report/
6+
test-results/
7+
.agentctl-docs-server.json

‎.markdownlint-cli2.jsonc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"config": {
3+
"MD013": false,
4+
"MD012": false,
5+
"MD024": { "siblings_only": true },
6+
"MD033": false,
7+
"MD041": false,
8+
"MD046": false
9+
},
10+
"ignores": [
11+
"node_modules/**",
12+
"dist-agentctl/**",
13+
"_site/**"
14+
]
15+
}

‎README.md‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,38 @@
1-
# opensourceops.github.io
1+
# OpenSourceOps GitHub Pages
2+
3+
This repository builds the organization root site and the public `agentctl` documentation at `/agentctl/`. Technical content is canonical in `opensourceops/agentctl`; a deterministic manifest imports it into an Astro and Starlight presentation layer.
4+
5+
## Prerequisites
6+
7+
- Node.js 22 or newer
8+
- pnpm 11.9.0 through Corepack
9+
- Rust 1.88.0 and Cargo
10+
- Playwright Chromium for the full browser gate
11+
- local checkouts of this repository and `agentctl`
12+
13+
Set `AGENTCTL_REPO` when the agentctl checkout is not in a documented sibling location.
14+
15+
## Local development
16+
17+
```text
18+
corepack enable
19+
pnpm install
20+
pnpm exec playwright install chromium
21+
AGENTCTL_REPO=/path/to/agentctl pnpm docs:sync
22+
pnpm dev:agentctl
23+
```
24+
25+
The development URL is `http://localhost:4321/agentctl/`. The development server makes no provider request, but dependency installation can use the package registry.
26+
27+
## Build and verify
28+
29+
```text
30+
AGENTCTL_REPO=/path/to/agentctl pnpm build
31+
AGENTCTL_REPO=/path/to/agentctl pnpm verify:agentctl
32+
```
33+
34+
`pnpm build` writes the complete Pages artifact to `_site`; serve that directory at its root and open `/agentctl/`. `pnpm verify:agentctl` is the canonical cross-repository gate. It runs `cargo xtask docs-verify`, synchronizes canonical content, checks writing, spelling, links, anchors, Mermaid, search, and generated freshness, builds the final artifact, then runs responsive Playwright and axe checks.
35+
36+
Common failures are a missing `AGENTCTL_REPO`, stale generated source or CLI references, a missing Playwright browser, or another process using port 4173. No verification command needs a provider API key.
37+
38+
See [deployment settings](docs/DEPLOYMENT.md) and the [documentation execution ledger](docs/execution/AGENTCTL_DOCS_STATUS.md).

‎astro.config.mjs‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
import { defineConfig } from 'astro/config';
2+
import starlight from '@astrojs/starlight';
3+
import mermaid from 'astro-mermaid';
4+
5+
const github = 'https://github.com/opensourceops/agentctl';
6+
7+
export default defineConfig({
8+
site: 'https://opensourceops.github.io',
9+
base: '/agentctl/',
10+
outDir: './dist-agentctl',
11+
integrations: [
12+
mermaid({
13+
autoTheme: true,
14+
enableLog: false,
15+
mermaidConfig: {
16+
securityLevel: 'strict',
17+
flowchart: { curve: 'linear', htmlLabels: false },
18+
},
19+
}),
20+
starlight({
21+
title: 'agentctl',
22+
description:
23+
'Declarative workflows for deterministic automation and bounded agent reasoning, with explicit policy and durable local state.',
24+
tagline: 'Deterministic workflows. Bounded agents. Durable evidence.',
25+
favicon: '/favicon.png',
26+
social: [{ icon: 'github', label: 'agentctl on GitHub', href: github }],
27+
editLink: { baseUrl: `${github}/edit/main/` },
28+
lastUpdated: false,
29+
pagination: true,
30+
pagefind: true,
31+
credits: false,
32+
customCss: ['./src/styles/custom.css'],
33+
components: {
34+
Header: './src/components/Header.astro',
35+
Footer: './src/components/Footer.astro',
36+
},
37+
head: [
38+
{ tag: 'meta', attrs: { name: 'theme-color', content: '#0f766e' } },
39+
{ tag: 'meta', attrs: { property: 'og:site_name', content: 'agentctl documentation' } },
40+
{ tag: 'meta', attrs: { property: 'og:type', content: 'website' } },
41+
{ tag: 'meta', attrs: { name: 'twitter:card', content: 'summary_large_image' } },
42+
{ tag: 'meta', attrs: { property: 'og:image', content: 'https://opensourceops.github.io/agentctl/og.png' } },
43+
{ tag: 'meta', attrs: { name: 'twitter:image', content: 'https://opensourceops.github.io/agentctl/og.png' } },
44+
{
45+
tag: 'script',
46+
attrs: { type: 'application/ld+json' },
47+
content: JSON.stringify({
48+
'@context': 'https://schema.org',
49+
'@type': 'WebSite',
50+
name: 'agentctl documentation',
51+
url: 'https://opensourceops.github.io/agentctl/',
52+
}),
53+
},
54+
],
55+
sidebar: [
56+
{
57+
label: 'Start here',
58+
items: [
59+
{ slug: 'overview', label: 'Overview', badge: 'v1alpha1' },
60+
{ slug: 'why-agentctl', label: 'Why agentctl' },
61+
{ slug: 'concepts/product', label: 'Product definition' },
62+
{ slug: 'getting-started/installation', label: 'Installation' },
63+
{ slug: 'getting-started', label: 'Getting started' },
64+
{ slug: 'getting-started/first-agent', label: 'First agent workflow' },
65+
{ slug: 'learning-paths', label: 'Learning paths' },
66+
{ slug: 'deployment-model', label: 'Choose a deployment model' },
67+
],
68+
},
69+
{
70+
label: 'Learn the workflow model',
71+
items: [
72+
{ slug: 'concepts/workflow-model', label: 'Workflow document' },
73+
{ slug: 'guides/workflow-authoring', label: 'Author workflows' },
74+
{ slug: 'concepts/tools', label: 'Actions, tools, and effects' },
75+
{ slug: 'concepts/policies', label: 'Policies and approvals' },
76+
{ slug: 'concepts/memory', label: 'Memory' },
77+
{ slug: 'concepts/packs', label: 'Packs' },
78+
],
79+
},
80+
{
81+
label: 'Run workflows',
82+
items: [
83+
{ slug: 'guides/local-operation', label: 'Local operation' },
84+
{ slug: 'durable-execution', label: 'Resume, replay, retry, and fork' },
85+
{ slug: 'operations/scheduled', label: 'Scheduled execution' },
86+
],
87+
},
88+
{
89+
label: 'Operate agentctl',
90+
items: [
91+
{ slug: 'guides/container', label: 'Container' },
92+
{ slug: 'guides/ci-cd', label: 'CI/CD and Kubernetes' },
93+
{ slug: 'observability', label: 'Logs and observability' },
94+
{ slug: 'reference/database', label: 'State, locking, and retention' },
95+
],
96+
},
97+
{
98+
label: 'Providers and protocols',
99+
items: [
100+
{ slug: 'providers', label: 'Provider overview' },
101+
{ slug: 'reference/capabilities', label: 'Capability matrices' },
102+
{ slug: 'providers/mcp', label: 'MCP' },
103+
{ slug: 'providers/a2a', label: 'A2A' },
104+
{ slug: 'reference/environment', label: 'Authentication and environment' },
105+
],
106+
},
107+
{
108+
label: 'Security',
109+
items: [
110+
{ slug: 'security', label: 'Security model' },
111+
{ slug: 'security/threat-model', label: 'Threat model' },
112+
{ slug: 'concepts/policies', label: 'Filesystem, process, and network policy' },
113+
{ slug: 'reference/limitations', label: 'Known limitations' },
114+
],
115+
},
116+
{
117+
label: 'Examples and use cases',
118+
items: [
119+
{ slug: 'examples', label: 'Examples overview' },
120+
{ slug: 'examples/repository-audit', label: 'Repository audit' },
121+
{ slug: 'examples/release-readiness', label: 'Release readiness' },
122+
{ slug: 'examples/scheduled-review', label: 'Scheduled review' },
123+
{ slug: 'examples/ci-quality-gate', label: 'CI quality gate' },
124+
{ slug: 'examples/approval-gated', label: 'Approval-gated action' },
125+
{ slug: 'examples/recorded-replay', label: 'Recorded replay' },
126+
{ slug: 'examples/provider-portability', label: 'Provider portability' },
127+
],
128+
},
129+
{
130+
label: 'Troubleshooting',
131+
items: [{ slug: 'troubleshooting', label: 'Problem-solving guide' }],
132+
},
133+
{
134+
label: 'Reference',
135+
items: [
136+
{ slug: 'reference/cli', label: 'CLI reference' },
137+
{ slug: 'reference/yaml', label: 'YAML reference' },
138+
{ slug: 'reference/output', label: 'Output and exit codes' },
139+
{ slug: 'reference/environment', label: 'Environment and default paths' },
140+
{ slug: 'reference/capabilities', label: 'Provider and tool matrices' },
141+
{ slug: 'reference/database', label: 'Database and migrations' },
142+
{ slug: 'reference/terminology', label: 'Terminology' },
143+
{ slug: 'reference/compatibility', label: 'Compatibility' },
144+
{ slug: 'reference/migration', label: 'Migrate from TypeScript' },
145+
{ slug: 'reference/limitations', label: 'Limitations' },
146+
],
147+
},
148+
{
149+
label: 'Architecture',
150+
items: [
151+
{ slug: 'architecture', label: 'Architecture overview' },
152+
{ slug: 'architecture/diagrams', label: 'Architecture diagrams' },
153+
{
154+
label: 'Design decisions',
155+
items: ['architecture/decisions/0001', 'architecture/decisions/0002', 'architecture/decisions/0003', 'architecture/decisions/0004', 'architecture/decisions/0005', 'architecture/decisions/0006', 'architecture/decisions/0007'],
156+
},
157+
],
158+
},
159+
{
160+
label: 'Contributing',
161+
items: [
162+
{ slug: 'contributing', label: 'Contributor guide' },
163+
{ slug: 'contributing/developer-guide', label: 'Developer guide' },
164+
{ slug: 'contributing/testing', label: 'Build and test' },
165+
{ slug: 'contributing/add-action', label: 'Add an action or tool' },
166+
{ slug: 'contributing/add-provider', label: 'Add a provider' },
167+
{ slug: 'contributing/add-migration', label: 'Add a migration' },
168+
{ slug: 'contributing/documentation', label: 'Write documentation' },
169+
{ slug: 'contributing/release', label: 'Release process' },
170+
],
171+
},
172+
],
173+
}),
174+
],
175+
});

‎cspell.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"version": "0.2",
3+
"language": "en",
4+
"useGitignore": true,
5+
"ignorePaths": [
6+
"pnpm-lock.yaml",
7+
"docs/execution/**",
8+
"src/content/docs/_generated/reference/cli.md",
9+
"public/downloads/workflow.schema.json"
10+
],
11+
"words": [
12+
"agentctl", "OpenSourceOps", "Starlight", "Astro", "Pagefind", "Playwright",
13+
"Anthropic", "Gemini", "OpenAI", "A2A", "MCP", "SQLite", "JSONL", "OCI",
14+
"Kubernetes", "CronJob", "systemd", "runbook", "allowlist", "allowlists",
15+
"idempotency", "idempotent", "toolchain", "checkpoints", "subprocess",
16+
"worktree", "rustls", "Clippy", "Rustfmt", "CycloneDX", "Gitleaks", "Trivy",
17+
"Cargo", "SHA", "v1alpha1", "tmpfs", "noexec", "nosuid", "runAsNonRoot",
18+
"fsGroup", "backoffLimit", "concurrencyPolicy", "apiVersion", "prev", "frontmatter",
19+
"astrojs", "basenames", "checkpointed", "checksummed", "Containerfile", "distroless",
20+
"effectful", "exfiltration", "inspectable", "ledgered", "lockfiles", "misexecutes",
21+
"msvc", "noninteractive", "nonroot", "oneshot", "proptest", "rustdoc", "sandboxing",
22+
"schedulable", "Streamable", "subpaths", "TOCTOU", "transactionally", "uncheckpointed",
23+
"unpushed", "xtask", "MSRV", "nojekyll", "accDescr"
24+
]
25+
}

‎docs/DEPLOYMENT.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# GitHub Pages deployment
2+
3+
The workflow in `.github/workflows/pages.yml` validates pull requests and deploys only from `main` or a manual dispatch. It checks out both repositories, runs the credential-free canonical and site gates, assembles `_site`, verifies `agentctl/index.html`, and uses GitHub's current Pages artifact deployment actions.
4+
5+
## Required repository settings after merge
6+
7+
1. Open the `opensourceops/opensourceops.github.io` repository settings.
8+
2. Under **Pages**, set **Source** to **GitHub Actions**.
9+
3. Keep the public custom domain empty unless OpenSourceOps intentionally adds one later.
10+
4. Under **Actions**, allow GitHub-owned actions. No provider secret is required.
11+
5. Protect `main` according to the organization's normal policy and require the `validate` job if desired.
12+
6. Run the workflow manually once, or merge a validated change to `main`.
13+
7. Confirm the deployment environment reports `https://opensourceops.github.io/` and verify `https://opensourceops.github.io/agentctl/` separately.
14+
15+
Do not configure Pages to deploy from a branch directory. The workflow uploads the complete `_site` artifact, including the organization root, `.nojekyll`, and the `agentctl/` subdirectory.
16+
17+
## Security model
18+
19+
Pull requests receive read-only repository permission and never reach the deployment job. The deployment job alone receives `pages: write` and `id-token: write`. The workflow does not read provider credentials or repository secrets. All action references are immutable commit SHAs with release annotations.

‎docs/execution/AGENTCTL_DOCS_CONTENT_MATRIX.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# agentctl documentation content matrix
2+
3+
| User question | Persona | Public page | Canonical source | Working example | Verification | Status |
4+
| --- | --- | --- | --- | --- | --- | --- |
5+
| What is agentctl and why use it? | evaluator | homepage, overview, why agentctl | `docs/PRODUCT.md` | `examples/acceptance/mock-tool` | site copy review, example gate | complete |
6+
| How do I install it? | new user | installation | `docs/guides/INSTALLATION.md` | `examples/v1/hello.yaml` | source install smoke | complete |
7+
| How do I finish a first run? | new user | getting started | `docs/guides/GETTING_STARTED.md` | `examples/v1/hello.yaml` | clean-directory run | complete |
8+
| How do I try an agent without a key? | new user | first agent workflow | `docs/guides/FIRST_AGENT_WORKFLOW.md` | `examples/acceptance/mock-tool` | clean-directory fake-provider run | complete |
9+
| How does workflow YAML fit together? | workflow author | workflow authoring, YAML reference | `docs/DSL.md`, `docs/reference/YAML.md` | `examples/v1/dataflow.yaml` | check and plan | complete |
10+
| How do I run and recover locally? | operator | local operation, durable execution | `docs/OPERATIONS.md`, `docs/DURABLE_EXECUTION.md` | `examples/v1/crash-resume.yaml` | runtime and acceptance tests | complete |
11+
| How do I use a container? | platform engineer | container | `docs/CONTAINER.md` | acceptance mock tool | locally executed container acceptance | complete |
12+
| How do I use CI or Kubernetes? | platform engineer | CI/CD | `docs/guides/CI_CD.md`, `docs/CONTAINER.md` | checked snippets | syntax and documentation review | complete |
13+
| How should I schedule runs? | operator | scheduled execution | `docs/OPERATIONS.md` | cron, systemd, CronJob | documentation review | complete |
14+
| Which provider can do what? | workflow author | providers | `docs/PROVIDERS.md` | `examples/v1/*-live.yaml` | mock protocol and opt-in live gates | complete |
15+
| How do MCP and A2A behave? | integrator | protocols | `docs/MCP.md`, `docs/A2A.md` | `examples/v1/mcp.yaml`, `a2a.yaml` | local mock servers | complete |
16+
| What is persisted and why? | operator | stateful architecture | `docs/DURABLE_EXECUTION.md`, `docs/MEMORY.md` | crash/resume and memory examples | store/runtime tests | complete |
17+
| How do I diagnose a failed run? | operator | troubleshooting, observability | `docs/guides/TROUBLESHOOTING.md`, `docs/OBSERVABILITY.md` | failure fixtures | exit and inspection tests | complete |
18+
| What are the security boundaries? | security reviewer | security, threat model | `docs/SECURITY.md`, `docs/THREAT_MODEL.md` | policy denial and approval | security and policy tests | complete |
19+
| How do I add runtime behavior? | contributor | developer guides | `docs/development/*` | focused Rust tests | cargo tests and docs gate | complete |
20+
| What is not supported? | evaluator | limitations and compatibility | `docs/LIMITATIONS.md`, `docs/COMPATIBILITY.md` | capability failure | negative contract tests | complete |

0 commit comments

Comments
 (0)