docs(repo): Align docs with current maintainer flows

Document the current static web-app behavior, local-only save flow, shallow installer path, and maintainer-only sync controls.\n\nAlign maintainer guides with the active audit-to-risk-sync workflow, canonical artifact bot contract, release/coverage requirements, and updated security triage context so the docs match the repository's real operating model.

.github/MAINTENANCE.md

@@ -98,6 +98,14 @@ Before ANY commit that adds/modifies skills, run the chain:
     ```bash
     npm run audit:maintainer
     ```
+    When you are reducing legacy `risk: unknown` debt, use this sequence instead of hand-editing large batches:
+    ```bash
+    npm run audit:skills
+    npm run sync:risk-labels -- --dry-run
+    npm run sync:risk-labels
+    npm run sync:repo-state
+    ```
+    `sync:risk-labels` is intentionally conservative. It should handle only the obvious subset; the ambiguous tail still needs maintainer review.
 
 4.  **COMMIT GENERATED FILES**:
     ```bash
@@ -107,6 +115,7 @@ Before ANY commit that adds/modifies skills, run the chain:
     > 🔴 **CRITICAL for direct `main` work**: If you skip this on maintainer work that lands directly on `main`, CI will fail with "Detected uncommitted changes".
     > For contributor PRs, do **not** include derived registry artifacts. CI blocks direct edits to those files and previews drift separately.
     > See [`docs/maintainers/ci-drift-fix.md`](../docs/maintainers/ci-drift-fix.md) for details.
+    > `main` may still auto-commit canonical artifacts with `[ci skip]`, but only within the generated-files contract. If the sync leaves unmanaged drift, the workflow must fail instead of pushing a partial fix.
 
 ### B. When You Merge a PR (Step-by-Step)
 

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Risk maintenance workflow**: expanded the legacy `risk:` cleanup flow so maintainers can sync explicit high-confidence `none`, `safe`, `critical`, and `offensive` labels from audit suggestions, including auto-inserting the required `AUTHORIZED USE ONLY` notice when a legacy skill is promoted to `offensive`.
+- **Contributor and maintainer policy docs**: clarified that automated validation is necessary but not sufficient for skill changes, documented the manual logic review requirement, and aligned maintainer guidance around the `audit:skills` -> `sync:risk-labels` -> `sync:repo-state` loop.
+- **Web app and CI docs**: aligned public documentation with the current static Pages deploy, local-only maintainer sync flow, browser-local save behavior, web-app coverage checks, and the stricter release/CI contract now used on `main`.
+
 ## [9.1.0] - 2026-03-28 - "SaaS Multi-Tenancy and Three.js r183 Refresh"
 
 > Installable skill library update for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and related AI coding assistants.

CONTRIBUTING.md

@@ -246,6 +246,8 @@ Passing `npm run validate` or `skill-review` is not enough on its own for skill
 - obvious failure modes, unsafe assumptions, and user-facing edge cases,
 - whether the declared `risk:` level still matches the actual behavior.
 
+Submitting `risk: unknown` is still acceptable for genuinely legacy or not-yet-classified content. Maintainers may later use `npm run audit:skills` and `npm run sync:risk-labels` to reconcile high-confidence legacy labels without asking contributors to regenerate catalog artifacts in their PRs.
+
 For **docs / workflows / infra changes**:
 
 ```bash

README.md

