docs: modularize GEMINI.md into Gemini CLI Skills

This commit transitions the large, monolithic project context in `GEMINI.md`
into modular Gemini CLI Skills stored in the `skills/` directory.

Benefits:
- Reduced token overhead by leveraging Progressive Disclosure (triggering
  specific skills only when relevant).
- Improved agent reliability with more focused, domain-specific instructions.
- Simplified maintenance of specialized architectural and workflow documentation.

Key Changes:
- Created 7 new skills: backend, frontend, e2e, ingestion, workers,
  search-grammar, and maintenance.
- Added `make link-skills` to the `Makefile` for easy skill registration.
- Automated skill linking in `.devcontainer/post_attach.sh`.
- Trimmed `GEMINI.md` to a high-level entry point that points to the skills.

Author: jcscottiii

.devcontainer/post_attach.sh

@@ -54,6 +54,9 @@ else
   echo "You may need to configure an API key manually to use certain Gemini features."
 fi
 
+# Link Gemini Skills
+echo "Linking Gemini Skills..."
+make link-skills
 
 echo "Note: After starting the Gemini CLI for the first time, it may present you with some errors."
 echo "In that case, it will tell you to open a new terminal and start the Gemini CLI again."

GEMINI.md

@@ -553,3 +553,15 @@ download-playwright-report-from-run-%: check-gh-login
 	rm -rf playwright-report
 	mkdir -p playwright-report
 	gh run download -R $(GH_REPO) $* -n playwright-report --dir playwright-report
+
+################################
+# Skills
+################################
+link-skills:
+	gemini skills link skills/webstatus-workers --consent
+	gemini skills link skills/webstatus-backend --consent
+	gemini skills link skills/webstatus-frontend --consent
+	gemini skills link skills/webstatus-e2e --consent
+	gemini skills link skills/webstatus-ingestion --consent
+	gemini skills link skills/webstatus-search-grammar --consent
+	gemini skills link skills/webstatus-maintenance --consent

Makefile

@@ -0,0 +1,54 @@
+---
+name: webstatus-backend
+description: Use when creating or modifying Go backend API endpoints, modifying Spanner database schemas, or working with OpenAPI and Spanner mappers.
+---
+
+# webstatus-backend
+
+This skill provides guidance for developing the Go-based backend API for `webstatus.dev`.
+
+## Core Components
+
+- **HTTP Server (`backend/pkg/httpserver`)**: Handles routing and requests via `oapi-codegen` stubs.
+- **Storage Adapter (`lib/gcpspanner/spanneradapters`)**: Translates API types to database types.
+- **Spanner Client (`lib/gcpspanner`)**: Core logic for Spanner interactions using the Mapper pattern.
+
+## Guides
+
+- **[Add a New API Endpoint](references/add-api-endpoint.md)**: Mandatory spec-first process.
+- **[Spanner Mapper Pattern](references/mapper-pattern.md)**: How to use the generic entity helpers.
+- **[Spanner Best Practices](references/spanner-best-practices.md)**: Efficient and safe querying.
+- **[Shared Libraries & Utilities](references/shared-libraries.md)**: Guidelines for `lib/`, `util/`, and the `OptionallySet` pattern.
+
+## General Do's and Don'ts
+
+- **DO** use `spanneradapters` for DB interactions in the API.
+- **DON'T** call `gcpspanner.Client` directly from `httpserver` handlers.
+- **DO** use `row.ToStruct(&yourStruct)` instead of manual column scanning.
+- **DO** define new Spanner table structs and query logic within `lib/gcpspanner`.
+- **DO** write integration tests using `testcontainers-go` for any changes to the `lib/gcpspanner` layer.
+- **DO** add response caching for new read-only endpoints in `backend/pkg/httpserver/cache.go`.
+- **DON'T** import `lib/backendtypes` into `lib/gcpspanner` (prevents circular dependencies).
+- **DO** handle business key to internal ID translation inside the `gcpspanner` client.
+- **DO** ensure `Merge` functions in mappers copy ALL fields, including `UpdatedAt`.
+- **DO** use `...WithTransaction` variants of helpers when inside a `ReadWriteTransaction`.
+
+## Testing & Linting
+
+- **Precommit Suite**: Run `make precommit` to execute the full suite of Go tests, formatting, and linting.
+- **Linting**: Run `make go-lint` to lint all Go code using `golangci-lint`.
+- **Quick Test Iteration**: Because this project uses a multi-module workspace (`go.work`), to run tests quickly for a single package without running the whole suite, execute `go test` from _within_ the specific module directory, or provide the full module path:
+  ```bash
+  cd backend && go test -v ./pkg/...
+  # Or
+  go test -v github.com/GoogleChrome/webstatus.dev/lib/gcpspanner/...
+  ```
+- **Integration Tests**: Any changes to `lib/gcpspanner` **MUST** include integration tests using `testcontainers-go` against the Spanner emulator.
+
+## Documentation Updates
+
+When making significant architectural changes, adding new major endpoints, or altering the database schema:
+
+- Trigger the "Updating the Knowledge Base" prompt in `GEMINI.md` to ensure I am aware of the changes.
+- Update `docs/ARCHITECTURE.md` if the system boundaries change.
+- Update these very skills files if you introduce new established patterns.

