statgpt-admin-fe-guide-macos

# StatGPT Admin Frontend Guide Updater This skill regenerates the **StatGPT Administrator Guide** — `guides/admin-guide.md` plus its annotated screenshots in `guides/content/admin-guide/` — so the prose, the configuration YAML, and the images all match the current Admin frontend. It exists because doing this by hand is fiddly: screenshots leak non-sample content, the Chrome debugging banner corrupts captures, badge placement is easy to get wrong, and the config format in the guide must match what the admin actually stores (not the snake_case seed files). The output is a rewritten guide with numbered-step prose whose numbers line up with numbered badges on each screenshot, plus a set of clean, sample-only annotated PNGs. ## Step 0 — Gather the three inputs This skill is **driven by three inputs**. Ask for any that aren't already given, then confirm them back before doing work: 1. **Scope** — what to refresh. Either a *full refresh* (every section + new features) or a *targeted* update (named sections, or "just the new X feature"). Scope decides which screens you capture and which parts of the guide you rewrite. Don't silently expand scope. 2. **Environment URL** — the admin frontend base URL to capture from (e.g. `https://statgpt-admin-frontend.aks.dev.dial.parts`). Everything is captured live from here through the claude-in-chrome MCP. 3. **Limitations** — hard constraints for this run. The defaults below are non-negotiable unless the user explicitly relaxes one; the user may add more (e.g. "don't touch the channel X"). ## Hard constraints (the defaults — honor unless the user overrides) These protect a **public** docs repo and a **shared** environment. Re-read them before each capture. - **Sample content only.** Every screenshot must show *only* sample entities. Filter every list to the sample data source (e.g. `IMF_SDMX21`), the sample channel (e.g. **StatGPT Sample**), and the "**- Sample**" datasets. Never let other orgs' content appear. If a screen can't be filtered to sample-only (e.g. an "Add datasets to channel" picker that lists everything and has no source filter), **don't screenshot it** — describe it in prose instead. Confirm the exact sample identifiers for the target environment up front. - **Redact PII.** Audit logs and similar screens show real user emails. Mask those columns with a redaction bar before the image leaves your hands (see `references/annotation.md`). - **No deletions of any content.** To document a delete action, open the confirm dialog and Cancel. Beware: some delete actions have **no confirmation dialog** (e.g. glossary terms delete immediately). If you trigger one by accident, **restore the item immediately** from the seed configs and tell the user. - **You may modify / reindex / deduplicate / add SAMPLE content only** — never other channels/sources. Don't create duplicate sources/datasets/channels when illustrating "Add"; fill the form for the screenshot, then Cancel. - **Documents page is out of scope** unless the user says otherwise. - **No git commits or pushes** unless the user asks. When they do, branch first, stage *only* the guide + its images (not stray local files), and follow the repo's PR conventions. ## Workflow Work in a scratch dir (e.g. `/tmp/statgpt-admin-guide/{raw,annotated,specs}`) and only copy finished images into the repo at the end. Track progress with a task list. ### Phase 1 — Explore and map changes Drive the admin UI with the claude-in-chrome MCP (load the deferred `mcp__claude-in-chrome__*` tools via ToolSearch first; call `tabs_context_mcp` to get the tab id). Walk the target scope's screens and compare against the current `guides/admin-guide.md`: note new nav items, renamed/added buttons, changed wizards, new columns, and new pages. Produce a short map of what changed so the rewrite and the screenshot list are grounded in the live UI, not assumptions. ### Phase 2 — Capture sample-only screenshots This is the part with the sharp edges. **Read `references/capture-pipeline.md` before starting** — it covers window calibration, the debugging-banner problem, and the two coordinate spaces. The loop per screenshot: 1. Drive the UI to the target state via MCP (`browser_batch` of clicks/types/navigate). **Filter every list to sample content** before capturing. 2. Make the **final MCP action a `hover` to a neutral, empty spot** so the cursor (which `screencapture` includes) isn't covering content. 3. Capture with the bundled banner-aware script — **no CDP command between the hover and this**: ``` CAP_REGION=<X,Y,W,H> CAP_PYBIN=<python-with-pillow> \ scripts/cap.sh /tmp/statgpt-admin-guide/raw/<name>.png ``` 4. **View the PNG** (Read it) and confirm it's banner-free and shows only sample content. Capture the set of screens your scope needs (list pages, add wizards, edit/config modals, context menus, per-dataset Versions / Auto update jobs pages, indexing dialogs, glossary, import modal, jobs, audit logs). `references/config-and-structure.md` has the canonical screen inventory and suggested filenames. ### Phase 3 — Annotate (numbered badges + highlight boxes) Style is **numbered badges + rounded highlight boxes** (numbers match the numbered prose steps), with **redaction bars** for PII. Use the bundled annotator: ``` <python-with-pillow> scripts/annotate.py spec.json ``` The spec is JSON with `src`, `dst`, optional `crop`, and `boxes` / `badges` / `redactions` arrays. **Coordinates are measured from the actual captured PNG**, and getting this right is the single biggest source of rework — **read `references/annotation.md`**, especially the part about *not* trusting downscaled previews (measure from clean, full-resolution crops). Verify every rendered annotation by viewing it; box columns to their *full* visible height; keep badges off the content they label. ### Phase 4 — Rewrite the guide Rewrite the in-scope parts of `guides/admin-guide.md`: - Match the new UI: structure, nav, wizards, new pages and columns. - Numbered prose steps that **correspond to the badges** in each referenced screenshot. - **Configuration YAML in admin (camelCase) format**, sourced from the `statgpt-backend` sample configs — *do not invent values*. The seed files are snake_case; the admin stores camelCase. See `references/config-and-structure.md` for the field mapping (data source, the dataset `dimensions` map, channel + tools). When in doubt, the live "Configure"/"Edit" editor is the source of truth — read it via Monaco `getValue()`. - When covering dataset configuration, **link the admin learning course** (`../learning/administration/README.md`, esp. Modules 03a/03b/04/05/06). - Add a table of contents; fix any broken image links; keep every cross-link resolvable. ### Phase 5 — Review and (if asked) ship Verify all referenced images exist; flag now-orphaned old images (don't delete files you didn't create without asking). If the user asks to ship: branch, stage only the guide + images, commit with a Conventional-Commits title, push, and open a PR with the repo's template. ## Key paths - Guide: `guides/admin-guide.md`; images: `guides/content/admin-guide/`. - Sample configs (source of truth for YAML): `statgpt-backend/configurations/clients/sample/` (`data_sources.yaml`, `datasets/*.yaml`, `channels.yaml`, `tools.yaml`, `glossaries/*.csv`). - Learning course: `learning/administration/` (README + numbered modules). - Bundled `scripts/cap.sh` (capture) and `scripts/annotate.py` (annotate). ## References (read when you reach the relevant phase) - `references/capture-pipeline.md` — window calibration, the Chrome debugging banner, coordinate spaces, and the capture protocol. **Read before Phase 2.** - `references/annotation.md` — the annotator spec, coordinate measurement (and the downscaled-preview trap), badge/box/redaction conventions. **Read before Phase 3.** - `references/config-and-structure.md` — seed→admin config field mapping, the guide's section structure, the screenshot inventory, and learning-course links. **Read before Phase 4.**