@@ -78,6 +78,7 @@ Install once; then use Starter Packs in [docs/users/bundles.md](docs/users/bundl
    # Default: ~/.gemini/antigravity/skills (Antigravity global). Use --path for other locations.
    npx antigravity-awesome-skills
    ```
+   The npm installer uses a shallow clone by default so first-run installs stay lighter than a full repository history checkout.
 2. **Verify**:
 
    ```bash
@@ -273,6 +274,8 @@ If you want a faster answer than "browse all 1,331+ skills", start with a tool-s
 These skills are continuously reviewed and hardened, but the collection is not "safe by default". They are instructions and examples that can include risky operations by design.
 
 - Runtime hardening now protects the `/api/refresh-skills` mutation flow (method/host checks and optional token gate) before any repo mutation.
+- The published GitHub Pages catalog runs in static public-catalog mode, so the maintainer-only `/api/refresh-skills` flow is hidden in production unless you are using the local Vite dev server with the explicit sync flag.
+- Skill saves in the web UI are intentionally browser-local today. Optional Supabase configuration is read-only and should not be treated as a shared write path or authoritative leaderboard.
 - Markdown rendering in the web app avoids raw HTML passthrough (`rehype-raw`) and follows safer defaults for skill content display.
 - A repo-wide `SKILL.md` security scan checks for high-risk command patterns (for example `curl|bash`, `wget|sh`, `irm|iex`, command-line token examples) with explicit allowlisting for deliberate exceptions.
 - Pull requests that touch `SKILL.md` files now also run an automated `skill-review` GitHub Actions check, so contributors and maintainers get a second pass focused on skill structure and review quality.
@@ -521,6 +524,8 @@ npm run app:dev
 
 That will copy the generated skill index into `apps/web-app/public/skills.json`, mirror the current `skills/` tree into `apps/web-app/public/skills/`, and start the Vite development server.
 
+On the hosted GitHub Pages site, the same app runs as a static public catalog: dev-only sync controls stay hidden there, and save/star actions remain local to the browser.
+
 **Hosted online:** The same app is available at [https://sickn33.github.io/antigravity-awesome-skills/](https://sickn33.github.io/antigravity-awesome-skills/) and is deployed automatically on every push to `main`. To enable it once: **Settings → Pages → Build and deployment → Source: GitHub Actions**.
 
 ## Contributing
@@ -531,6 +536,7 @@ That will copy the generated skill index into `apps/web-app/public/skills.json`,
 - Validate with `npm run validate` before opening a PR.
 - Keep community PRs source-only: do not commit generated registry artifacts like `CATALOG.md`, `skills_index.json`, or `data/*.json`.
 - If your PR changes `SKILL.md`, expect the automated `skill-review` check on GitHub in addition to the usual validation and security scans.
+- If your PR changes skills or risky guidance, manual logic review is still required even when the automated checks are green.
 
 ## Community
 

apps/web-app/README.md

@@ -8,6 +8,7 @@ This app is the static catalog and skill browser for `antigravity-awesome-skills
 - Renders home, category, bundle, and skill detail routes for the published library.
 - Adds SEO metadata, sitemap-backed URLs, and static asset resolution for GitHub Pages.
 - Supports a local-only "refresh skills" developer flow through the Vite dev server plugin.
+- Treats save/star interactions as browser-local UX, even when optional read-only Supabase counts are configured.
 
 ## Architecture
 
@@ -19,12 +20,18 @@ This app is the static catalog and skill browser for `antigravity-awesome-skills
 
 The app intentionally assumes a static hosting model in production. Anything that depends on `/api/*` is development-only unless it is backed by a real serverless or backend implementation.
 
+The hosted Pages build should be understood as a public catalog, not a control plane:
+
+- `Sync Skills` is a maintainer/development affordance and must stay hidden unless `VITE_ENABLE_SKILLS_SYNC=true`.
+- save/star interactions are local-only unless the project gains a real backend write contract with abuse controls and deployment support.
+
 ## Development
 
 From the repo root:
 
 ```bash
 npm run app:install
+npm run app:test:coverage
 npm run app:dev
 ```
 
@@ -79,6 +86,7 @@ The high-level maintainer flow is:
 From the repo root:
 
 ```bash
+npm run app:test:coverage
 cd apps/web-app && npm run test
 cd apps/web-app && npm run test:coverage
 npm run test
@@ -86,6 +94,8 @@ npm run test
 
 The repo-level test suite also contains workflow and documentation guardrails outside `src/`, so changes to this app can fail tests in `tools/scripts/tests/` even when the React code itself is untouched.
 
+`main`/release CI also runs `npm run app:test:coverage`, so coverage thresholds are part of the real shipping contract for this app rather than an optional local extra.
+
 ## Troubleshooting
 
 - If the app shows stale catalog data, run `npm run sync:web-assets` from the repo root and rebuild.

docs/contributors/quality-bar.md

@@ -64,6 +64,8 @@ Use `npm run audit:skills` when you need a repo-wide report that goes beyond sch
 - which skills are missing examples or limitations,
 - and which skills have the highest concentration of warnings/errors.
 
+Maintainers can pair that report with `npm run sync:risk-labels` for conservative legacy cleanup. That sync only rewrites `risk: unknown` when the suggested label is explicit and high-confidence enough to automate safely, and it preserves the contributor-facing rule that new or uncertain submissions can still start as `unknown`.
+
 ---
 
 ## Support Levels
@@ -94,6 +96,7 @@ Notes:
 
 - `npm run validate` is the operational contributor gate.
 - `npm run audit:skills` is the maintainer-facing compliance/usability report for the full library.
+- `npm run sync:risk-labels` is a maintainer cleanup tool for high-confidence legacy `risk:` fixes.
 - `npm run security:docs` is required for command-heavy or risky skill content.
 - PRs that touch `SKILL.md` also get an automated `skill-review` GitHub Actions check.
 - Skill changes and risky guidance still require a manual logic review before merge, even when the automated gates pass.

docs/maintainers/audit.md

@@ -17,7 +17,9 @@ This document summarizes the repository coherence audit performed after the `app
 ### 1. Conteggi
 
 - `README.md`, `package.json`, and generated artifacts are aligned to the current collection size.
-- `npm run sync:all` and `npm run catalog` are the canonical commands for keeping counts and generated files synchronized.
+- `npm run sync:repo-state` is the canonical maintainer command for keeping counts, generated files, contributors, and tracked web assets synchronized on local `main`.
+- `npm run sync:release-state` is the canonical release-facing variant when you want the same sync without the contributor refresh step.
+- `npm run sync:all` remains a legacy alias for the core chain, not the full maintainer sync surface.
 
 ### 2. Validazione skill
 
@@ -39,6 +41,8 @@ This document summarizes the repository coherence audit performed after the `app
   - plus the existing structural/safety checks (frontmatter, risk, `When to Use`, offensive disclaimer, dangling links).
 - The report also includes a non-blocking `suggested_risk` for skills that are still marked `unknown` or appear to be misclassified, so maintainers can resolve risk classification during PR review without changing the contributor gate.
 - Added `tools/scripts/sync_risk_labels.py` (also exposed as `npm run sync:risk-labels`) for conservative legacy cleanup: it only rewrites `risk: unknown` when the suggestion is high-confidence enough to be safely automated.
+- The sync now covers explicit high-confidence `safe`, `critical`, `offensive`, and `none` patterns. When a skill is promoted to `offensive`, the sync also inserts the canonical `AUTHORIZED USE ONLY` notice so the label and content guardrail stay aligned.
+- The intended maintainer loop is: `audit:skills` to inspect `suggested_risk`, `sync:risk-labels` for the safe automated subset, then manual review for the ambiguous tail that should not be batch-classified.
 - Use `npm run audit:skills` for the maintainer view and `npm run audit:skills -- --json-out ... --markdown-out ...` when you want artifacts for triage or cleanup tracking.
 
 ### 3. Riferimenti incrociati
@@ -76,6 +80,7 @@ npm run validate          # validazione skill (soft)
 npm run validate:strict   # hardening / diagnostic pass
 npm run audit:skills      # audit completo per skill con finding codes e status
 npm run sync:risk-labels  # conservative sync for high-confidence legacy risk labels
+npm run sync:risk-labels -- --dry-run  # preview legacy risk rewrites before touching files
 npm run validate:references  # workflow, bundle, and docs/users/bundles.md references
 npm run security:docs       # documentation command-risk scan (required for security-sensitive guidance)
 npm run build             # chain + catalog
@@ -85,4 +90,5 @@ npm test                  # suite test
 ## Issue aperte / follow-up
 
 - Gradual cleanup of legacy skills so `npm run validate:strict` can become a hard CI gate in the future.
+- Continue reducing the remaining `risk: unknown` tail with conservative sync passes plus manual maintainer review for ambiguous cases.
 - Keep translated docs aligned in a separate pass after the canonical English docs are stable.

docs/maintainers/ci-drift-fix.md

@@ -1,6 +1,6 @@
 # CI Drift Fix Guide
 
-**Problem**: The failing job is caused by uncommitted changes detected in `README.md`, `skills_index.json`, or catalog files after the update scripts run.
+**Problem**: The failing job is caused by tracked drift left behind after the canonical sync steps run on `main`.
 
 **Error**:
 
@@ -9,7 +9,16 @@
 ```
 
 **Cause**:
-Scripts like `tools/scripts/generate_index.py`, `tools/scripts/update_readme.py`, and `tools/scripts/build-catalog.js` modify `README.md`, `skills_index.json`, `data/catalog.json`, `data/bundles.json`, `data/aliases.json`, and `CATALOG.md`. The workflow expects these files to have no changes after the scripts run. Any differences mean the committed repo is out-of-sync with what the generation scripts produce.
+The canonical sync contract is broader than just the root registry files. Scripts such as `generate_index.py`, `update_readme.py`, `build-catalog.js`, `setup_web.js`, and plugin sync helpers can legitimately update:
+
+- `README.md`
+- `CATALOG.md`
+- `skills_index.json`
+- `data/*.json`
+- tracked web assets under `apps/web-app/public/`
+- generated plugin metadata and plugin-safe copies
+
+The workflow expects the repository to be clean after those sync steps finish. Any remaining tracked or unmanaged changes mean `main` is out of sync with what the generation pipeline actually produces.
 
 ## Pull Requests vs Main
 
@@ -18,32 +27,36 @@ Scripts like `tools/scripts/generate_index.py`, `tools/scripts/update_readme.py`
 
 ## How to Fix on `main`
 
-1. Run the **FULL Validation Chain** locally:
+1. Run the canonical maintainer sync locally:
 
    ```bash
-   npm run chain
+   npm run sync:repo-state
-   npm run catalog
    ```
 
-2. Check for changes:
+2. Check whether anything is still dirty:
 
    ```bash
    git status
    git diff
    ```
 
-3. Commit and push any updates:
+3. If the sync produced only canonical/generated changes, stage and commit them. Prefer the generated-files contract instead of a hand-maintained file list:
+
    ```bash
-   git add README.md skills_index.json data/skills_index.json data/catalog.json data/bundles.json data/aliases.json CATALOG.md
+   node tools/scripts/generated_files.js --include-mixed
-   git commit -m "chore: sync generated registry files"
+   git add $(node tools/scripts/generated_files.js --include-mixed)
+   git commit -m "chore: sync canonical artifacts"
    git push
    ```
 
+4. If `sync:repo-state` leaves unrelated or unmanaged drift, stop and inspect it. The bot on `main` is only allowed to push the canonical/generated subset; anything else should fail the workflow instead of being silently auto-committed.
+
 ## Maintainer guidance for PRs
 
 - Validate the source change, not the absence of committed generated artifacts.
 - If a contributor PR includes direct edits to `CATALOG.md`, `skills_index.json`, or `data/*.json`, ask them to drop those files from the PR or remove them while refreshing the branch.
 - If merge conflicts touch generated registry files, keep `main`'s version for those files and let `main` auto-sync the final generated artifact set after merge.
+- If CI on `main` later creates a bot commit with `[ci skip]`, that is expected only for the canonical/generated subset. It is not a license to push arbitrary extra drift.
 
 **Summary**:
 Use generator drift as a hard failure only on `main`. On PRs, the contract is simpler: source-only changes are reviewed, generated output is previewed, and `main` produces the final canonical artifact set.

docs/maintainers/merging-prs.md

@@ -8,6 +8,7 @@
 - The PR must show as **Merged**, not Closed. That way the contributor appears in the repo’s contribution graph and the PR is clearly linked to the merge commit.
 - Do **not** integrate a PR by squashing locally, pushing to `main`, and then closing the PR. That would show "Closed" and the contributor would not get proper credit.
 - Before merging, require the normal PR checks from [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) to be green. If the PR touches `SKILL.md`, also require the separate [`skill-review` workflow](../../.github/workflows/skill-review.yml) to pass.
+- For PRs that touch `SKILL.md` or risky guidance, require a real manual logic review in addition to the automated checks. Confirm the instructions, failure modes, and `risk:` label make sense before merging.
 
 ## If the PR has merge conflicts
 
@@ -19,6 +20,7 @@ Resolve conflicts **on the PR branch** so the PR becomes mergeable, then use "Sq
 - `README.md` is mixed ownership: contributor prose edits are allowed, but workflow-managed metadata is canonicalized on `main`.
 - If derived files appear in a PR refresh or merge conflict, prefer **`main`'s side** and remove them from the PR branch instead of hand-maintaining them there.
 - Do not block a PR only because shared generated files would be regenerated differently after other merges. `main` auto-syncs the final state after merge.
+- If a skill PR leaves `risk: unknown`, that is not automatically a blocker. Maintainers can review the suggested classification with `npm run audit:skills`, optionally run `npm run sync:risk-labels` locally after merge, and still keep the contributor PR source-only.
 
 ### Steps (maintainer resolves conflicts on the contributor’s branch)
 

docs/maintainers/release-process.md

@@ -17,7 +17,13 @@ This is the maintainer playbook for cutting a repository release. Historical rel
 npm run release:preflight
 ```
 
-This preflight now runs the deterministic `sync:release-state` flow, refreshes the tracked web assets in `apps/web-app/public`, executes the local test suite, runs the web-app build, and performs `npm pack --dry-run --json` so release tags are validated against the same artifact path used later in CI.
+This preflight now runs the deterministic `sync:release-state` flow, refreshes the tracked web assets in `apps/web-app/public`, executes the local test suite, installs the web-app dependencies, runs the web-app build, and performs `npm pack --dry-run --json` so release tags are validated against the same artifact path used later in CI.
+
+The active CI/release contract also expects:
+
+- Python dependencies to come from `tools/requirements.txt`,
+- the web app coverage job (`npm run app:test:coverage`) to stay green,
+- and `npm run security:docs` to pass without relying on non-blocking audit warnings.
 
 2. Mandatory documentation hardening (repo-wide SKILL.md security scan):
 
@@ -41,6 +47,7 @@ Use this as a diagnostic signal. It is useful for spotting legacy quality debt,
 - Confirm `README.md` reflects the current version and generated counts.
 - Confirm Credits & Sources, contributors, and support links are still correct.
 - If PR or CI workflow behavior changed during the cycle, confirm maintainer and contributor docs mention the active checks (for example the `skill-review` workflow for `SKILL.md` pull requests).
+- If maintainers used `npm run sync:risk-labels` or a comparable cleanup flow during the cycle, make sure the maintainer docs still describe the current audit -> sync -> repo-state loop.
 
 5. Prepare the release commit and tag locally:
 
@@ -73,7 +80,7 @@ npm publish
 ```
 
 Normally this still happens via the existing GitHub release workflow after the GitHub release is published.
-That workflow now reruns `sync:release-state`, refreshes tracked web assets, fails on canonical drift via `git diff --exit-code`, executes tests and docs security checks, builds the web app, and dry-runs the npm package before `npm publish`.
+That workflow now reruns `sync:release-state`, installs Python dependencies from `tools/requirements.txt`, refreshes tracked web assets, fails on canonical drift via `git diff --exit-code`, executes tests and docs security checks, runs the web-app coverage gate, enforces `npm audit --audit-level=high`, builds the web app, and dry-runs the npm package before `npm publish`.
 
 ## Canonical Sync Bot
 
@@ -81,6 +88,7 @@ That workflow now reruns `sync:release-state`, refreshes tracked web assets, fai
 
 - PRs stay source-only.
 - After merge, the `main` workflow may commit generated canonical files directly to `main` with `[ci skip]`.
+- Those bot commits still skip CI, so the sync contract must stay narrow and predictable: only canonical/generated files may be staged, and any unmanaged drift must fail the workflow instead of being silently pushed.
 - The bot commit is only allowed to stage files resolved from `tools/scripts/generated_files.js --include-mixed`.
 - If repo-state sync leaves any unmanaged tracked or untracked drift, the workflow fails instead of pushing a partial fix.
 - The scheduled hygiene workflow follows the same contract and shares the same concurrency group so only one canonical sync writer runs at a time.

docs/maintainers/security-findings-triage-2026-03-15.md

@@ -1,5 +1,7 @@
 # Security Findings Triage (2026-03-15)
 
+Maintainer note: later fixes changed the status of several findings after this baseline snapshot. See [`security-findings-triage-2026-03-29-addendum.md`](security-findings-triage-2026-03-29-addendum.md) before using this file as the current source of truth.
+
 - Baseline: `origin/main@226f10c2a62fc182b4e93458bddea2e60f9b0cb9`
 - Input CSV was treated as triage input only, not as ground truth.
 - Status meanings: `still present and exploitable`, `still present but low practical risk`, `obsolete/not reproducible on current HEAD`, `duplicate of another finding`.

docs/maintainers/security-findings-triage-2026-03-29-addendum.md

@@ -0,0 +1,45 @@
+# Security Findings Triage Addendum (2026-03-29)
+
+This addendum updates the 2026-03-15 baseline after the follow-up hardening
+work shipped on `main`.
+
+## Corrected / Updated Findings
+
+- Finding `1` / `7` (`tools/scripts/sync_microsoft_skills.py`)
+  The Microsoft sync path now constrains filesystem writes and copied inputs to
+  safe in-repo targets. The plugin-skill discovery path also skips symlinked
+  `SKILL.md` files instead of trusting them. Regression coverage lives in
+  `tools/scripts/tests/test_sync_microsoft_skills_security.py`.
+
+- Finding `18` / `29` (`tools/scripts/validate_skills.py`,
+  `tools/scripts/generate_index.py`)
+  Frontmatter parsing now rejects non-mapping YAML payloads cleanly and handles
+  empty/frontmatter-edge cases without crashing downstream validation or index
+  generation. Regression coverage lives in
+  `tools/scripts/tests/test_frontmatter_parsing_security.py`.
+
+- Finding `19`
+  The web app no longer exposes shared frontend writes for skill saves/stars by
+  default. The current behavior is browser-local save state with optional
+  read-only remote counts, so the old "anonymous Supabase writes allow skill
+  star tampering" assessment is no longer the active behavior on current HEAD.
+
+- Findings `16` / `17`
+  The `refresh-skills` plugin remains a local development surface, but the
+  published GitHub Pages app now runs in static public-catalog mode and does not
+  expose the maintainer sync CTA in production. Treat the residual plugin logic
+  as local dev hardening scope, not a public production endpoint.
+
+- Finding `33`
+  The Office unpack helpers no longer call `extractall()` blindly. They now
+  validate archive member paths and reject traversal/symlink-style entries
+  before extraction. Regression coverage lives in
+  `tools/scripts/tests/test_office_unpack_security.py`.
+
+## Maintainer Guidance
+
+- Keep the 2026-03-15 file as the historical baseline snapshot.
+- Use this addendum plus the newer regression tests when deciding which
+  findings are still actionable on current HEAD.
+- If a future triage refresh is produced, fold these corrections into the next
+  full summary instead of re-copying the original counts unchanged.

docs/users/faq.md

@@ -81,6 +81,13 @@ For a concrete example (including pseudo‑code) see:
 
 The skill files themselves are stored locally on your computer, but your AI assistant needs an internet connection to function.
 
+### Does the hosted web app write anything back to the repository?
+
+No. The public site is a static GitHub Pages deploy.
+
+- The maintainer `Sync Skills` flow is local-development only and is not a public production endpoint.
+- Browser save/star interactions are intentionally local-first for now. Until the project has a real backend contract, treat them as browser-local state rather than shared repository writes.
+
 ---
 
 ## Security & Trust
@@ -123,6 +130,8 @@ If you get a 404 from npm, use: `npx github:sickn33/antigravity-awesome-skills`
 git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
 ```
 
+The installer CLI is the recommended path for most users because it performs a lighter shallow clone of the current library. Manual `git clone` is still the right option when you want the full repository history or plan to contribute from the same checkout.
+
 **Tool-specific paths:**
 
 - Claude Code: `.claude/skills/`
@@ -148,6 +157,28 @@ This repository also includes repo-local plugin metadata for Codex:
 
 That path exposes the new plugin-safe Codex root plugin plus generated bundle plugins. For the full explanation, read [plugins.md](plugins.md).
 
+### Why do I not see `Sync Skills` on the hosted website?
+
+Because the public site is a static GitHub Pages catalog, not a maintainer control surface.
+
+`Sync Skills` is only meant for local maintainer/development runs behind the Vite dev server, and it stays hidden unless the local environment explicitly enables it.
+
+### What does `Public catalog mode` mean?
+
+It means you are looking at the published static catalog build.
+
+In that mode:
+
+- catalog browsing and skill detail pages work normally
+- dev-only `/api/refresh-skills` behavior is not available
+- anything that would require a backend or mutable server state is intentionally disabled or reduced to local-only behavior
+
+### Are saves/stars global or just local?
+
+Right now they are local to your browser.
+
+The app may show optional read-only community counts when configured, but clicking save/star does not create a shared server-side vote. Until the project ships a real backend write contract with abuse controls, treat saves as a personal local bookmark signal.
+
 ### What does `plugin-safe` mean?
 
 Plugin-safe means the published Claude Code and Codex plugins only include the subset of skills that is ready for marketplace-style distribution.

docs/users/getting-started.md

@@ -33,6 +33,7 @@ npx antigravity-awesome-skills
 ```
 
 This clones to `~/.gemini/antigravity/skills` by default. Use `--cursor`, `--claude`, `--gemini`, `--codex`, or `--kiro` to install for a specific tool, or `--path <dir>` for a custom location. Run `npx antigravity-awesome-skills --help` for details.
+The installer uses a shallow clone by default so you get the current library without paying for the full git history on first install.
 
 If you see a 404 error, use: `npx github:sickn33/antigravity-awesome-skills`
 
@@ -116,11 +117,13 @@ Once installed, just talk to your AI naturally.
 
 We classify skills so you know what you're running:
 
-- 🟣 **Official**: Maintained by Anthropic/Google/Vendors (High Trust).
+- ⚪ **unknown**: legacy/unclassified content that still needs maintainer triage.
-- 🔵 **Safe**: Community skills that are non-destructive (Read-only/Planning).
+- 🟢 **none**: pure text/reasoning guidance.
-- 🔴 **Risk**: Skills that modify systems or perform security tests (Authorized Use Only).
+- 🔵 **safe**: read-only or low-risk operational guidance.
+- 🟠 **critical**: state-changing or deployment-impacting guidance.
+- 🔴 **offensive**: pentest/red-team guidance with an explicit Authorized Use Only warning.
 
-When adding new skills, high-risk guidance is extra-reviewed with repository-wide `security:docs` scanning before release.
+Community PRs may still submit `risk: unknown`, but maintainers now audit and progressively reconcile those labels using the repo-wide audit/report tooling. High-risk guidance is extra-reviewed with repository-wide `security:docs` scanning before release.
 
 _Check the [Skill Catalog](../../CATALOG.md) for the full list._
 

walkthrough.md

@@ -1,3 +1,19 @@
+# Maintenance Walkthrough - 2026-03-29
+
+- Fixed the remaining production/documentation drift introduced by the web-app and CI hardening work:
+  - clarified that the hosted GitHub Pages app runs in static public-catalog mode
+  - documented that `Sync Skills` is development-only unless explicitly enabled in local maintainer runs
+  - documented that web-app save/star interactions are intentionally browser-local today
+- Hardened the maintainer documentation so release and CI expectations now match the live workflows:
+  - release docs now mention the shared `tools/requirements.txt` install path, the web-app coverage gate, and blocking `npm audit --audit-level=high` on publish
+  - maintainer docs now document the narrow canonical-artifact auto-sync contract on `main`
+- Expanded the documented risk-maintenance workflow after the new automation landed:
+  - `audit:skills` exposes `suggested_risk`
+  - `sync:risk-labels` supports conservative high-confidence legacy cleanup
+  - offensive auto-promotions now also insert the canonical `AUTHORIZED USE ONLY` notice
+- Updated user-facing install docs to mention that the npm installer now uses a shallow clone for lighter first-run installs.
+- Updated the onboarding/trust docs to reflect the real `risk` taxonomy (`unknown`, `none`, `safe`, `critical`, `offensive`) instead of the older simplified wording.
+
 # Maintenance Walkthrough - 2026-03-25
 
 - Imported 14 skills from [Dimillian/Skills](https://github.com/Dimillian/Skills) into `skills/`: