@synapta/skills 0.1.1 → 0.2.0

package/skills/playwright-qa/references/cli.md

@@ -0,0 +1,116 @@
+# Playwright CLI Reference
+
+Use the wrapper script unless the CLI is already installed globally:
+
+```bash
+export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"
+"$PWCLI" --help
+```
+
+User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
+
+Optional convenience alias:
+
+```bash
+alias pwcli="$PWCLI"
+```
+
+## Core
+
+```bash
+pwcli open https://example.com
+pwcli close
+pwcli snapshot
+pwcli click e3
+pwcli dblclick e7
+pwcli type "search terms"
+pwcli press Enter
+pwcli fill e5 "user@example.com"
+pwcli drag e2 e8
+pwcli hover e4
+pwcli select e9 "option-value"
+pwcli upload ./document.pdf
+pwcli check e12
+pwcli uncheck e12
+pwcli eval "document.title"
+pwcli eval "el => el.textContent" e5
+pwcli dialog-accept
+pwcli dialog-accept "confirmation text"
+pwcli dialog-dismiss
+pwcli resize 1920 1080
+```
+
+## Navigation
+
+```bash
+pwcli go-back
+pwcli go-forward
+pwcli reload
+```
+
+## Keyboard
+
+```bash
+pwcli press Enter
+pwcli press ArrowDown
+pwcli keydown Shift
+pwcli keyup Shift
+```
+
+## Mouse
+
+```bash
+pwcli mousemove 150 300
+pwcli mousedown
+pwcli mousedown right
+pwcli mouseup
+pwcli mouseup right
+pwcli mousewheel 0 100
+```
+
+## Save as
+
+```bash
+pwcli screenshot
+pwcli screenshot e5
+pwcli pdf
+```
+
+## Tabs
+
+```bash
+pwcli tab-list
+pwcli tab-new
+pwcli tab-new https://example.com/page
+pwcli tab-close
+pwcli tab-close 2
+pwcli tab-select 0
+```
+
+## DevTools
+
+```bash
+pwcli console
+pwcli console warning
+pwcli network
+pwcli run-code "await page.waitForTimeout(1000)"
+pwcli tracing-start
+pwcli tracing-stop
+```
+
+## Sessions
+
+Use a named session to isolate work:
+
+```bash
+pwcli --session todo open https://demo.playwright.dev/todomvc
+pwcli --session todo snapshot
+```
+
+Or set an environment variable once:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION=todo
+pwcli open https://demo.playwright.dev/todomvc
+```

package/skills/playwright-qa/references/workflows.md

@@ -0,0 +1,95 @@
+# Playwright CLI Workflows
+
+Use the wrapper script and snapshot often.
+Assume `PWCLI` is set and `pwcli` is an alias for `"$PWCLI"`.
+In this repo, run commands from `output/playwright/<label>/` to keep artifacts contained.
+
+## Standard interaction loop
+
+```bash
+pwcli open https://example.com
+pwcli snapshot
+pwcli click e3
+pwcli snapshot
+```
+
+## Form submission
+
+```bash
+pwcli open https://example.com/form --headed
+pwcli snapshot
+pwcli fill e1 "user@example.com"
+pwcli fill e2 "password123"
+pwcli click e3
+pwcli snapshot
+pwcli screenshot
+```
+
+## Data extraction
+
+```bash
+pwcli open https://example.com
+pwcli snapshot
+pwcli eval "document.title"
+pwcli eval "el => el.textContent" e12
+```
+
+## Debugging and inspection
+
+Capture console messages and network activity after reproducing an issue:
+
+```bash
+pwcli console warning
+pwcli network
+```
+
+Record a trace around a suspicious flow:
+
+```bash
+pwcli tracing-start
+# reproduce the issue
+pwcli tracing-stop
+pwcli screenshot
+```
+
+## Sessions
+
+Use sessions to isolate work across projects:
+
+```bash
+pwcli --session marketing open https://example.com
+pwcli --session marketing snapshot
+pwcli --session checkout open https://example.com/checkout
+```
+
+Or set the session once:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION=checkout
+pwcli open https://example.com/checkout
+```
+
+## Configuration file
+
+By default, the CLI reads `playwright-cli.json` from the current directory. Use `--config` to point at a specific file.
+
+Minimal example:
+
+```json
+{
+  "browser": {
+    "launchOptions": {
+      "headless": false
+    },
+    "contextOptions": {
+      "viewport": { "width": 1280, "height": 720 }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+- If an element ref fails, run `pwcli snapshot` again and retry.
+- If the page looks wrong, re-open with `--headed` and resize the window.
+- If a flow depends on prior state, use a named `--session`.

package/skills/playwright-qa/scripts/playwright_cli.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v npx >/dev/null 2>&1; then
+  echo "Error: npx is required but not found on PATH." >&2
+  exit 1
+fi
+
+has_session_flag="false"
+for arg in "$@"; do
+  case "$arg" in
+    --session|--session=*)
+      has_session_flag="true"
+      break
+      ;;
+  esac
+done
+
+cmd=(npx --yes --package @playwright/cli playwright-cli)
+if [[ "${has_session_flag}" != "true" && -n "${PLAYWRIGHT_CLI_SESSION:-}" ]]; then
+  cmd+=(--session "${PLAYWRIGHT_CLI_SESSION}")
+fi
+cmd+=("$@")
+
+exec "${cmd[@]}"

package/skills/release-publish/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: release-publish
+description: Publish npm packages with Trusted Publishing (OIDC), provenance, Changesets, and pack-smoke tests. Never store `NPM_TOKEN` in CI secrets; never `npm unpublish`.
+triggers: [synapta release, npm publish, provenance, OIDC, trusted publishing, Changesets]
+network: allowlist
+tools: [Bash, Read, Edit]
+source:
+  origin: authored-by-synapta
+  reason: "skills.rest source returned 403 at adoption time; aggregator sites generally low-quality."
+  citation_patterns:
+    - "npm Trusted Publishing (https://docs.npmjs.com/trusted-publishers)"
+    - "npm provenance (https://docs.npmjs.com/generating-provenance-statements)"
+    - "Changesets (https://github.com/changesets/changesets)"
+    - "SLSA (https://slsa.dev)"
+---
+
+# Release & Publish
+
+Publish to npm from CI only, via Trusted Publishing (OIDC). 2FA enforced on the publishing org. Provenance on every release. SBOM attached to GitHub Releases.
+
+## Mandatory rules
+
+1. **No `NPM_TOKEN` in CI secrets**. Use Trusted Publishing — GitHub Actions ↔ npm via OIDC. If the org / package isn't on Trusted Publishing yet, do that first.
+2. **`publishConfig.provenance: true`** in every publishable `package.json`.
+3. **2FA enforced** on the publishing org for both account and `publish` actions.
+4. **Never `npm unpublish`** for a public release. Deprecate (`npm deprecate`) and publish a new patch.
+5. **Smoke after pack**: install the `.tgz` in a clean tempdir before publish. If the smoke fails, the publish doesn't run.
+
+## Process (Synapta canonical flow)
+
+1. `pnpm changeset` — record changes (semver + summary).
+2. `pnpm changeset version` — bumps versions + writes CHANGELOG entries.
+3. Open PR, merge to `main`.
+4. `release.yml` workflow runs on `main`:
+   - lint + typecheck + test + build
+   - `pnpm pack` each publishable package
+   - smoke: clean tempdir, `npm i ./pkg-*.tgz`, run the package's CLI/`--version`
+   - security scans (Trivy, gitleaks, semgrep, osv-scanner)
+   - **OIDC publish**: `npm publish --provenance`
+   - post-publish: `npx <pkg>@<tag> --version` in fresh tempdir
+   - attach CycloneDX SBOM + provenance statement to GitHub Release
+
+## `package.json` required fields for publishable packages
+
+```jsonc
+{
+  "name": "@scope/pkg",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md", "LICENSE"],
+  "types": "./dist/index.d.ts",
+  "engines": { "node": ">=22" },
+  "publishConfig": { "access": "public", "provenance": true }
+}
+```
+
+## Tags
+
+| Tag | Source branch | Purpose |
+|---|---|---|
+| `next` | every merge to `main` | bleeding-edge, integration testing |
+| `beta` | release candidate | external testers |
+| `latest` | tagged release | stable, default `npm install` |
+
+## Failure modes
+
+- **Provenance build fails** → workflow must abort before publish; provenance is not optional
+- **Smoke install fails on Windows/Linux/macOS** → fix the cause; do not "skip on $OS"
+- **Publish succeeds but verify fails** → open an incident, do not retry blindly; might be a registry cache issue
+- **Deprecate after publish** → use `npm deprecate '<pkg>@<version>' '<reason>'`; never `unpublish`
+
+## Rollback
+
+There is no "unship" for npm. Options, in order of preference:
+1. Publish a patch (`x.y.z+1`) that reverts the breaking change.
+2. `npm deprecate` the bad version pointing at the patch.
+3. If a secret was published: rotate the secret first; deprecate the version with a note; consider `unpublish` only within the 72-hour window AND if downstream impact is zero. This requires coordination with npm support for popular packages.
+
+## Anti-patterns
+
+- Long-lived publish tokens stored as secrets
+- Publishing from a developer laptop "just this once"
+- Skipping the post-pack smoke "to save 30 seconds"
+- Using `npm version` (manual) instead of Changesets in a monorepo

package/skills/repo-bootstrap/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: repo-bootstrap
+synapta_original_name: agent-rules
+triggers: [synapta new, synapta repo init, AGENTS.md, scaffold project, .claude overlay, .codex overlay]
+network: allowlist
+source:
+  origin: https://github.com/netresearch/agent-rules-skill
+  path: skills/agent-rules
+  commit: 9d1c57d1a131
+  license: MIT AND CC-BY-SA-4.0 (Netresearch DTT GmbH)
+  adapted: light-touch
+description: "Use when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents."
+license: "(MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.0"
+compatibility: "Requires bash 4.3+, jq 1.5+, git 2.0+."
+metadata:
+  author: Netresearch DTT GmbH
+  version: "3.9.1"
+  repository: https://github.com/netresearch/agent-rules-skill
+allowed-tools: Bash(git:*) Bash(jq:*) Bash(grep:*) Bash(find:*) Bash(bash:*) Read Glob Grep
+---
+
+# AGENTS.md Generator Skill
+
+Generate and maintain AGENTS.md files following the [agents.md convention](https://agents.md/). AGENTS.md is FOR AGENTS, not humans.
+
+## When to Use
+
+- Creating or updating AGENTS.md for new/existing projects
+- Standardizing agent documentation across repositories
+- Checking if AGENTS.md files are current with recent code changes
+- Onboarding AI agents to an unfamiliar codebase
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/generate-agents.sh PATH` | Generate AGENTS.md files |
+| `scripts/validate-structure.sh PATH` | Validate structure compliance |
+| `scripts/check-freshness.sh PATH` | Check if files are outdated |
+| `scripts/verify-content.sh PATH` | Verify documented files/commands match codebase |
+| `scripts/verify-commands.sh PATH` | Verify documented commands execute |
+| `scripts/detect-project.sh PATH` | Detect language, version, build tools |
+| `scripts/detect-scopes.sh PATH` | Identify directories needing scoped files |
+| `scripts/extract-commands.sh PATH` | Extract commands from build configs |
+| `scripts/extract-ci-rules.sh PATH` | Extract CI quality gates and version matrix |
+| `scripts/extract-architecture-rules.sh PATH` | Extract module boundaries |
+| `scripts/extract-adrs.sh PATH` | Extract architectural decision records |
+| `scripts/extract-github-rulesets.sh PATH` | Extract GitHub rulesets and merge rules |
+
+See `references/scripts-guide.md` for full options.
+
+## Workflow
+
+1. **Detect**: `detect-project.sh` + `detect-scopes.sh` to identify stacks and subsystems
+2. **Extract**: `extract-commands.sh`, `extract-ci-rules.sh`, etc. to gather facts
+3. **Generate**: `generate-agents.sh` with `--style=thin` (default) or `--verbose`
+4. **Verify**: `verify-content.sh` + `verify-commands.sh` -- MANDATORY before done
+
+Use `--update` to preserve human-curated content outside `<!-- GENERATED -->` markers.
+
+## Core Principles
+
+- **Structured over Prose** -- tables parse faster than paragraphs
+- **Never Fabricate** -- only document what exists; verify every command and path
+- **Pointer Principle** -- point to files, don't duplicate content
+- **Auto Symlinks** -- CLAUDE.md/GEMINI.md symlinks by default (see [`ai-tool-compatibility.md`](references/ai-tool-compatibility.md))
+
+## References
+
+| File | Contents |
+|------|----------|
+| [`verification-guide.md`](references/verification-guide.md) | Verification steps, design principles |
+| [`scripts-guide.md`](references/scripts-guide.md) | Script options, validation checklist |
+| [`ai-tool-compatibility.md`](references/ai-tool-compatibility.md) | 16-agent compatibility matrix |
+| [`output-structure.md`](references/output-structure.md) | Root/scoped sections |
+| [`git-hooks-setup.md`](references/git-hooks-setup.md) | Hook framework detection and setup |
+| [`examples/`](references/examples/) | Complete examples |
+| [`ai-contribution-guidelines.md`](references/ai-contribution-guidelines.md) | "3 Cs" framework for AI contributions (Comprehension, Context, Continuity) |
+| [`directory-coverage.md`](references/directory-coverage.md) | Full coverage rationale for scoped AGENTS.md files |
+
+## Templates
+
+Root: `assets/root-thin.md` (default), `root-verbose.md`. Scoped: `assets/scoped/` -- `backend-go.md`, `backend-php.md`, `python-modern.md`, `typo3.md`, `symfony.md`, `skill-repo.md`, `cli.md`, `frontend-typescript.md`, `oro.md`.
+
+## Supported Projects
+
+Go, PHP (Composer/Laravel/Symfony/TYPO3/Oro), TypeScript (React/Next/Vue/Node), Python (pip/poetry/ruff/mypy), Skill repos, Hybrid (multi-stack with auto-scoping).
+
+## See Also
+
+- [`agent-harness-skill`](https://github.com/netresearch/agent-harness-skill) — broader agent-readiness harness (CI verification, enforcement). Invokes this skill when AGENTS.md is missing.
+- [`skill-repo-skill`](https://github.com/netresearch/skill-repo-skill) — skill-repo structure (plugin.json, split licensing, release workflows).

package/skills/repo-bootstrap/assets/example-workflows/validate-agents.yml

@@ -0,0 +1,89 @@
+# Example GitHub Actions workflow for validating AGENTS.md files
+# Copy this to your repository's .github/workflows/ directory
+#
+# This workflow runs on:
+# - Push/PR to any AGENTS.md file
+# - Manual dispatch
+#
+# Customize the validation steps to match your project's setup.
+
+name: Validate AGENTS.md
+
+on:
+  push:
+    paths:
+      - 'AGENTS.md'
+      - '**/AGENTS.md'
+  pull_request:
+    paths:
+      - 'AGENTS.md'
+      - '**/AGENTS.md'
+  workflow_dispatch:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check AGENTS.md exists
+        run: |
+          if [ ! -f "AGENTS.md" ]; then
+            echo "ERROR: AGENTS.md not found in repository root"
+            exit 1
+          fi
+          echo "AGENTS.md found"
+
+      - name: Validate structure
+        run: |
+          # Check for required sections (customize this list for your needs)
+          required_sections=(
+            "## Overview"
+            "## Commands"
+          )
+
+          for section in "${required_sections[@]}"; do
+            if ! grep -qi "^$section" AGENTS.md; then
+              echo "WARNING: Missing section: $section"
+            fi
+          done
+          echo "Structure validation complete"
+
+      - name: Check for unresolved placeholders
+        run: |
+          # Fail if {{PLACEHOLDER}} patterns exist
+          if grep -E '\{\{[A-Z][A-Z0-9_]*\}\}' AGENTS.md; then
+            echo "ERROR: Found unresolved placeholders"
+            exit 1
+          fi
+          echo "No unresolved placeholders"
+
+      - name: Check for stale content
+        run: |
+          # Error if unresolved template placeholders exist
+          if grep -qE '\{\{[A-Z_]+\}\}' AGENTS.md; then
+            echo "ERROR: Found unresolved template placeholders - regenerate AGENTS.md"
+            exit 1
+          fi
+
+          # Check freshness (optional - customize days threshold)
+          if grep -q "Last updated:" AGENTS.md; then
+            last_updated=$(grep "Last updated:" AGENTS.md | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' | head -1)
+            if [ -n "$last_updated" ]; then
+              days_old=$(( ($(date +%s) - $(date -d "$last_updated" +%s)) / 86400 ))
+              if [ "$days_old" -gt 90 ]; then
+                echo "WARNING: AGENTS.md is $days_old days old - consider updating"
+              fi
+            fi
+          fi
+          echo "Freshness check complete"
+
+      # Optional: Verify documented commands work
+      # Uncomment and customize for your project
+      # - name: Verify commands
+      #   run: |
+      #     # Example: check that npm scripts exist
+      #     if [ -f "package.json" ]; then
+      #       # Extract commands from AGENTS.md and verify they exist
+      #       echo "Verifying npm commands..."
+      #     fi

package/skills/repo-bootstrap/assets/root-thin.md

@@ -0,0 +1,141 @@
+<!-- FOR AI AGENTS - Human readability is a side effect, not a goal -->
+<!-- Managed by agent: keep sections and order; edit content, not structure -->
+<!-- Last updated: {{TIMESTAMP}} | Last verified: {{VERIFIED_TIMESTAMP}} -->
+
+# AGENTS.md
+
+**Precedence:** the **closest `AGENTS.md`** to the files you're changing wins. Root holds global defaults only.
+
+## Commands{{VERIFIED_STATUS}}
+> Source: {{COMMAND_SOURCE}} — CI-sourced commands are most reliable
+
+<!-- AGENTS-GENERATED:START commands -->
+| Task | Command | ~Time |
+|------|---------|-------|
+| Typecheck | {{TYPECHECK_CMD}} | {{TYPECHECK_TIME}} |
+| Lint | {{LINT_CMD}} | {{LINT_TIME}} |
+| Format | {{FORMAT_CMD}} | {{FORMAT_TIME}} |
+| Test (single) | {{TEST_SINGLE_CMD}} | ~2s |
+| Test (all) | {{TEST_CMD}} | {{TEST_TIME}} |
+| Build | {{BUILD_CMD}} | {{BUILD_TIME}} |
+<!-- AGENTS-GENERATED:END commands -->
+
+> If commands fail, verify against Makefile/package.json/composer.json or ask user to update.
+
+## Response Style
+- Answer first, elaborate only if needed. No sycophantic openers ("Great question!", "Absolutely!").
+- For yes/no or status questions, lead with the answer.
+- Skip preamble. Match response length to task complexity.
+
+## Workflow
+1. **Before coding**: Read nearest `AGENTS.md` + check Golden Samples for the area you're touching
+2. **After each change**: Run the smallest relevant check (lint → typecheck → single test)
+3. **Before committing**: Run full test suite if changes affect >2 files or touch shared code
+4. **Before claiming done**: Run verification and **show output as evidence** — never say "try again", "should work now", "tested", "verified", or "all green" without pasted command output in the same turn
+
+## File Map
+<!-- AGENTS-GENERATED:START filemap -->
+```
+{{FILE_MAP}}
+```
+<!-- AGENTS-GENERATED:END filemap -->
+
+## Golden Samples (follow these patterns)
+<!-- AGENTS-GENERATED:START golden-samples -->
+| For | Reference | Key patterns |
+|-----|-----------|--------------|
+{{GOLDEN_SAMPLES}}
+<!-- AGENTS-GENERATED:END golden-samples -->
+
+## Utilities (check before creating new)
+<!-- AGENTS-GENERATED:START utilities -->
+| Need | Use | Location |
+|------|-----|----------|
+{{UTILITIES_LIST}}
+<!-- AGENTS-GENERATED:END utilities -->
+
+## Heuristics (quick decisions)
+<!-- AGENTS-GENERATED:START heuristics -->
+| When | Do |
+|------|-----|
+{{HEURISTICS}}
+| Adding dependency | Ask first - we minimize deps |
+| Unsure about pattern | Check Golden Samples above |
+<!-- AGENTS-GENERATED:END heuristics -->
+
+## Repository Settings
+<!-- AGENTS-GENERATED:START repo-settings -->
+{{REPO_SETTINGS}}
+<!-- AGENTS-GENERATED:END repo-settings -->
+
+<!-- AGENTS-GENERATED:START ci-rules -->
+{{CI_RULES_SECTION}}
+<!-- AGENTS-GENERATED:END ci-rules -->
+
+## Key Decisions
+<!-- AGENTS-GENERATED:START key-decisions -->
+{{KEY_DECISIONS}}
+<!-- AGENTS-GENERATED:END key-decisions -->
+
+## Boundaries
+
+### Always Do
+- Run pre-commit checks before committing
+- Add tests for new code paths
+- Use conventional commit format: `type(scope): subject`
+- Use **atomic commits** (one logical change per commit); preserve signatures, keep bisection useful
+- **Show test output as evidence before claiming work is complete** — never say "try again", "should work now", "tested", "verified", or "all green" without pasted command output
+- Before any edit, verify `pwd` resolves inside the intended repo worktree — not `.bare/`, not `~/.claude/skills/…`, not `~/.claude/plugins/cache/…` (those are read-only caches that get clobbered on update)
+- For upstream dependency fixes: run **full** test suite, not just affected tests
+- Force-push only with `--force-with-lease`
+{{LANGUAGE_CONVENTIONS}}
+
+### Ask First
+- Adding new dependencies
+- Modifying CI/CD configuration
+- Changing public API signatures
+- Running full e2e test suites
+- Repo-wide refactoring or rewrites
+- Operations that touch >3 repos (produce a dry-run plan first)
+
+### Never Do
+- Commit secrets, credentials, or sensitive data
+- Modify vendor/, node_modules/, or generated files
+- Push directly to main/master branch — open a PR
+- Merge a PR before all review threads are resolved
+- Squash commits during merge or rebase unless the user explicitly asked
+- Edit installed skill/plugin cache paths (`~/.claude/skills/`, `~/.claude/plugins/cache/`, `**/.bare/**`) — always the source worktree
+- Reply to review comments with bare "Addressed" or "Fixed" — cite the resolving commit SHA
+- Delete migration files or schema changes
+- Use `secrets: inherit` in reusable GitHub Actions workflows (pass secrets explicitly)
+{{LANGUAGE_SPECIFIC_NEVER}}
+
+## Contributing (for AI agents)
+- **Comprehension**: Understand the problem before submitting code. Read the linked issue, understand *why* the change is needed, not just *what* to change.
+- **Context**: Every PR must explain the trade-offs considered and link to the issue it addresses. Disclose AI assistance if the project requires it.
+- **Continuity**: Respond to review feedback. Drive-by PRs without follow-up will be closed.
+
+<!-- AGENTS-GENERATED:START module-boundaries -->
+{{MODULE_BOUNDARIES}}
+<!-- AGENTS-GENERATED:END module-boundaries -->
+
+## Codebase State
+<!-- AGENTS-GENERATED:START codebase-state -->
+{{CODEBASE_STATE}}
+<!-- AGENTS-GENERATED:END codebase-state -->
+
+## Terminology
+| Term | Means |
+|------|-------|
+{{TERMINOLOGY}}
+
+## Scoped AGENTS.md (MUST read when working in these directories)
+<!-- AGENTS-GENERATED:START scope-index -->
+{{SCOPE_INDEX}}
+<!-- AGENTS-GENERATED:END scope-index -->
+
+> **Agents**: When you read or edit files in a listed directory, you **must** load its AGENTS.md first. It contains directory-specific conventions that override this root file.
+
+## When instructions conflict
+The nearest `AGENTS.md` wins. Explicit user prompts override files.
+{{LANGUAGE_SPECIFIC_CONFLICT_RESOLUTION}}