skills/webstatus-backend/SKILL.md

@@ -0,0 +1,39 @@
+# How to Add a New Backend API Endpoint
+
+This project follows a **mandatory "spec-first"** process. You must define the API contract before writing any Go code to avoid compilation errors from missing types.
+
+## Step-by-Step Process
+
+### 1. Define the Contract (`openapi/backend/openapi.yaml`)
+
+- Open `openapi/backend/openapi.yaml`.
+- Define the new endpoint, parameters, and request/response schemas.
+- If using new data structures, define them in `components.schemas`.
+- Ensure you set a clear `operationId`.
+
+### 2. Generate Types
+
+- Run `make openapi`.
+- This reads the YAML and generates Go server stubs, request/response structs, and TypeScript client code in `lib/gen/backend/`.
+- **CRITICAL:** Do not proceed until this command completes successfully.
+
+### 3. Implement the HTTP Handler (`backend/pkg/httpserver/`)
+
+- Add a new method to the `Server` struct. The method name must match the `operationId`.
+- This handler parses the request, calls the adapter layer, and writes the response.
+
+### 4. Implement the Adapter Method (`lib/gcpspanner/spanneradapters/`)
+
+- Add a method to the `Backend` struct.
+- Translate generated API types (from `lib/gen/backend/`) to internal Spanner types.
+- Call the underlying Spanner client.
+
+### 5. Implement the Spanner Client Method (`lib/gcpspanner/`)
+
+- Add a method to the `Client` struct.
+- Contains the actual database logic (queries, writes, transactions), ideally using the mapper pattern.
+
+### 6. Add Tests
+
+- **Unit Test**: In `lib/gcpspanner/spanneradapters/backend_test.go` using mocks.
+- **Integration Test**: In `lib/gcpspanner/*_test.go` using `testcontainers-go` against a Spanner emulator.

skills/webstatus-backend/references/add-api-endpoint.md

@@ -0,0 +1,32 @@
+# The Go Mapper Pattern for Spanner
+
+Used for all interactions with the Spanner database to reduce boilerplate and ensure consistency. Defined in `lib/gcpspanner/client.go`.
+
+## Core Concept
+
+Use generic helpers configured with a "mapper" struct instead of custom query logic.
+
+### Generic Helpers
+
+- `newEntityReader`
+- `newEntityWriter`
+- `newEntitySynchronizer`
+
+### Mapper Interfaces
+
+- `baseMapper`: Defines the Spanner table name.
+- `readOneMapper`: Defines selection by key.
+- `mergeMapper`: Defines how to merge updates.
+- `deleteByStructMapper`: Defines deletion.
+- `childDeleteMapper`: Handles child deletions in batches (via `GetChildDeleteKeyMutations`) to stay under Spanner's mutation limit.
+
+## Transactional Usage
+
+- **DO** use the `...WithTransaction` variants (e.g., `createWithTransaction`, `updateWithTransaction`) inside a `ReadWriteTransaction`.
+- **DON'T** use standard helpers inside a transaction; they will attempt to start a new transaction and fail.
+- **DON'T** use `spanner.InsertStruct` manually.
+
+## Implementation Guardrails
+
+- **Merge Logic**: Ensure `Merge` or `mergeAndCheckChangedMapper` copies **all** fields. A missing field assignment will cause silent update failures.
+- **UpdatedAt**: Always set `UpdatedAt` to `spanner.CommitTimestamp` in the input struct before merging.

