diff --git a/.agents/skills/update-lifecycle-docs/SKILL.md b/.agents/skills/update-lifecycle-docs/SKILL.md new file mode 100644 index 00000000..5491b1e9 --- /dev/null +++ b/.agents/skills/update-lifecycle-docs/SKILL.md @@ -0,0 +1,100 @@ +--- +name: update-lifecycle-docs +description: Update, correct, reorganize, or review Lifecycle's end-user MDX documentation and UI screenshots. Use for source-PR documentation impact, new or changed product behavior, configuration/schema/API/CLI synchronization, troubleshooting guides, navigation changes, screenshot capture or refresh, and docs drift audits in lifecycle-docs. +--- + +# Update Lifecycle Docs + +Follow the repository `AGENTS.md` throughout this workflow. + +## Classify the Work + +For an upstream change, choose one: + +- **No docs needed:** internal-only behavior with no user, API, configuration, installation, or interface impact. +- **Docs needed:** a user-visible behavior, workflow, contract, default, command, route, or support boundary changed. +- **Uncertain:** the authoritative source does not establish the user impact. + +Do not manufacture a docs change for the first case. For the third, identify the missing product decision or evidence instead of guessing. + +## Update Workflow + +1. **Choose the user and task.** + + - Name the reader: evaluator, application developer, platform operator, Agent user, or administrator. + - State the outcome the page must help them reach. + +2. **Find the owning contract.** + + - Use the source routing in `AGENTS.md`. + - Inspect implementation, schema, OpenAPI/validators, CLI registration, chart values, or live UI as appropriate. + - Record the commit or PR used for verification. + - Surface contradictions between sources before editing. + - Treat support status as a product decision. If source code and the live UI + do not establish it, record the question for the product owner. + +3. **Assess the existing journey.** + + - Read the target page, neighboring pages, navigation metadata, and incoming/outgoing links. + - Prefer correcting an existing page. + - Create a new page only for a distinct user task or audience. + +4. **Author for task completion.** + + - Lead with the outcome. + - Add prerequisites and support/feature status before the procedure. + - Use the smallest safe sequence with tested examples. + - Add observable success criteria, recovery, troubleshooting, and the next action. + - Keep reference tables separate from task guidance when either becomes hard to scan. + +5. **Decide whether a screenshot helps.** + + - Use a screenshot only when recognizing a page/state, locating an action, or understanding a dense UI materially improves success. + - For screenshot work, read `references/screenshots.md` completely before capture. + - Prefer a diagram for concepts and selectable text for code, commands, schemas, or payloads. + - Get user authorization before creating a fixture PR or otherwise changing + external repository state. + +6. **Keep navigation coherent.** + + - Update the nearest `_meta.ts` when adding, moving, or renaming a page. + - Run generated metadata steps through the normal build. + - Review generated changes and links rather than accepting churn blindly. + +7. **Verify content and rendering.** + + - Validate examples against the owning schema, CLI, API, or chart. + - Format changed files only. + - Run `bun run verify`. + - Inspect every changed route in desktop Chrome. + - Check every theme enabled in `src/theme.config.tsx`; the current site + forces the dark theme. + +8. **Prepare the handoff.** + - Summarize the reader task, authoritative evidence, changed routes, validation, and remaining uncertainty. + - Record screenshot fixture and cleanup when applicable. + - Create a docs PR only when authorized; never merge it without explicit authorization. + +## Page Shape + +Use this order when it fits the task: + +1. Outcome +2. Audience, prerequisites, and support status +3. Procedure +4. Verify the result +5. Recover or roll back +6. Troubleshoot +7. Next steps +8. Version/owner last verified + +Do not force headings that add no value, but do not omit safety, verification, or recovery when the workflow changes state. + +## Safety and Accuracy + +- Do not infer public support from code acceptance alone. +- Do not describe Labs or admin-gated controls as universally available. +- Do not publish private values, credentials, unrestricted examples, or destructive shortcuts. +- Do not silently reconcile conflicting contracts. Report the conflict and identify the owner. +- Do not add placeholders or TODO-only pages to navigation. +- Do not preserve obsolete terminology merely because an old page uses it. diff --git a/.agents/skills/update-lifecycle-docs/agents/openai.yaml b/.agents/skills/update-lifecycle-docs/agents/openai.yaml new file mode 100644 index 00000000..3df0d105 --- /dev/null +++ b/.agents/skills/update-lifecycle-docs/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Update Lifecycle Docs" + short_description: "Update Lifecycle docs and UI screenshots" + default_prompt: "Use $update-lifecycle-docs to update Lifecycle documentation and refresh any relevant UI screenshots." diff --git a/.agents/skills/update-lifecycle-docs/references/screenshots.md b/.agents/skills/update-lifecycle-docs/references/screenshots.md new file mode 100644 index 00000000..7c50c781 --- /dev/null +++ b/.agents/skills/update-lifecycle-docs/references/screenshots.md @@ -0,0 +1,170 @@ +# Lifecycle documentation screenshots + +Use this reference only when adding, replacing, or reviewing UI screenshots. + +## Contents + +- [When a screenshot is worth maintaining](#when-a-screenshot-is-worth-maintaining) +- [Capture standard](#capture-standard) +- [Fixture workflow](#fixture-workflow) +- [Asset placement and accessibility](#asset-placement-and-accessibility) +- [Screenshot catalog](#screenshot-catalog) +- [Capture checklist](#capture-checklist) + +## When a Screenshot Is Worth Maintaining + +Use a screenshot when it materially helps a reader: + +- Recognize a page, dialog, or state +- Find an action in a dense interface +- Distinguish success, pending, and failure states +- Understand the relationship between an Environment, its Services, logs, or Agent activity + +Do not use a screenshot for: + +- Code, terminal commands, schemas, or API payloads +- Conceptual architecture that a diagram explains more clearly +- Decorative proof that a feature exists +- Rapidly changing Labs controls unless the page names the status and the catalog has a refresh owner + +Keep the smallest screenshot set that explains the journey. + +## Capture Standard + +- Use the running local Lifecycle UI in desktop Chrome through Chrome DevTools. +- In the standard local workspace, verify the UI at `http://localhost:3000`. + Follow the workspace operations guide and `lifecycle-ui/AGENTS.md` to start or + authenticate it; do not invent credentials or bypass authentication. +- Set the viewport to 1440×900 at device scale factor 1 and browser zoom 100%. +- Use the light theme for the current screenshot series. +- Set `labs=true` before capturing Labs-gated surfaces. +- Wait for loading, transitions, toasts, and live updates to settle. +- Prefer a component or application-region capture. Keep enough surrounding UI for orientation. +- Use viewport position or element capture instead of editing pixels afterward. +- Do not bake arrows, labels, or explanatory text into the bitmap; put explanation in prose and captions. +- Do not use generative image editing on product screenshots. +- Capture PNG for UI text. Optimize only when legibility and dimensions remain unchanged. +- Keep raw captures in task scratch; only reviewed images belong in `public/`. +- If Chrome DevTools cannot persist a file, capture the returned image bytes exactly through a trusted local tool. Do not re-render or transform the UI. +- Prefer neutral fixture values at the source. If an authorized private + fixture's identity is incidental and cannot be avoided, replace only + identity-bearing DOM text and links before capture. Record the substitutions + in task scratch, never alter product labels, statuses, controls, or messages, + and re-inspect the final image. + +Use neutral fixtures. Exclude or avoid: + +- Tokens, secrets, environment-variable values, and one-time credentials +- Personal names, avatars, emails, and private repository ownership +- Internal cluster identifiers or unrelated local resources +- Incidental timestamps, random identifiers, and hostnames when they do not teach the task +- Browser chrome, developer-tool overlays, unrelated tabs, and transient notifications + +Crop or choose a narrower UI region rather than blurring. If a user-facing identifier is necessary to explain the task, use a neutral fixture value. + +## Fixture Workflow + +Use only a fixture repository explicitly authorized for the task. In the +standard personal workspace, the root workspace instructions may name one. +Resolve its actual GitHub identity from the local worktree instead of recording +a private repository or owner in tracked documentation: + +```sh +git -C remote get-url origin +gh repo view / --json nameWithOwner,defaultBranchRef,viewerPermission +``` + +Before mutation: + +1. Confirm that the user authorized creating a PR and changing external + repository state for the capture. +2. Inspect the exact repository, worktree status, existing worktrees, open PRs, and current `lifecycle.yaml`. +3. Never switch the user's existing checkout or reuse, close, or modify a pre-existing PR. +4. Create a unique branch in a temporary git worktree from `origin/main`. +5. Use one minimal Service and a neutral PR title. +6. Never merge a fixture PR. +7. Record the branch, PR, Environment UUID, and cleanup status in task scratch. + +Use this minimal healthy manifest when the current schema still validates it: + +```yaml +--- +version: "2.1.0" + +environment: + autoDeploy: false + defaultServices: + - name: web + +services: + - name: web + docker: + dockerImage: nginx + defaultTag: 1.27.4-alpine + ports: + - 80 + deployment: + public: true + resource: + cpu: + request: 10m + memory: + request: 50Mi + readiness: + tcpSocketPort: 80 +``` + +Validate it against the current Lifecycle schema before use. Apply `lifecycle-deploy!` and, only when needed, `lifecycle-status-comments!`. + +To produce a deterministic image/deploy failure after capturing the healthy state, change only the tag to a clearly nonexistent value and push another commit. For a distinct build failure, use a GitHub Service with a deliberately missing Dockerfile path only after validating that fixture against the current schema. + +Cleanup order: + +1. Verify the PR's head branch exactly matches the recorded fixture branch. +2. Close the PR without deleting the branch. +3. Wait for teardown and confirm the Environment namespace is gone. +4. Delete only the recorded remote branch. +5. Remove the temporary worktree. +6. Attempt to delete the local branch with `git branch -d`. A fixture branch + from an unmerged, closed PR may require `git branch -D`; before doing that, + re-verify its exact name and commit against the task record and confirm the + remote branch and Environment are already gone. +7. Stop if cleanup finds unexpected changes or a target mismatch. + +Long term, prefer a dedicated GoodRx-owned public documentation fixture repository. The private shared test repository is suitable for controlled local captures but creates avoidable ownership and accumulated-state noise. + +## Asset Placement and Accessibility + +- Mirror the page route under `public/docs/`; for example, a screenshot for `/docs/troubleshooting/deploy-issues` belongs under `public/docs/troubleshooting/deploy-issues/`. +- Use a descriptive, stable filename such as `service-deploy-failure.png`, not a UUID or date. +- Add explicit `width`, `height`, and `ratio` to ``. +- Write alt text that explains the information contributed by the image, not every visible control. +- Keep all operational instructions in nearby text so the page remains usable without the image. +- Add a caption when the state, scope, or support status is not obvious. + +## Screenshot Catalog + +Update this table whenever a tracked screenshot is added or refreshed. + +| Asset | Docs page | User point | UI route/state | Fixture | Viewport/theme | UI commit | Last verified | +| ----------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------ | ------------- | +| `/docs/getting-started/explore-environment/environment-ready.png` | `/docs/getting-started/explore-environment` | Recognize a ready Environment and Service | `/environments/`, selected Service Summary, `Deployed` / `Ready` | Temporary authorized private fixture; one Docker Service; identity values neutralized; cleaned up | 1440×900 / light | `b1df0cd64b4680fb241364be6cab985a2dce1f4f` | 2026-07-24 | +| `/docs/troubleshooting/deploy-issues/service-deploy-failure.png` | `/docs/troubleshooting/deploy-issues` | Recognize failure signals and find the first failure reason | `/environments/`, selected Service Summary, `Error` / `Deploy failed` | Temporary authorized private fixture; nonexistent Docker image tag; identity values neutralized; cleaned up | 1440×900 / light | `b1df0cd64b4680fb241364be6cab985a2dce1f4f` | 2026-07-24 | + +The images under `public/getting-started/` predate this catalog. Treat their +fixture, source revision, and freshness as unknown until they are recaptured or +explicitly verified. + +## Capture Checklist + +- [ ] The screenshot teaches a point that text or a diagram cannot communicate as well. +- [ ] The owning UI behavior was verified in the running app. +- [ ] The fixture is neutral, minimal, and recorded. +- [ ] Loading, animation, and transient UI have settled. +- [ ] No secret, personal, private, or unrelated data is visible. +- [ ] The crop retains enough context for orientation. +- [ ] Alt text and adjacent instructions carry the same essential meaning. +- [ ] The asset path and catalog entry are updated. +- [ ] The rendered page was checked in every theme enabled by + `src/theme.config.tsx` (currently dark only). +- [ ] Temporary PR, branch, Environment, Site, or session state was cleaned up. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index cf9884aa..f5758461 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,11 +1,23 @@ -## Fixes +## Reader and task -- Fixes # +- Audience: +- Task/outcome: -## Proposed Changes +## Source of truth -- Change +- Owning repository/PR/commit: +- Product or runtime verification: ---- +## Documentation changes -> Read about referenced issues [here](https://help.github.com/articles/closing-issues-using-keywords/). Replace words with this Pull Request's context. +- Changed pages: +- Navigation or redirects: +- Screenshots and fixture/cleanup: + +## Verification + +- [ ] Formatted changed files +- [ ] `bun run verify` +- [ ] Checked changed routes in desktop Chrome +- [ ] Checked every theme enabled by the current theme config +- [ ] Confirmed screenshots contain no secrets or personal/private data diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e0f51199..d7c3d02b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -36,5 +36,4 @@ jobs: with: bun-version: latest - run: bun install - - run: bun run lint - - run: bun run test + - run: bun run verify diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..24703bc0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,88 @@ +# Lifecycle Docs Agent Guide + +Lifecycle Docs is the public, end-user documentation for Lifecycle. Keep it accurate, task-oriented, safe to follow, and easy to scan. + +## Load Order + +1. Read `PRODUCT.md` for audiences, voice, and accessibility goals. It is editorial direction, not product-behavior truth. +2. Read `README.md` for MDX and component mechanics. +3. Read the target page, its nearest `_meta.ts`, and adjacent pages before editing. +4. Read `DESIGN.md` and `DESIGN.json` only for component, layout, brand, or visual-system work. +5. Inspect the owning product source before asserting behavior. +6. Use `$update-lifecycle-docs` for documentation synchronization, new guides, troubleshooting, or UI screenshots. + +## Sources of Truth + +When sibling repositories are available, route claims as follows: + +| Claim | Owning source | +| ------------------------------------------------------------------- | -------------------------------------------------------------- | +| Product behavior, API, OpenAPI, `lifecycle.yaml`, and Agent runtime | `../lifecycle` | +| UI routes, labels, states, and interactions | `../lifecycle-ui` and the running UI | +| CLI commands, flags, output, and exit behavior | `../lifecycle-cli` | +| Installation defaults and Helm values | `../helm-charts` | +| Demo/evaluation infrastructure | `../lifecycle-opentofu`; never imply it is production guidance | +| Public explanation, navigation, and task guidance | This repository, after verifying the owner above | + +If an owning repository is unavailable, require an upstream PR, commit, schema, or other authoritative artifact. Mark behavior as unverified instead of guessing. Never use an existing docs page as proof that the same page is correct. + +## Authoring Rules + +- Name the intended reader and task before editing. +- Lead with the outcome, then prerequisites, steps, expected result, recovery, and next action. +- Explain user-observable behavior rather than internal implementation. +- Prefer canonical product language. Use **Environment** for the user concept; mention **Build** only when an API or CLI compatibility context requires it. +- Give every page useful `title` and `description` frontmatter. +- Prefer updating an existing page unless a distinct user task needs its own page. +- Put copyable code, commands, and payloads in text—not screenshots. +- Give every meaningful image descriptive alt text and adjacent instructions or a caption. +- Give every iframe a useful title. +- Clearly label Stable, Alpha/Beta, Labs, admin-gated, evaluation-only, and production-supported behavior. +- Use a product decision, release note, or visible product label as the source + for support status. Code presence alone does not prove public support; if the + status is unresolved, say so in the handoff instead of inventing a label. +- Never publish credentials, secret values, broad secret-decoding commands, direct database mutation as normal setup, or destructive diagnostic shortcuts. +- Do not expose private repository ownership, personal identities, access tokens, internal-only hostnames, or incidental local data in screenshots. +- Preserve unrelated changes and review generated `_meta.ts` output for accidental ordering churn. + +## UI and Screenshot Work + +- Verify UI claims in the running desktop UI through Chrome DevTools; source inspection alone is not enough for visual behavior. +- Use a 1440×900 desktop viewport. Do not add mobile captures unless the task explicitly requires them. +- Set `labs=true` before inspecting Labs-gated surfaces. +- The common local UI URL is `http://localhost:3000`; confirm it from the + current workspace run instructions rather than assuming it. +- Never create a fixture PR, push a fixture branch, or mutate another external + repository unless the user authorized that external state change. +- Capture only stable, task-relevant states. Prefer focused application regions over full browser windows. +- Use neutral, reversible fixture data and meaningful alt text. Do not use blur or generative editing to hide sensitive content. +- Read `.agents/skills/update-lifecycle-docs/references/screenshots.md` before creating or refreshing screenshots. + +## Verification + +Format only the files you changed: + +```sh +bunx prettier --check +``` + +Run the repository verification suite: + +```sh +bun run verify +``` + +When content or visuals change, inspect the rendered routes in desktop Chrome. +Check every theme enabled in `src/theme.config.tsx`; the current site forces the +dark theme. If a change enables another theme, verify that theme before +shipping. + +For local rendering, run `bun run dev` and open `http://localhost:3333`. + +In the PR summary, identify: + +- Intended reader and task +- Owning source or commit used for verification +- Changed pages +- Runtime/browser verification +- Screenshot fixture and cleanup, when applicable diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..056f0d07 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# Lifecycle Docs + +Read and follow `AGENTS.md` before changing this repository. For documentation updates or UI screenshots, also read `.agents/skills/update-lifecycle-docs/SKILL.md`. diff --git a/README.md b/README.md index 85ef4ffb..4449ce7d 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Making a post can be done in a few steps. ```txt // example src/pages/docs/troubleshooting/ - public/docs/troubleshooting/new-page> + public/docs/troubleshooting// ``` --- @@ -41,23 +41,25 @@ View all the currently exported components [here](https://github.com/GoodRxOSS/l The `` component is a wrapper around next/image that provides a few extra features to make it easier to look nice in the docs. ```mdx -import Image from '@lifecycle-docs/components'; +import { Image } from '@lifecycle-docs/components'; Alt text ``` -You can center the image by adding the `center` prop and some extra JSX. +`alt` is required. Describe the information the image contributes to the +surrounding instructions. + +You can constrain and center an image with normal layout classes: ```mdx
-
+
Additional Optional Services
@@ -98,15 +100,23 @@ Run the development server bun run dev ``` +Open `http://localhost:3333`. + +Before opening a pull request, run: + +```bash +bun run verify +``` + ## Deployment -This site is deployed to GitHub Pages using GitHub Actions. When changes are pushed to the `oss` branch, a GitHub Action workflow automatically builds the site and deploys it to the `gh-pages` branch. +This site is deployed to GitHub Pages using GitHub Actions. When changes are pushed to the `main` branch, a GitHub Action workflow automatically builds the site and deploys it to the `gh-pages` branch. ### Automatic Deployment The deployment process is handled by a GitHub Actions workflow defined in `.github/workflows/deploy.yml`. This workflow: -1. Runs when changes are pushed to the `oss` branch +1. Runs when changes are pushed to the `main` branch 2. Sets up Bun 3. Installs dependencies 4. Builds the static site @@ -151,7 +161,7 @@ You can also build and deploy the site manually: git reset --hard git commit --allow-empty -m "Initial gh-pages commit" git push origin gh-pages - git checkout oss + git checkout main # For subsequent deployments bun run deploy @@ -162,7 +172,7 @@ You can also build and deploy the site manually: git add . git commit -m "Deploy to GitHub Pages" git push origin gh-pages - git checkout oss + git checkout main ``` However, it's recommended to let the GitHub Actions workflow handle the deployment automatically. diff --git a/package.json b/package.json index ed5c3d15..9f793cf4 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,8 @@ "test": "bun test", "test:watch": "bun test --watch", "test:coverage": "bun test --coverage", - "update": "codependence --update" + "update": "codependence --update", + "verify": "bun run lint && bun run typecheck && bun run test && bun run build" }, "dependencies": { "@code-hike/mdx": "^0.9.0", diff --git a/public/docs/getting-started/explore-environment/environment-ready.png b/public/docs/getting-started/explore-environment/environment-ready.png new file mode 100644 index 00000000..f1ee6bc6 Binary files /dev/null and b/public/docs/getting-started/explore-environment/environment-ready.png differ diff --git a/public/docs/troubleshooting/deploy-issues/service-deploy-failure.png b/public/docs/troubleshooting/deploy-issues/service-deploy-failure.png new file mode 100644 index 00000000..77a41e43 Binary files /dev/null and b/public/docs/troubleshooting/deploy-issues/service-deploy-failure.png differ diff --git a/src/components/home/main/index.tsx b/src/components/home/main/index.tsx index 779aa384..871300b1 100644 --- a/src/components/home/main/index.tsx +++ b/src/components/home/main/index.tsx @@ -46,7 +46,10 @@ export const Main = () => {
-