diff --git a/.github/workflows/docs-lint.yml b/.github/workflows/docs-lint.yml new file mode 100644 index 0000000000..361c30e747 --- /dev/null +++ b/.github/workflows/docs-lint.yml @@ -0,0 +1,49 @@ +name: Docs Lint + +on: + pull_request: + paths: + - 'docs/**' + +jobs: + lint: + name: Lint Documentation + runs-on: ubuntu-latest + timeout-minutes: 5 + + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: '22' + cache: 'npm' + cache-dependency-path: docs/package-lock.json + + - name: Install Vale + run: | + curl -sfL https://github.com/errata-ai/vale/releases/download/v3.12.1/vale_3.12.1_Linux_64-bit.tar.gz | tar xz -C /usr/local/bin vale + + - name: Install npm tools + run: npm install -g markdownlint-cli2 cspell + + - name: Run Vale + working-directory: docs + run: vale src/content/docs/ + + - name: Run markdownlint + working-directory: docs + run: markdownlint-cli2 "src/content/docs/**/*.md" + + - name: Run cspell + working-directory: docs + run: cspell lint --no-progress "src/content/docs/**/*.md" + + - name: Build docs (structural validation) + working-directory: docs + run: | + npm ci + npx playwright install --with-deps chromium + npm run build diff --git a/Makefile b/Makefile index a7aab15c32..48d6f045b5 100755 --- a/Makefile +++ b/Makefile @@ -966,6 +966,18 @@ test-e2e-setup: ## Install e2e test dependencies e2e-setup: test-e2e-setup ## Alias for test-e2e-setup (backward compatibility) +##@ Documentation Quality + +docs-lint: ## Lint documentation content (Vale + markdownlint + cspell) + @echo "$(COLOR_BLUE)▶$(COLOR_RESET) Linting documentation..." + @cd docs && vale src/content/docs/ && \ + echo "$(COLOR_GREEN)✓$(COLOR_RESET) Vale passed" + @cd docs && npx markdownlint-cli2 "src/content/docs/**/*.md" && \ + echo "$(COLOR_GREEN)✓$(COLOR_RESET) markdownlint passed" + @cd docs && npx cspell lint --no-progress "src/content/docs/**/*.md" && \ + echo "$(COLOR_GREEN)✓$(COLOR_RESET) cspell passed" + @echo "$(COLOR_GREEN)✓$(COLOR_RESET) All docs lint checks passed" + ##@ Documentation Screenshots screenshots: ## Capture documentation screenshots against running kind cluster diff --git a/docs/.cspell.json b/docs/.cspell.json new file mode 100644 index 0000000000..53bf2bcfe9 --- /dev/null +++ b/docs/.cspell.json @@ -0,0 +1,113 @@ +{ + "version": "0.2", + "language": "en", + "ignorePaths": [ + "node_modules", + "dist", + ".astro", + "public/images" + ], + "ignoreRegExpList": [ + "/```[\\s\\S]*?```/g", + "/(https?://[^\\s)]+)/g", + "/`[^`]+`/g", + "/\\{[^}]+\\}/g" + ], + "words": [ + "acpctl", + "agentready", + "agenticsessions", + "Ambient", + "Amber", + "Anthropic", + "Archie", + "Astro", + "Atlassian", + "autoscaling", + "backoff", + "buildx", + "cadence", + "CORS", + "coderabbit", + "codeready", + "colocation", + "ConfigMap", + "ConfigMaps", + "CronJob", + "CronJobs", + "cspell", + "Cypress", + "frontmatter", + "gofmt", + "golangci", + "Grafana", + "Haiku", + "HTTPS", + "idempotency", + "integrations", + "Jira", + "Kustomize", + "Kubernetes", + "Langfuse", + "Langsmith", + "LangChain", + "langgraph", + "markdownlint", + "mcp", + "Milvus", + "MinIO", + "mkdir", + "monospace", + "namespace", + "namespaces", + "Netlify", + "NextJS", + "OAuth", + "Olivia", + "onboarding", + "OpenShift", + "Opus", + "parallelizable", + "projectsettings", + "Playwright", + "preconfigured", + "Prometheus", + "provisioning", + "quickstart", + "RBAC", + "readability", + "reachable", + "reconciler", + "reconcilers", + "reconciliation", + "rehype", + "remark", + "Rollback", + "rfes", + "rollout", + "RoleBinding", + "repo", + "repos", + "screenshot", + "screenshots", + "Shadcn", + "slugified", + "speedrun", + "Sonnet", + "Starlight", + "subagent", + "subagents", + "Tailscale", + "teardown", + "templated", + "TypeScript", + "unattended", + "automatable", + "uncomitted", + "unmount", + "viewport", + "worktree", + "worktrees", + "YAML" + ] +} diff --git a/docs/.markdownlint.json b/docs/.markdownlint.json new file mode 100644 index 0000000000..7d6357d802 --- /dev/null +++ b/docs/.markdownlint.json @@ -0,0 +1,15 @@ +{ + "default": true, + "MD013": false, + "MD025": false, + "MD033": { + "allowed_elements": ["figure", "img", "br", "details", "summary", "Badge"] + }, + "MD036": false, + "MD040": false, + "MD041": false, + "MD024": { + "siblings_only": true + }, + "MD060": false +} diff --git a/docs/.vale.ini b/docs/.vale.ini new file mode 100644 index 0000000000..47b33c2f66 --- /dev/null +++ b/docs/.vale.ini @@ -0,0 +1,8 @@ +StylesPath = .vale/styles + +MinAlertLevel = suggestion + +Vocab = ACP + +[*.md] +BasedOnStyles = ACP diff --git a/docs/.vale/styles/ACP/ActiveVoice.yml b/docs/.vale/styles/ACP/ActiveVoice.yml new file mode 100644 index 0000000000..5eaff29b7d --- /dev/null +++ b/docs/.vale/styles/ACP/ActiveVoice.yml @@ -0,0 +1,26 @@ +extends: existence +message: "Prefer active voice. '%s' is passive." +level: suggestion +ignorecase: true +tokens: + - 'is created by' + - 'is managed by' + - 'is handled by' + - 'is configured by' + - 'is controlled by' + - 'is provided by' + - 'is defined by' + - 'is required by' + - 'is supported by' + - 'is determined by' + - 'was created' + - 'was configured' + - 'was deleted' + - 'was removed' + - 'was updated' + - 'were created' + - 'were configured' + - 'were deleted' + - 'can be accessed by' + - 'should be configured by' + - 'must be set by' diff --git a/docs/.vale/styles/ACP/HeadingStyle.yml b/docs/.vale/styles/ACP/HeadingStyle.yml new file mode 100644 index 0000000000..bf3627b8d5 --- /dev/null +++ b/docs/.vale/styles/ACP/HeadingStyle.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't end headings with punctuation: '%s'." +level: error +scope: heading +nonword: true +tokens: + - '[.!?;:]$' diff --git a/docs/.vale/styles/ACP/Jargon.yml b/docs/.vale/styles/ACP/Jargon.yml new file mode 100644 index 0000000000..3fe6834263 --- /dev/null +++ b/docs/.vale/styles/ACP/Jargon.yml @@ -0,0 +1,14 @@ +extends: existence +message: "Consider explaining '%s' on first use or linking to a glossary." +level: suggestion +ignorecase: false +nonword: true +tokens: + - '\bCRDs?\b' + - '\bRBAC\b' + - '\bPATs?\b' + - '\bMCP\b' + - '\bAG-UI\b' + - '\bCR\b' + - '\bPVC\b' + - '\bHPA\b' diff --git a/docs/.vale/styles/ACP/Readability.yml b/docs/.vale/styles/ACP/Readability.yml new file mode 100644 index 0000000000..d9dbf969fe --- /dev/null +++ b/docs/.vale/styles/ACP/Readability.yml @@ -0,0 +1,6 @@ +extends: readability +message: "Reading level is grade %s. Aim for grade 12 or lower." +level: suggestion +metrics: + - Flesch-Kincaid +grade: 12 diff --git a/docs/.vale/styles/ACP/SentenceLength.yml b/docs/.vale/styles/ACP/SentenceLength.yml new file mode 100644 index 0000000000..28d4fd415e --- /dev/null +++ b/docs/.vale/styles/ACP/SentenceLength.yml @@ -0,0 +1,6 @@ +extends: occurrence +message: "Sentence has %s words. Try to keep sentences under 30 words." +level: warning +scope: sentence +max: 30 +token: '\b\w+\b' diff --git a/docs/.vale/styles/ACP/Terminology.yml b/docs/.vale/styles/ACP/Terminology.yml new file mode 100644 index 0000000000..596bf580de --- /dev/null +++ b/docs/.vale/styles/ACP/Terminology.yml @@ -0,0 +1,9 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +level: error +ignorecase: true +swap: + vTeam: ACP + v-team: ACP + vteam platform: Ambient Code Platform + the vteam: ACP diff --git a/docs/.vale/styles/config/vocabularies/ACP/accept.txt b/docs/.vale/styles/config/vocabularies/ACP/accept.txt new file mode 100644 index 0000000000..eecce14431 --- /dev/null +++ b/docs/.vale/styles/config/vocabularies/ACP/accept.txt @@ -0,0 +1,67 @@ +ACP +acpctl +Ambient +Amber +AgentReady +Anthropic +Archie +Astro +Atlassian +Bailey +Bitbucket +Casey +CLI +Claude +ConfigMap +CRD +CRC +Cypress +Dan +Diego +Docker +Emma +Felix +Gemini +GitHub +GitLab +Grafana +Haiku +Jira +Kustomize +Kubernetes +Langfuse +LangChain +Langsmith +Lee +LLM +MinIO +MCP +Morgan +Neil +Netlify +NextJS +OAuth +Olivia +OpenShift +Opus +PAT +Parker +Playwright +Prometheus +Quinn +RBAC +REST +RFE +Riley +Ryan +Shadcn +Sonnet +SSO +Starlight +Stella +Steve +Tailscale +Terry +Tessa +TypeScript +Uma diff --git a/docs/.vale/styles/config/vocabularies/ACP/reject.txt b/docs/.vale/styles/config/vocabularies/ACP/reject.txt new file mode 100644 index 0000000000..d179218ef7 --- /dev/null +++ b/docs/.vale/styles/config/vocabularies/ACP/reject.txt @@ -0,0 +1,3 @@ +vTeam +v-team +vteam diff --git a/docs/src/content/docs/concepts/workspaces.md b/docs/src/content/docs/concepts/workspaces.md index c27feb237a..bc055c3119 100644 --- a/docs/src/content/docs/concepts/workspaces.md +++ b/docs/src/content/docs/concepts/workspaces.md @@ -127,7 +127,7 @@ Choose a token lifetime based on your use case: | 1 year | 31,536,000 | Long-running integrations | | No expiration | -- | Persistent service keys that you rotate manually | -4. Click **Create Key**. +1. Click **Create Key**. ### Copying the key diff --git a/docs/src/content/docs/features/session-sharing.md b/docs/src/content/docs/features/session-sharing.md index e8a0e9c19c..287da72f70 100644 --- a/docs/src/content/docs/features/session-sharing.md +++ b/docs/src/content/docs/features/session-sharing.md @@ -17,6 +17,7 @@ When multiple users collaborate in a shared session, **each message uses the sen | Shared session | User A | User B | User B | **Example:** + - User A creates a session and adds User B as an editor - Both User A and User B have configured their GitHub integrations - User A sends "Create a PR" -- the PR is created using User A's GitHub token @@ -25,10 +26,12 @@ When multiple users collaborate in a shared session, **each message uses the sen ### Automated Sessions **API Keys:** Always use the **creator's credentials** (the user who created the API key). + - GitHub commits show the creator's username - The creator is responsible for all actions performed via their API key **Scheduled Sessions:** Always use the **creator's credentials** (the user who scheduled the session). + - The session runs as the creating user even when they are offline - The creator is accountable for all scheduled session behavior diff --git a/docs/src/content/docs/guides/migrating-shared-sessions.md b/docs/src/content/docs/guides/migrating-shared-sessions.md index 70ffe868f0..3498218d4d 100644 --- a/docs/src/content/docs/guides/migrating-shared-sessions.md +++ b/docs/src/content/docs/guides/migrating-shared-sessions.md @@ -12,6 +12,7 @@ description: How to update existing shared sessions for per-message credential b ## Impact If you have shared sessions created before this update: + - Messages sent by editors will now use **their own credentials** instead of the session owner's - If an editor has not configured the required integrations, operations that need those credentials will fail diff --git a/docs/src/content/docs/workflows/spec-kit.md b/docs/src/content/docs/workflows/spec-kit.md index 6eea35a7d1..d1dd0a121c 100644 --- a/docs/src/content/docs/workflows/spec-kit.md +++ b/docs/src/content/docs/workflows/spec-kit.md @@ -39,6 +39,7 @@ The workflow provides a set of slash commands that map to distinct phases: The Spec-kit workflow has access to a roster of 21 specialized sub-agents that it engages automatically based on the phase and complexity. Key agents include: **Engineering and architecture:** + - **Archie (Architect)** -- System design, technical vision, architectural patterns. - **Stella (Staff Engineer)** -- Technical leadership, implementation excellence, code review. - **Neil (Test Engineer)** -- Testing strategy, QA, test automation. @@ -46,18 +47,21 @@ The Spec-kit workflow has access to a roster of 21 specialized sub-agents that i - **Emma (Engineering Manager)** -- Engineering management and capacity planning. **Product and strategy:** + - **Parker (Product Manager)** -- Market strategy, customer feedback, business value. - **Olivia (Product Owner)** -- Backlog management, user stories, sprint planning. - **Dan (Senior Director)** -- Strategic direction and executive alignment. - **Diego (Program Manager)** -- Cross-team program management. **UX and design:** + - **Aria (UX Architect)** -- UX strategy, journey mapping, design system architecture. - **Felix (UX Feature Lead)** -- Feature-level UX design, interaction design. - **Steve (UX Designer)** -- Visual design and interaction patterns. - **Uma (UX Team Lead)** -- UX team coordination. **Content and documentation:** + - **Terry (Technical Writer)** -- Technical documentation standards. - **Tessa (Writing Manager)** -- Writing quality and editorial oversight. - **Casey (Content Strategist)** -- Content strategy and information architecture.