skills/webstatus-backend/references/mapper-pattern.md

@@ -0,0 +1,39 @@
+# Shared Go Libraries & Utilities
+
+The `lib/` directory contains shared code used by the `backend` and `workflows`.
+
+## Key Subdirectories
+
+- **`lib/gen`**: Auto-generated code (OpenAPI, JSON Schema, ANTLR). **Never edit manually.**
+- **`lib/gcpspanner`**: Spanner client, models, generic mapper helpers.
+- **`lib/gcpspanner/spanneradapters`**: Translation layer between external services and the DB client.
+- **`lib/generic`**: Utilities like `OptionallySet[T]` for handling optional fields.
+- **`lib/blobtypes`**: GCS blob storage definitions.
+
+## Blob Storage & Schema Evolution
+
+When storing persistent state (like saved search notifications in GCS blobs):
+
+- **Canonical vs. Storage Types**: Keep internal business logic (`lib/workertypes/comparables`) separate from persistent types (`lib/blobtypes/v1`).
+- **The `OptionallySet` Pattern**: To handle forward and backward compatibility, wrap new struct fields in `generic.OptionallySet[T]`.
+  - _Old Blob_: Field missing -> `IsSet: false`. Logic ignores it (Quiet Rollout).
+  - _New Data_: Field present -> `IsSet: true`. Logic processes it.
+- **DON'T** change the meaning of existing fields in `lib/blobtypes`; create `v2` if a breaking change is needed.
+
+## Utility Scripts
+
+Small CLI tools and helper scripts reside in `util/`:
+
+- `util/run_job.sh`: Runs data ingestion locally via Minikube.
+- `util/cmd/load_fake_data/`: Emulators fake data (`make dev_fake_data`).
+- `util/cmd/load_test_users/`: Emulators fake users (`make dev_fake_users`).
+- **DON'T** put production application logic in `util/`.
+
+## Verify, Don't Assume
+
+Always consult the canonical sources of truth instead of assuming based on general patterns:
+
+- **API Contracts**: `openapi/backend/openapi.yaml`
+- **Database Schema**: `infra/storage/spanner/migrations/`
+- **Search Grammar**: `antlr/FeatureSearch.g4`
+- **External Schemas**: `jsonschema/`

skills/webstatus-backend/references/shared-libraries.md

@@ -0,0 +1,21 @@
+# Go Spanner Query Best Practices
+
+## Database Migrations
+
+- **Creation**: Run `make spanner_new_migration` to create a new migration file in `infra/storage/spanner/migrations/`.
+- **Data Migrations**: For complex data migrations (e.g. renaming a feature key), use the generic migrator in `lib/gcpspanner/spanneradapters/migration.go`.
+
+## Scanning Rows
+
+- **DO** use `row.ToStruct(&yourStruct)` to scan results. It leverages struct tags (e.g., `spanner:"ColumnName"`) and is less error-prone.
+- **DON'T** manually scan columns using `r.ColumnByName`. This is verbose and fragile to schema changes.
+
+## Foreign Keys
+
+- **Cascade Deletes**: Use `ON DELETE CASCADE` for relationships.
+- **Batched Deletes**: If a cascade would delete thousands of rows, implement `GetChildDeleteKeyMutations` in the parent mapper to delete children in batches first.
+
+## Mappers vs Clients
+
+- **DO** look for existing mappers in `lib/gcpspanner/` (e.g. `webFeatureSpannerMapper`) before creating new ones.
+- **DO** translate business keys to internal IDs inside the `gcpspanner` client so that adapters/workflows remain unaware of internal DB IDs.

skills/webstatus-backend/references/spanner-best-practices.md

@@ -0,0 +1,46 @@
+---
+name: webstatus-e2e
+description: Use when writing, modifying, or debugging Playwright end-to-end (E2E) tests for webstatus.dev.
+---
+
+# webstatus-e2e
+
+This skill provides guidance for working with the End-to-End (E2E) test suite in `webstatus.dev`, which is built using Playwright and TypeScript.
+
+## Architecture & Location
+
+- **Directory**: The E2E tests are located in the `e2e/` directory.
+- **Framework**: **Playwright** with **TypeScript**.
+- **Configuration**: `playwright.config.ts` handles browser definitions, retries, and worker limits.
+
+## Guidelines (Do's and Don'ts)
+
+- **DO** add E2E tests for critical user journeys (e.g., login flows, complex search operations, saving a search).
+- **DON'T** write E2E tests for small component-level interactions; those belong in frontend unit tests (`frontend/src/**/*.test.ts`).
+- **DO** use resilient locators. Prefer using `data-testid` attributes (e.g., `page.getByTestId('submit-btn')`) over brittle CSS classes or XPath.
+- **DO** move the mouse to a neutral position (e.g., `page.mouse.move(0, 0)`) before taking visual snapshots to avoid flaky tests caused by unintended hover effects on UI elements.
+
+## Configuration & Stability
+
+- **Single Worker**: Tests currently operate on the same end-user accounts, which means they can interfere with each other if run concurrently. To ensure stability, `workers: 1` is strictly enforced in `playwright.config.ts`.
+- **Retries**: Playwright tests are configured to retry twice on failure only when running in a CI environment. If you want to simulate this locally and test flakiness, you can prefix your command with `CI=true` (e.g., `CI=true make playwright-test`).
+- **Browsers**: If you ever need to test against new browsers (e.g., mobile viewports, branded Edge/Chrome), modify the `projects` array within `playwright.config.ts`.
+
+## Execution & Debugging
+
+- For detailed instructions on rapid iteration, debugging CI failures, and using traces, see [references/execution-and-debugging.md](references/execution-and-debugging.md).
+
+## Commands Summary
+
+- Use the `Makefile` in the project root:
+  - `make playwright-test`: Sets up a fresh local environment and runs the test suite.
+  - `make playwright-ui`: Runs the tests in Playwright's interactive UI mode.
+  - `make playwright-debug`: Runs the tests in debug mode.
+  - `make playwright-update-snapshots`: Updates visual regression snapshots.
+
+## Documentation Updates
+
+When modifying playwright configuration, retries, or execution strategies:
+
+- Trigger the "Updating the Knowledge Base" prompt in `GEMINI.md` to ensure I am aware of the changes.
+- Update these very skills files if you introduce new established patterns for testing.

skills/webstatus-e2e/SKILL.md

@@ -0,0 +1,25 @@
+# Playwright Execution and Debugging
+
+## Rapid Iteration (`SKIP_FRESH_ENV`)
+
+If you already have a local environment running (via `make start-local`, `make port-forward-manual`, `make dev_fake_users`, and `make dev_fake_data`), you can skip the environment teardown and setup to run tests faster.
+
+**Command**: `SKIP_FRESH_ENV=1 make playwright-test`
+
+_Note: Use this only when your local environment is in a known good state._
+
+## Debugging GitHub Failures
+
+When E2E tests fail in CI, you can download the traces and reports locally for analysis.
+
+1. **Find the Run ID**: `make print-gh-runs`
+2. **Download the Report**: `make download-playwright-report-from-run-<RUN_ID>`
+3. **Open the Report**: `make playwright-open-report`
+4. **Inspect Traces**:
+   - List traces: `make playwright-show-traces`
+   - Open a specific trace: `npx playwright show-trace playwright-report/data/<trace_hash>.zip`
+
+## Local Interactive Tools
+
+- **Playwright UI**: `make playwright-ui` (best for seeing tests run live and inspecting locators).
+- **Step-through Debugging**: `make playwright-debug`.