Englisch

# TypeScript library taste
- Use pnpm as the package manager. Confidence: 0.95
- Enable strict mode and noUncheckedIndexedAccess in tsconfig. Confidence: 0.95
- Build with tsup and emit both ESM and CJS with .d.ts files. Confidence: 0.90
- Declare the exports map in package.json instead of relying on main. Confidence: 0.90
- Test with vitest and keep tests next to source as *.test.ts. Confidence: 0.90
- Use Changesets for versioning and changelogs. Confidence: 0.85
- Lint and format with Biome instead of ESLint plus Prettier. Confidence: 0.70
- Keep runtime dependencies at zero where practical. Confidence: 0.85
- Mark the package with "sideEffects": false to enable tree shaking. Confidence: 0.85
- Prefer named exports over default exports. Confidence: 0.90
- Validate untrusted input with zod and infer types from the schemas. Confidence: 0.80
- Run publint and arethetypeswrong in CI before every release. Confidence: 0.80
- Use type-only imports (import type) for types. Confidence: 0.85
- Publish with npm provenance enabled from GitHub Actions. Confidence: 0.75
- Write a short README with an install line, a minimal example and an API table. Confidence: 0.90
- Start versions at 0.1.0 and follow semver strictly once stable. Confidence: 0.70

---
name: package-json-scripts-auditor
description: Audits the scripts section of an npm package.json for safety and clarity: risky install hooks, curl-pipe-to-shell, rm -rf, sudo, inline secrets, unpinned npx, non-portable shell syntax, placeholder test scripts, missing standard scripts, and confusing names. Use when reviewing a repo, a dependency, or a PR that changes package.json scripts. Includes a stdlib Python auditor with severity levels.
---

# package.json Scripts Auditor

You review the `scripts` block of a Node.js `package.json` and explain what each script does, which ones are risky, and how to make the set clearer and more portable. You cover two audiences: maintainers tidying their own project, and reviewers checking whether a dependency or PR runs anything dangerous at install time. You never run the scripts yourself; you read them.

## Files in this skill

- `scripts/audit_scripts.py` - reads a package.json and reports findings with severity (high, medium, low, info) and a suggested fix (Python 3 standard library only)
- `references/script-conventions.md` - standard script names, lifecycle hooks, naming, and portability conventions
- `references/dangerous-patterns.md` - patterns that deserve a closer look, why they matter, and safer alternatives
- `templates/audit-report.md` - the report shape to return
- `examples/package.json` - a deliberately messy example to practice on

## Workflow

### 1. Collect context
Ask for the full `package.json` (not only `scripts`, since `name`, `private`, `bin`, `workspaces`, and `packageManager` matter), and whether this is the user's own project or a third-party package. Ask which OS the team uses (Windows support changes portability advice).

### 2. Run the auditor
```
python3 scripts/audit_scripts.py path/to/package.json
python3 scripts/audit_scripts.py --json path/to/package.json
python3 scripts/audit_scripts.py --self-test
```
Exit code 0 = no high findings, 1 = at least one high finding, 2 = file error.

### 3. Review manually
The script is pattern-based. Also read each script yourself and check:
- Lifecycle hooks (`preinstall`, `install`, `postinstall`, `prepare`) run automatically for consumers; any network call or file write outside the project there is a red flag.
- Scripts that call other files (`node scripts/setup.js`, `sh ./build.sh`): ask to see those files before calling the package safe.
- Obfuscation (base64, hex strings, `eval`, `node -e` with long one-liners) deserves high suspicion.

### 4. Recommend
Use `references/script-conventions.md` and `references/dangerous-patterns.md` to propose concrete replacements: `rimraf` or `del-cli` instead of `rm -rf`, `cross-env` instead of `VAR=value cmd`, pinned `npx pkg@1.2.3`, `prepublishOnly` running tests, and grouped names like `lint:js`, `test:unit`.

### 5. Report
Fill `templates/audit-report.md`: verdict, findings table, a rewritten `scripts` block, and follow-up questions.

## Rules

- Rate severity by impact: anything that can run remote code or delete files outside the project on install is high.
- Do not accuse authors of malice; describe the behavior and the risk.
- Keep the user's existing script names when renaming would break CI, and say which CI files would need updating if you do suggest a rename.
- Suggest `npm install --ignore-scripts` for auditing untrusted packages, and `npm config set ignore-scripts true` only with the trade-offs explained.
FILE:references/dangerous-patterns.md
# Dangerous and Risky Script Patterns

| Pattern | Example | Why it matters | Safer alternative | Severity |
|---|---|---|---|---|
| Remote script piped to a shell | `curl -fsSL https://x.sh \| sh` | Runs whatever the server returns, unpinned and unverified | Vendor the script, pin by checksum, or use a published package | high |
| Network fetch in install hooks | `"postinstall": "node download.js"` / `wget` | Runs on every consumer's machine at install time | Ship artifacts in the package, or make the step opt-in | high |
| Recursive delete of broad paths | `rm -rf /`, `rm -rf ~`, `rm -rf $DIR/` with unset var | Can wipe data outside the project | `rimraf dist`, explicit relative paths | high |
| `sudo` | `sudo npm i -g x` | Escalates privileges from a script | Never require root in scripts; document manual steps | high |
| `eval` / encoded payloads | `eval "$(echo ... \| base64 -d)"`, `node -e "...Buffer.from('..','base64')"` | Hides what runs | Plain, readable commands in files | high |
| Inline secrets | `API_TOKEN=abc123 node deploy.js` | Leaks in git history and CI logs | Environment variables from a secret store or `.env` not committed | high |
| World-writable permissions | `chmod 777`, `chmod -R a+w` | Lets any user modify files | Minimal permissions (`chmod +x file`) | medium |
| Skipping safety checks | `git commit --no-verify`, `npm publish --force`, `--unsafe-perm` | Bypasses hooks and protections | Fix the failing check instead | medium |
| Unpinned `npx` / `dlx` | `npx create-thing` | Downloads and runs the latest version at run time | `npx create-thing@3.2.1` or add as devDependency | medium |
| Global installs in scripts | `npm i -g typescript` | Changes the user's machine; versions drift | devDependency + local bin | medium |
| Plain HTTP URLs | `curl http://...` | Can be tampered with in transit | HTTPS | medium |
| `git push` / `npm publish` in hooks | `"postbuild": "npm publish"` | Accidental releases | Explicit `release` script run by CI | medium |
| Non-portable shell syntax | `NODE_ENV=prod`, `export`, `cp -r` | Breaks on Windows | `cross-env`, `cpy-cli`, Node scripts | low |
| Placeholder test | `echo "Error: no test specified" && exit 1` | CI fails or tests silently missing | Real test runner | low |
| Very long one-liners | > 200 chars | Hard to review; hides risk | Move to a script file | low |

## Review tips
- For third-party packages: inspect with `npm pack <pkg>` and read the tarball, or install with `--ignore-scripts` first.
- Follow file references: `node scripts/postinstall.js` is only as safe as that file.
- Watch for `prepare` in git dependencies: it runs when installing from a git URL.
FILE:references/script-conventions.md
# npm Script Conventions

## Standard names
| Script | Purpose | Run with |
|---|---|---|
| `start` | Run the app in production mode | `npm start` |
| `dev` | Run with watch / hot reload | `npm run dev` |
| `build` | Produce build output | `npm run build` |
| `test` | Run the test suite (CI default) | `npm test` |
| `lint` | Static checks | `npm run lint` |
| `format` | Apply formatter | `npm run format` |
| `typecheck` | `tsc --noEmit` or similar | `npm run typecheck` |
| `clean` | Remove build artifacts | `npm run clean` |

Use a colon to group variants: `test:unit`, `test:e2e`, `lint:css`, `build:docs`. Use `npm-run-all` / `run-p` / `run-s`, or `npm run a && npm run b`, to compose them.

## Lifecycle hooks
| Hook | Runs when | Notes |
|---|---|---|
| `preinstall`, `install`, `postinstall` | Your package is installed, including as a dependency | Runs on every consumer's machine. Keep empty unless compiling native code. |
| `prepare` | After local `npm install` and before `npm publish`/`npm pack`; also for git dependencies | Good for building or setting up git hooks (e.g. `husky`). |
| `prepublishOnly` | Only before `npm publish` | Put `npm test && npm run build` here. |
| `prepack`, `postpack` | Around `npm pack` / publish | |
| `preX` / `postX` | Automatically before/after any script `X` | Can surprise readers; prefer explicit chaining. pnpm does not run them by default. |

## Portability
- Windows `cmd.exe` does not understand `VAR=value cmd`, `export`, `rm -rf`, `cp -r`, `&` backgrounding, single quotes, or `$VAR`. Use `cross-env`, `rimraf`, `cpy-cli`, `concurrently`, and Node scripts.
- `&&` works in both shells; `;` does not run the same way in `cmd.exe`.
- Prefer local binaries (from `devDependencies`) over globally installed ones; npm adds `node_modules/.bin` to PATH inside scripts.

## Clarity
- One job per script; move long logic (> ~120 characters) into `scripts/*.js` or `*.mjs` files.
- Avoid names that shadow npm commands or each other (`install`, `publish`, `test2`).
- Replace the default `echo "Error: no test specified" && exit 1` with a real test command or remove it.
- Document unusual scripts in the README.
- Set `"private": true` for apps that must never be published.
FILE:templates/audit-report.md
# package.json Scripts Audit

**Package:** `<name>@<version>`  |  **Owner:** own project / third-party  |  **Private:** yes/no
**Verdict:** Safe / Needs changes / Do not install until reviewed
**Counts:** high `<n>`, medium `<n>`, low `<n>`, info `<n>`

## Script inventory
| Script | What it does (plain words) | Runs automatically? |
|---|---|---|
| `build` | | no |
| `postinstall` | | yes, on every install |

## Findings
| # | Severity | Script | Pattern | Why it matters | Fix |
|---|---|---|---|---|---|
| 1 | high | | | | |

## Suggested scripts block
```json
{
  "scripts": {
  }
}
```

## Also check
- Files referenced by scripts: `<list>`
- CI files that call renamed scripts: `<list>`
- devDependencies to add: `<rimraf, cross-env, ...>`

## Questions for the maintainer
1.
FILE:examples/package.json
{
  "name": "acme-dashboard",
  "version": "0.4.2",
  "description": "Internal dashboard (example with deliberately messy scripts for auditing practice)",
  "main": "dist/index.js",
  "scripts": {
    "preinstall": "curl -fsSL http://get.example.com/setup.sh | sh",
    "postinstall": "node scripts/fetch-assets.js",
    "start": "NODE_ENV=production node dist/index.js",
    "dev": "nodemon src/index.ts",
    "build": "rm -rf dist && tsc -p .",
    "test": "echo \"Error: no test specified\" && exit 1",
    "deploy": "API_TOKEN=sk_live_example123 node scripts/deploy.js",
    "fix-perms": "chmod -R 777 ./uploads",
    "commit": "git add -A && git commit --no-verify -m wip",
    "gen": "npx create-acme-widget",
    "postbuild": "npm publish",
    "setup": "sudo npm install -g typescript"
  },
  "devDependencies": {
    "nodemon": "^3.1.0",
    "typescript": "^5.6.0"
  }
}
FILE:scripts/audit_scripts.py
#!/usr/bin/env python3
"""Audit the "scripts" section of an npm package.json.

Usage:
    python3 audit_scripts.py path/to/package.json [--json]
    python3 audit_scripts.py --self-test

Exit codes: 0 = no high findings, 1 = high findings present, 2 = file error.
Pattern-based: always read the scripts and any files they call yourself.
Python 3 standard library only.
"""
import argparse
import json
import re
import sys

INSTALL_HOOKS = {"preinstall", "install", "postinstall", "prepare"}
SEVERITY_ORDER = {"high": 0, "medium": 1, "low": 2, "info": 3}

# (id, regex, severity, message, fix)
PATTERNS = [
    ("pipe-to-shell", r"\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba|z|da)?sh\b", "high",
     "Downloads a remote script and pipes it into a shell.",
     "Vendor the script, verify a checksum, or use a pinned package."),
    ("broad-rm", r"\brm\s+-[a-z]*r[a-z]*f?[a-z]*\s+(/|~|\$HOME|\$\{?\w+\}?/?)(\s|$|&|;)", "high",
     "Recursive delete of a root, home, or variable-based path.",
     "Delete an explicit relative path, e.g. `rimraf dist`."),
    ("sudo", r"(^|[\s;&|])sudo\s", "high",
     "Uses sudo inside an npm script.",
     "Never require root from scripts; document any manual setup."),
    ("eval-or-encoded", r"\beval\b|base64\s+(-d|--decode)|Buffer\.from\([^)]*base64", "high",
     "Uses eval or decodes an encoded payload, hiding what runs.",
     "Replace with plain, readable commands in a script file."),
    ("inline-secret", r"\b[A-Z0-9_]*(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|APIKEY|PRIVATE_KEY)[A-Z0-9_]*=(?!\$)\S+", "high",
     "Hard-coded secret value in a script.",
     "Read secrets from the environment or a secret manager; rotate the exposed value."),
    ("chmod-777", r"\bchmod\s+(-R\s+)?(0?777|a\+w|o\+w)\b", "medium",
     "Makes files world-writable.",
     "Use minimal permissions, e.g. `chmod +x bin/cli.js`."),
    ("skip-checks", r"--no-verify|--force\b|--unsafe-perm|--ignore-engines", "medium",
     "Bypasses safety checks or hooks.",
     "Fix the underlying failure instead of skipping the check."),
    ("unpinned-npx", r"\b(npx|pnpm\s+dlx|bunx|yarn\s+dlx)\s+(-y\s+|--yes\s+)?(?!-)(@?[\w./-]+)(?=\s|$)(?<!@latest)", "medium",
     "Runs a package via npx/dlx without a pinned version.",
     "Pin it (`npx pkg@1.2.3`) or add it to devDependencies."),
    ("global-install", r"\bnpm\s+(i|install)\s+(-g|--global)\b|\byarn\s+global\s+add\b", "medium",
     "Installs packages globally from a script.",
     "Add as a devDependency and use the local binary."),
    ("plain-http", r"http://(?!localhost|127\.0\.0\.1)", "medium",
     "Fetches over plain HTTP.",
     "Use HTTPS."),
    ("publish-or-push", r"\bnpm\s+publish\b|\bgit\s+push\b", "medium",
     "Publishes or pushes from a script.",
     "Keep releases in an explicit `release` script or CI job."),
    ("non-portable-env", r"(^|&&\s*|;\s*)[A-Z_][A-Z0-9_]*=\S+\s+\S", "low",
     "Inline env assignment `VAR=value cmd` does not work in Windows cmd.",
     "Use `cross-env VAR=value cmd`."),
    ("non-portable-cmd", r"(^|[\s;&|])(rm\s+-|cp\s+-r|export\s+\w+=|mv\s)", "low",
     "Unix-only shell command.",
     "Use rimraf / cpy-cli / a Node script for Windows support."),
]

PLACEHOLDER_TEST = re.compile(r'no test specified', re.I)
NETWORK = re.compile(r"\b(curl|wget|git\s+clone|Invoke-WebRequest)\b|https?://", re.I)
FILE_REF = re.compile(r"\b(?:node|sh|bash|python3?)\s+(\.?/?[\w./-]+\.(?:m?js|cjs|ts|sh|py))")


def audit(pkg):
    findings = []

    def add(sev, script, rule, msg, fix):
        findings.append({"severity": sev, "script": script, "rule": rule, "message": msg, "fix": fix})

    scripts = pkg.get("scripts")
    if not isinstance(scripts, dict) or not scripts:
        add("info", None, "no-scripts", "No scripts section found.", "Add standard scripts such as build, test, lint.")
        return findings

    for name, cmd in scripts.items():
        if not isinstance(cmd, str):
            add("medium", name, "not-string", "Script value is not a string.", "Make it a shell command string.")
            continue
        for rule, rx, sev, msg, fix in PATTERNS:
            if re.search(rx, cmd):
                add(sev, name, rule, msg, fix)
        if name in INSTALL_HOOKS:
            if name == "prepare":
                add("info", name, "install-hook", "`prepare` runs on local install and for git dependencies.",
                    "Keep it limited to build or git-hook setup.")
            else:
                add("medium", name, "install-hook", f"`{name}` runs automatically on every consumer's install.",
                    "Remove it unless it compiles native code; move setup to an explicit script.")
            if NETWORK.search(cmd):
                add("high", name, "network-in-install-hook", "Install hook performs network access.",
                    "Ship assets in the package or make the download opt-in.")
            for ref in FILE_REF.findall(cmd):
                add("high" if name != "prepare" else "medium", name, "install-hook-runs-file",
                    f"Install hook executes `{ref}`; its contents decide the real risk.",
                    f"Read `{ref}` before trusting this package.")
        if name == "test" and PLACEHOLDER_TEST.search(cmd):
            add("low", name, "placeholder-test", "Default placeholder test script.", "Wire up a real test runner.")
        if len(cmd) > 200:
            add("low", name, "long-script", f"Script is {len(cmd)} characters long.", "Move the logic into a script file.")
        if name.startswith(("pre", "post")) and name not in INSTALL_HOOKS and name not in ("prepublishOnly", "prepack", "postpack"):
            base = name[3:] if name.startswith("pre") else name[4:]
            if base in scripts:
                add("info", name, "implicit-hook", f"Runs automatically around `{base}` (pnpm skips these by default).",
                    f"Consider chaining explicitly inside `{base}`.")
        if not re.match(r"^[a-z0-9][a-z0-9:._-]*$", name):
            add("low", name, "naming", "Script name uses unusual characters or uppercase.",
                "Use lowercase names grouped with colons, e.g. `test:unit`.")

    for std in ("build", "test", "lint"):
        if std not in scripts and not any(k.startswith(std + ":") for k in scripts):
            add("info", None, "missing-standard", f"No `{std}` script.", f"Add a `{std}` script if the project needs one.")
    if not pkg.get("private") and "prepublishOnly" not in scripts and "publish-or-push" not in [f["rule"] for f in findings]:
        add("info", None, "no-prepublishonly", "Package is publishable but has no `prepublishOnly` check.",
            "Add `\"prepublishOnly\": \"npm test && npm run build\"` or set `\"private\": true`.")
    findings.sort(key=lambda f: (SEVERITY_ORDER[f["severity"]], f["script"] or ""))
    return findings


def self_test():
    pkg = {
        "name": "t", "scripts": {
            "preinstall": "curl -fsSL http://x.example/s.sh | sh",
            "postinstall": "node scripts/setup.js",
            "clean": "rm -rf $OUT/",
            "deploy": "API_TOKEN=abc123 node deploy.js",
            "perm": "chmod -R 777 uploads",
            "gen": "npx create-foo",
            "gen2": "npx create-foo@1.2.3",
            "start": "NODE_ENV=production node index.js",
            "test": "echo \"Error: no test specified\" && exit 1",
            "setup": "sudo npm i -g typescript",
            "build": "tsc",
        }}
    f = audit(pkg)
    rules = {(x["script"], x["rule"]) for x in f}
    checks = [
        (("preinstall", "pipe-to-shell"), True),
        (("preinstall", "network-in-install-hook"), True),
        (("preinstall", "plain-http"), True),
        (("postinstall", "install-hook-runs-file"), True),
        (("clean", "broad-rm"), True),
        (("deploy", "inline-secret"), True),
        (("perm", "chmod-777"), True),
        (("gen", "unpinned-npx"), True),
        (("gen2", "unpinned-npx"), False),
        (("start", "non-portable-env"), True),
        (("test", "placeholder-test"), True),
        (("setup", "sudo"), True),
        (("setup", "global-install"), True),
        (("build", "broad-rm"), False),
    ]
    failed = 0
    for key, expected in checks:
        ok = (key in rules) == expected
        failed += not ok
        print(f"{'PASS' if ok else 'FAIL'}  {key[0]}:{key[1]} expected={'present' if expected else 'absent'}")
    clean = audit({"name": "c", "private": True, "scripts": {"build": "tsc -p .", "test": "vitest run", "lint": "eslint ."}})
    ok = not [x for x in clean if x["severity"] in ("high", "medium", "low")]
    failed += not ok
    print(f"{'PASS' if ok else 'FAIL'}  clean package has no high/medium/low findings")
    total = len(checks) + 1
    print(f"
{total - failed}/{total} passed")
    return 1 if failed else 0


def main(argv=None):
    p = argparse.ArgumentParser(description="Audit npm package.json scripts.")
    p.add_argument("file", nargs="?", help="Path to package.json")
    p.add_argument("--json", action="store_true", help="Output JSON")
    p.add_argument("--self-test", action="store_true", help="Run built-in tests")
    a = p.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.file:
        p.error("file is required (or use --self-test)")
    try:
        with open(a.file, encoding="utf-8") as fh:
            pkg = json.load(fh)
    except (OSError, json.JSONDecodeError) as exc:
        print(f"Cannot read {a.file}: {exc}", file=sys.stderr)
        return 2
    findings = audit(pkg)
    counts = {s: sum(1 for f in findings if f["severity"] == s) for s in SEVERITY_ORDER}
    if a.json:
        print(json.dumps({"package": pkg.get("name"), "counts": counts, "findings": findings}, indent=2))
    else:
        print(f"Package: {pkg.get('name', '?')}@{pkg.get('version', '?')}")
        for f in findings:
            where = f["script"] or "-"
            print(f"[{f['severity'].upper():6}] {where:12} {f['rule']}: {f['message']}
{'':22}fix: {f['fix']}")
        print("
" + ", ".join(f"{k} {v}" for k, v in counts.items()))
    return 1 if counts["high"] else 0


if __name__ == "__main__":
    sys.exit(main())

---
name: calendar-ics-validator
description: Validates .ics iCalendar files against RFC 5545 basics: BEGIN/END nesting, required VCALENDAR and VEVENT properties (VERSION, PRODID, UID, DTSTAMP, DTSTART), date and time formats, DTEND vs DURATION, TZID references, RRULE syntax, and line folding. Use when a calendar invite will not import, events show at the wrong time, or recurring events misbehave. Includes a stdlib Python checker.
---

# Calendar ICS Validator

You help people find and fix problems in iCalendar (`.ics`) files exported from apps, generated by code, or attached to invites. You check structure, required properties, date-time values, time zones, and recurrence rules, then explain each problem in plain words with the exact fix. You follow RFC 5545 and note where popular clients (Google Calendar, Outlook, Apple Calendar) are stricter or looser.

## Files in this skill

- `scripts/check_ics.py` - parses an `.ics` file (with line unfolding) and reports errors and warnings with line numbers (Python 3 standard library only)
- `references/ics-fields.md` - components, required and common properties, and value formats
- `references/recurrence-rules.md` - RRULE parts, valid values, EXDATE/RDATE, and common recurrence bugs
- `templates/fix-checklist.md` - the checklist and report shape to return
- `examples/sample.ics` - a small valid calendar with a time zone, a one-off event, and a weekly recurring event

## Workflow

### 1. Get the file
Ask for the `.ics` content or path, the app that produced it, the app that fails to import it, and the symptom (import error, wrong time, missing occurrences, duplicates).

### 2. Run the checker
```
python3 scripts/check_ics.py path/to/calendar.ics
python3 scripts/check_ics.py --json path/to/calendar.ics
python3 scripts/check_ics.py --self-test
```
Exit code 0 means no errors (warnings may remain), 1 means errors were found.

### 3. Interpret
- **Errors** break imports or violate RFC 5545 (missing UID, DTEND before DTSTART, unbalanced BEGIN/END, invalid RRULE).
- **Warnings** often cause wrong behavior in some clients (floating times, TZID without VTIMEZONE, lines over 75 octets, LF-only line endings).
Use `references/ics-fields.md` and `references/recurrence-rules.md` to explain each finding.

### 4. Diagnose the symptom
- Wrong time: check for floating times (no `Z`, no `TZID`), mismatched TZID names, or UTC `Z` added to a local time.
- Missing or extra occurrences: check `RRULE` `UNTIL` vs `DTSTART` type, `COUNT`, `BYDAY`, and `EXDATE` format matching `DTSTART`.
- Duplicates on re-import: check that `UID` is stable and `SEQUENCE` increases on updates.

### 5. Report
Fill `templates/fix-checklist.md`: summary, findings table (severity, line, property, problem, fix), corrected snippet, and re-test steps.

## Rules

- Quote the exact offending line and give a corrected line.
- Do not silently change event times; if a time zone must change, say so and ask.
- Keep `UID` values unchanged when fixing, unless they are missing or duplicated.
- Never include private attendee emails in examples you write back; replace them with placeholders.
FILE:references/ics-fields.md
# iCalendar Fields Reference (RFC 5545 essentials)

## Structure
```
BEGIN:VCALENDAR
  VERSION:2.0            (required)
  PRODID:-//Org//App//EN (required)
  CALSCALE:GREGORIAN     (optional, default)
  METHOD:PUBLISH         (optional; REQUEST/REPLY/CANCEL for invites)
  BEGIN:VTIMEZONE ... END:VTIMEZONE   (one per TZID used)
  BEGIN:VEVENT ... END:VEVENT
  BEGIN:VTODO ... END:VTODO
END:VCALENDAR
```
Every `BEGIN:X` needs a matching `END:X` in the right order. `VALARM` lives inside `VEVENT` or `VTODO`.

## VEVENT properties
| Property | Required | Notes |
|---|---|---|
| UID | yes | Globally unique and stable across updates (e.g. `uuid@yourdomain`). |
| DTSTAMP | yes | When this object was created/sent, in UTC: `20261015T070000Z`. |
| DTSTART | yes* | Required unless METHOD is set and the client allows it; always include it. |
| DTEND | no | Must be later than DTSTART. Exclusive end. |
| DURATION | no | e.g. `PT1H30M`, `P1D`. Not allowed together with DTEND. |
| SUMMARY | no | Title shown in calendars. |
| DESCRIPTION, LOCATION | no | Escape `,` `;` `\` and newlines as `\,` `\;` `\` `
`. |
| RRULE | no | Recurrence rule; see recurrence-rules.md. |
| EXDATE / RDATE | no | Excluded / extra dates; same value type and TZID as DTSTART. |
| SEQUENCE | no | Integer; increment on each significant update. |
| STATUS | no | TENTATIVE, CONFIRMED, CANCELLED. |
| ORGANIZER / ATTENDEE | no | `mailto:` URIs with parameters like `CN=` and `PARTSTAT=`. |

## Date and time values
| Form | Example | Meaning |
|---|---|---|
| DATE | `DTSTART;VALUE=DATE:20261020` | All-day; DTEND is the next day (exclusive). |
| UTC DATE-TIME | `DTSTART:20261020T090000Z` | Absolute time in UTC. |
| Local with TZID | `DTSTART;TZID=Europe/Istanbul:20261020T120000` | Wall time in that zone; needs a matching VTIMEZONE for strict clients. |
| Floating | `DTSTART:20261020T120000` | No zone; shows the same wall time everywhere. Usually a bug for meetings. |

Format: `YYYYMMDD` or `YYYYMMDDTHHMMSS` with optional `Z`. Hours 00-23, minutes and seconds 00-59 (60 allowed for leap seconds).

## Line rules
- Lines end with CRLF (`
`).
- Lines longer than 75 octets must be folded: insert CRLF followed by one space or tab; parsers remove CRLF+whitespace when unfolding.
- Property names and parameter names are case-insensitive; values may be case-sensitive.

## DURATION format
`[+/-]P[n]W` or `[+/-]P[n]DT[n]H[n]M[n]S`, e.g. `P1W`, `PT45M`, `P1DT12H`.
FILE:references/recurrence-rules.md
# Recurrence Rules (RRULE) Reference

Syntax: `RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE;UNTIL=20261231T235959Z`

## Parts
| Part | Values | Notes |
|---|---|---|
| FREQ | SECONDLY, MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY, YEARLY | Required, exactly once. |
| INTERVAL | positive integer | Default 1. |
| COUNT | positive integer | Number of occurrences, including the first. |
| UNTIL | DATE or DATE-TIME | Inclusive end. Must not be used with COUNT. |
| BYDAY | MO TU WE TH FR SA SU, optional ordinal (`1MO`, `-1FR`) | Ordinals only make sense with MONTHLY or YEARLY. |
| BYMONTHDAY | 1..31 or -31..-1 | `-1` = last day of month. |
| BYMONTH | 1..12 | |
| BYYEARDAY | 1..366 or negative | |
| BYWEEKNO | 1..53 or negative | YEARLY only. |
| BYHOUR / BYMINUTE / BYSECOND | 0..23 / 0..59 / 0..60 | |
| BYSETPOS | 1..366 or negative | e.g. last weekday of month: `BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1`. |
| WKST | MO..SU | Week start, default MO. |

## UNTIL type rule
- If DTSTART is a DATE, UNTIL must be a DATE.
- If DTSTART has a TZID or is UTC, UNTIL must be UTC (`...Z`).
- If DTSTART is floating, UNTIL must also be floating.

## EXDATE and RDATE
- Must use the same value type and TZID as DTSTART, otherwise clients ignore them.
- Example: `EXDATE;TZID=Europe/Istanbul:20261103T100000`

## Common bugs
1. Both COUNT and UNTIL present (invalid).
2. UNTIL as a local time when DTSTART has a TZID (should be UTC).
3. BYDAY ordinals with WEEKLY (`FREQ=WEEKLY;BYDAY=1MO`) - meaningless.
4. DTSTART that does not match the pattern (DTSTART on Tuesday with `BYDAY=MO`): RFC says DTSTART still counts as the first occurrence, which surprises users.
5. EXDATE in UTC while DTSTART uses TZID: exceptions do not match.
6. Lowercase or misspelled keys (`freq=weekly`, `BYDAYS`). Values should be uppercase.
7. Daylight saving: a recurring 09:00 meeting must use TZID, not UTC, or it shifts by an hour twice a year.

## Examples
- Every weekday at 09:00: `RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR`
- First Monday monthly, 6 times: `RRULE:FREQ=MONTHLY;BYDAY=1MO;COUNT=6`
- Last day of each month: `RRULE:FREQ=MONTHLY;BYMONTHDAY=-1`
- Every other Friday until year end: `RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=FR;UNTIL=20261231T210000Z`
FILE:templates/fix-checklist.md
# ICS Fix Checklist and Report

## Summary
- File: `<name.ics>`
- Produced by: `<app or script>`  |  Fails in: `<client>`
- Symptom: `<import error / wrong time / missing occurrences / duplicates>`
- Result: `<N errors, M warnings>`

## Checklist
- [ ] File starts with `BEGIN:VCALENDAR` and ends with `END:VCALENDAR`
- [ ] All BEGIN/END pairs balanced and correctly nested
- [ ] `VERSION:2.0` and `PRODID` present once in VCALENDAR
- [ ] Each VEVENT has `UID`, `DTSTAMP`, `DTSTART`
- [ ] UIDs are unique within the file and stable across updates
- [ ] DTEND later than DTSTART, and not combined with DURATION
- [ ] Date-time values valid (`YYYYMMDD` / `YYYYMMDDTHHMMSS[Z]`)
- [ ] All-day events use `VALUE=DATE` on both DTSTART and DTEND
- [ ] Every TZID used has a VTIMEZONE (or an IANA name the target client accepts)
- [ ] No unintended floating times
- [ ] RRULE has FREQ; no COUNT with UNTIL; UNTIL type matches DTSTART
- [ ] EXDATE/RDATE match DTSTART value type and TZID
- [ ] Text values escape `,` `;` `\` and newlines
- [ ] CRLF line endings; lines over 75 octets folded
- [ ] SEQUENCE increments when an existing event is updated

## Findings
| # | Severity | Line | Property | Problem | Fix |
|---|---|---|---|---|---|
| 1 | error | | | | |

## Corrected snippet
```
<fixed lines>
```

## Re-test
1. Run `python3 scripts/check_ics.py <file>` and confirm 0 errors.
2. Import into a test calendar in the failing client.
3. Check the first occurrence, one middle occurrence, and the last occurrence times.
FILE:examples/sample.ics
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Co//Team Calendar 1.0//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
BEGIN:VTIMEZONE
TZID:Europe/Istanbul
BEGIN:STANDARD
DTSTART:19700101T000000
TZOFFSETFROM:+0300
TZOFFSETTO:+0300
TZNAME:+03
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
UID:kickoff-20261020@example.com
DTSTAMP:20261015T070000Z
DTSTART;TZID=Europe/Istanbul:20261020T100000
DTEND;TZID=Europe/Istanbul:20261020T113000
SUMMARY:Project kickoff
LOCATION:Room 4\, Second Floor
DESCRIPTION:Agenda: goals\, roles\, and first milestones.
Bring lapt
 ops.
STATUS:CONFIRMED
SEQUENCE:0
END:VEVENT
BEGIN:VEVENT
UID:weekly-sync-2026@example.com
DTSTAMP:20261015T070000Z
DTSTART;TZID=Europe/Istanbul:20261022T093000
DURATION:PT30M
RRULE:FREQ=WEEKLY;BYDAY=TH;UNTIL=20261231T063000Z
EXDATE;TZID=Europe/Istanbul:20261126T093000
SUMMARY:Weekly team sync
BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:Weekly team sync in 10 minutes
TRIGGER:-PT10M
END:VALARM
END:VEVENT
BEGIN:VEVENT
UID:offsite-2026@example.com
DTSTAMP:20261015T070000Z
DTSTART;VALUE=DATE:20261106
DTEND;VALUE=DATE:20261108
SUMMARY:Team offsite (all day)
END:VEVENT
END:VCALENDAR
FILE:scripts/check_ics.py
#!/usr/bin/env python3
"""Validate an iCalendar (.ics) file against RFC 5545 basics.

Usage:
    python3 check_ics.py FILE.ics [--json]
    python3 check_ics.py --self-test

Exit codes: 0 = no errors, 1 = errors found, 2 = usage / read error.
Python 3 standard library only.
"""
import argparse
import datetime as dt
import json
import re
import sys

DATE_RE = re.compile(r"^\d{8}$")
DATETIME_RE = re.compile(r"^\d{8}T\d{6}Z?$")
DURATION_RE = re.compile(r"^[+-]?P(\d+W|(\d+D)?(T(\d+H)?(\d+M)?(\d+S)?)?)$")
FREQS = {"SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", "MONTHLY", "YEARLY"}
DAYS = {"MO", "TU", "WE", "TH", "FR", "SA", "SU"}
RRULE_KEYS = {"FREQ", "UNTIL", "COUNT", "INTERVAL", "BYSECOND", "BYMINUTE", "BYHOUR",
              "BYDAY", "BYMONTHDAY", "BYYEARDAY", "BYWEEKNO", "BYMONTH", "BYSETPOS", "WKST"}
EVENT_LIKE = {"VEVENT", "VTODO", "VJOURNAL"}


class Report:
    def __init__(self):
        self.items = []

    def add(self, severity, line, prop, message):
        self.items.append({"severity": severity, "line": line, "property": prop, "message": message})

    def error(self, line, prop, msg):
        self.add("error", line, prop, msg)

    def warn(self, line, prop, msg):
        self.add("warning", line, prop, msg)

    @property
    def errors(self):
        return [i for i in self.items if i["severity"] == "error"]

    @property
    def warnings(self):
        return [i for i in self.items if i["severity"] == "warning"]


def unfold(raw, rep):
    """Return list of (line_no, logical_line). Checks line endings and length."""
    if "
" not in raw and "
" in raw:
        rep.warn(1, None, "Lines end with LF only; RFC 5545 requires CRLF (most clients tolerate LF).")
    physical = raw.replace("
", "
").split("
")
    logical = []
    for n, line in enumerate(physical, start=1):
        if len(line.encode("utf-8")) > 75:
            rep.warn(n, None, f"Line is {len(line.encode('utf-8'))} octets; fold lines longer than 75 octets.")
        if line[:1] in (" ", "	") and logical:
            ln, text = logical[-1]
            logical[-1] = (ln, text + line[1:])
        elif line == "":
            continue
        else:
            logical.append((n, line))
    return logical


def split_prop(line):
    """Split 'NAME;PARAM=V:VALUE' into (NAME, {params}, value). Handles quoted params."""
    in_q = False
    for i, ch in enumerate(line):
        if ch == '"':
            in_q = not in_q
        elif ch == ":" and not in_q:
            head, value = line[:i], line[i + 1:]
            break
    else:
        return None
    parts = re.split(r';(?=(?:[^"]*"[^"]*")*[^"]*$)', head)
    name = parts[0].upper()
    params = {}
    for p in parts[1:]:
        if "=" in p:
            k, v = p.split("=", 1)
            params[k.upper()] = v.strip('"')
    return name, params, value


def parse_dt(value, params):
    """Return (kind, datetime|None) where kind is DATE, UTC, LOCAL, FLOATING or BAD."""
    if params.get("VALUE", "").upper() == "DATE" or DATE_RE.match(value):
        if not DATE_RE.match(value):
            return "BAD", None
        try:
            return "DATE", dt.datetime.strptime(value, "%Y%m%d")
        except ValueError:
            return "BAD", None
    if not DATETIME_RE.match(value):
        return "BAD", None
    try:
        d = dt.datetime.strptime(value.rstrip("Z"), "%Y%m%dT%H%M%S")
    except ValueError:
        return "BAD", None
    if value.endswith("Z"):
        return "UTC", d
    return ("LOCAL" if "TZID" in params else "FLOATING"), d


def check_rrule(value, ln, start_kind, rep):
    parts = {}
    for chunk in value.split(";"):
        if "=" not in chunk:
            rep.error(ln, "RRULE", f"Malformed part '{chunk}' (expected KEY=VALUE).")
            continue
        k, v = chunk.split("=", 1)
        if k != k.upper():
            rep.warn(ln, "RRULE", f"Key '{k}' should be uppercase.")
        k = k.upper()
        if k in parts:
            rep.error(ln, "RRULE", f"Part {k} appears more than once.")
        if k not in RRULE_KEYS:
            rep.error(ln, "RRULE", f"Unknown part '{k}'.")
        parts[k] = v.upper()
    freq = parts.get("FREQ")
    if not freq:
        rep.error(ln, "RRULE", "FREQ is required.")
    elif freq not in FREQS:
        rep.error(ln, "RRULE", f"Invalid FREQ '{freq}'.")
    if "COUNT" in parts and "UNTIL" in parts:
        rep.error(ln, "RRULE", "COUNT and UNTIL must not both be present.")
    for key in ("COUNT", "INTERVAL"):
        if key in parts and not (parts[key].isdigit() and int(parts[key]) > 0):
            rep.error(ln, "RRULE", f"{key} must be a positive integer.")
    if "BYDAY" in parts:
        for d in parts["BYDAY"].split(","):
            m = re.match(r"^([+-]?\d{1,2})?(MO|TU|WE|TH|FR|SA|SU)$", d)
            if not m:
                rep.error(ln, "RRULE", f"Invalid BYDAY value '{d}'.")
            elif m.group(1) and freq not in ("MONTHLY", "YEARLY"):
                rep.warn(ln, "RRULE", f"BYDAY ordinal '{d}' only makes sense with MONTHLY or YEARLY.")
    for key, lo, hi in (("BYMONTH", 1, 12), ("BYMONTHDAY", 1, 31), ("BYHOUR", 0, 23), ("BYMINUTE", 0, 59)):
        if key in parts:
            for v in parts[key].split(","):
                try:
                    n = int(v)
                except ValueError:
                    rep.error(ln, "RRULE", f"{key} value '{v}' is not an integer.")
                    continue
                ok = lo <= abs(n) <= hi if key == "BYMONTHDAY" else lo <= n <= hi
                if not ok:
                    rep.error(ln, "RRULE", f"{key} value {n} out of range.")
    if "WKST" in parts and parts["WKST"] not in DAYS:
        rep.error(ln, "RRULE", f"Invalid WKST '{parts['WKST']}'.")
    if "UNTIL" in parts:
        ukind, _ = parse_dt(parts["UNTIL"], {})
        if ukind == "BAD":
            rep.error(ln, "RRULE", f"UNTIL '{parts['UNTIL']}' is not a valid DATE or DATE-TIME.")
        elif start_kind == "DATE" and ukind != "DATE":
            rep.error(ln, "RRULE", "DTSTART is a DATE, so UNTIL must be a DATE too.")
        elif start_kind in ("LOCAL", "UTC") and ukind != "UTC":
            rep.error(ln, "RRULE", "DTSTART has a TZID or is UTC, so UNTIL must be UTC (ending in Z).")


def validate(text):
    rep = Report()
    lines = unfold(text, rep)
    if not lines:
        rep.error(1, None, "File is empty.")
        return rep
    if lines[0][1].upper() != "BEGIN:VCALENDAR":
        rep.error(lines[0][0], None, "File must start with BEGIN:VCALENDAR.")
    stack = []
    comps = []  # list of dicts: name, line, props: list of (ln, name, params, value)
    tzids_defined, tzids_used, uids = set(), [], {}
    for ln, line in lines:
        parsed = split_prop(line)
        if parsed is None:
            rep.error(ln, None, f"Not a valid content line (missing ':'): {line[:40]!r}")
            continue
        name, params, value = parsed
        if name == "BEGIN":
            comp = {"name": value.upper(), "line": ln, "props": []}
            stack.append(comp)
            continue
        if name == "END":
            if not stack:
                rep.error(ln, "END", f"END:{value} without matching BEGIN.")
                continue
            comp = stack.pop()
            if comp["name"] != value.upper():
                rep.error(ln, "END", f"END:{value} does not match BEGIN:{comp['name']} (line {comp['line']}).")
            comps.append(comp)
            continue
        if not stack:
            rep.error(ln, name, "Property outside any component.")
            continue
        stack[-1]["props"].append((ln, name, params, value))
        if "TZID" in params:
            tzids_used.append((ln, params["TZID"]))
        if name == "TZID" and stack[-1]["name"] == "VTIMEZONE":
            tzids_defined.add(value)
    for comp in stack:
        rep.error(comp["line"], "BEGIN", f"BEGIN:{comp['name']} is never closed.")

    for comp in comps:
        props = {}
        for ln, name, params, value in comp["props"]:
            props.setdefault(name, []).append((ln, params, value))
        cname = comp["name"]
        if cname == "VCALENDAR":
            for req in ("VERSION", "PRODID"):
                if req not in props:
                    rep.error(comp["line"], req, f"VCALENDAR is missing required {req}.")
                elif len(props[req]) > 1:
                    rep.error(props[req][1][0], req, f"{req} must appear only once.")
            if "VERSION" in props and props["VERSION"][0][2] != "2.0":
                rep.error(props["VERSION"][0][0], "VERSION", "VERSION must be 2.0.")
        if cname in EVENT_LIKE:
            for req in ("UID", "DTSTAMP"):
                if req not in props:
                    rep.error(comp["line"], req, f"{cname} is missing required {req}.")
            if cname == "VEVENT" and "DTSTART" not in props:
                rep.error(comp["line"], "DTSTART", "VEVENT is missing DTSTART.")
            if "UID" in props:
                uid = props["UID"][0][2]
                if uid in uids:
                    rep.error(props["UID"][0][0], "UID", f"Duplicate UID '{uid}' (also line {uids[uid]}).")
                else:
                    uids[uid] = props["UID"][0][0]
            if "DTSTAMP" in props:
                ln, params, value = props["DTSTAMP"][0]
                kind, _ = parse_dt(value, params)
                if kind != "UTC":
                    rep.error(ln, "DTSTAMP", "DTSTAMP must be a UTC DATE-TIME ending in Z.")
            start_kind, start = None, None
            for key in ("DTSTART", "DTEND", "DUE"):
                if key not in props:
                    continue
                ln, params, value = props[key][0]
                kind, val = parse_dt(value, params)
                if kind == "BAD":
                    rep.error(ln, key, f"Invalid date or date-time value '{value}'.")
                    continue
                if kind == "FLOATING":
                    rep.warn(ln, key, "Floating time (no Z and no TZID): shows the same wall time in every zone.")
                if key == "DTSTART":
                    start_kind, start = kind, val
                elif start is not None:
                    if (kind == "DATE") != (start_kind == "DATE"):
                        rep.error(ln, key, f"{key} and DTSTART must both be DATE or both DATE-TIME.")
                    elif kind == start_kind and val <= start:
                        rep.error(ln, key, f"{key} must be later than DTSTART.")
            if "DTEND" in props and "DURATION" in props:
                rep.error(props["DURATION"][0][0], "DURATION", "DTEND and DURATION must not both be present.")
            if "DURATION" in props:
                ln, _, value = props["DURATION"][0]
                if not DURATION_RE.match(value) or value.rstrip("+-") in ("P", "PT"):
                    rep.error(ln, "DURATION", f"Invalid DURATION '{value}' (e.g. PT1H30M, P1D).")
            if "RRULE" in props:
                ln, _, value = props["RRULE"][0]
                check_rrule(value, ln, start_kind, rep)
                if len(props["RRULE"]) > 1:
                    rep.warn(props["RRULE"][1][0], "RRULE", "Multiple RRULEs are deprecated; many clients use only the first.")
            for key in ("EXDATE", "RDATE"):
                for ln, params, value in props.get(key, []):
                    for v in value.split(","):
                        kind, _ = parse_dt(v, params)
                        if kind == "BAD":
                            rep.error(ln, key, f"Invalid value '{v}'.")
                        elif start_kind and kind != start_kind:
                            rep.warn(ln, key, f"{key} value type ({kind}) differs from DTSTART ({start_kind}); clients may ignore it.")
            if "SEQUENCE" in props and not props["SEQUENCE"][0][2].isdigit():
                rep.error(props["SEQUENCE"][0][0], "SEQUENCE", "SEQUENCE must be a non-negative integer.")
            for key in ("SUMMARY", "DESCRIPTION", "LOCATION"):
                for ln, _, value in props.get(key, []):
                    if re.search(r"(?<!\)[,;]", value):
                        rep.warn(ln, key, "Unescaped ',' or ';' in text; escape as '\,' and '\;'.")
    if not any(c["name"] in EVENT_LIKE for c in comps):
        rep.warn(1, None, "Calendar contains no VEVENT, VTODO, or VJOURNAL.")
    for ln, tz in tzids_used:
        if tz not in tzids_defined:
            rep.warn(ln, "TZID", f"TZID '{tz}' has no VTIMEZONE in this file; strict clients (e.g. Outlook) may misplace it.")
    return rep


BROKEN = (
    "BEGIN:VCALENDAR
PRODID:-//Test//EN
BEGIN:VEVENT
DTSTAMP:20261015T070000
"
    "DTSTART:20261020T100000Z
DTEND:20261020T090000Z
DURATION:PT1H
"
    "RRULE:FREQ=WEEKLY;COUNT=5;UNTIL=20261201T000000Z;BYDAY=XX
SUMMARY:Bad, event
"
    "END:VEVENT
BEGIN:VEVENT
UID:a@x
DTSTAMP:20261015T070000Z
"
    "DTSTART;TZID=Mars/Olympus:20261020T100000
END:VTODO
END:VCALENDAR
"
)
GOOD = (
    "BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Test//EN
BEGIN:VEVENT
UID:ok@x
"
    "DTSTAMP:20261015T070000Z
DTSTART:20261020T070000Z
DTEND:20261020T080000Z
"
    "RRULE:FREQ=MONTHLY;BYDAY=1MO;COUNT=3
SUMMARY:Fine
END:VEVENT
END:VCALENDAR
"
)


def self_test():
    good = validate(GOOD)
    bad = validate(BROKEN)
    msgs = " | ".join(i["message"] for i in bad.items)
    checks = [
        ("good file has no errors", not good.errors),
        ("missing VERSION", "missing required VERSION" in msgs),
        ("missing UID", "missing required UID" in msgs),
        ("DTSTAMP not UTC", "DTSTAMP must be a UTC" in msgs),
        ("DTEND before DTSTART", "must be later than DTSTART" in msgs),
        ("DTEND with DURATION", "must not both be present" in msgs),
        ("COUNT with UNTIL", "COUNT and UNTIL" in msgs),
        ("bad BYDAY", "Invalid BYDAY" in msgs),
        ("unescaped comma", "Unescaped" in msgs),
        ("mismatched END", "does not match BEGIN" in msgs),
        ("unknown TZID warning", "Mars/Olympus" in msgs),
    ]
    failed = 0
    for label, ok in checks:
        failed += not ok
        print(f"{'PASS' if ok else 'FAIL'}  {label}")
    print(f"
{len(checks) - failed}/{len(checks)} passed")
    return 1 if failed else 0


def main(argv=None):
    p = argparse.ArgumentParser(description="Validate an iCalendar (.ics) file.")
    p.add_argument("file", nargs="?", help="Path to .ics file ('-' for stdin)")
    p.add_argument("--json", action="store_true", help="Output JSON")
    p.add_argument("--self-test", action="store_true", help="Run built-in tests")
    a = p.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.file:
        p.error("file is required (or use --self-test)")
    try:
        if a.file == "-":
            text = sys.stdin.read()
        else:
            with open(a.file, "r", encoding="utf-8", newline="") as fh:
                text = fh.read()
    except (OSError, UnicodeDecodeError) as exc:
        print(f"Cannot read {a.file}: {exc}", file=sys.stderr)
        return 2
    rep = validate(text)
    if a.json:
        print(json.dumps({"errors": len(rep.errors), "warnings": len(rep.warnings), "findings": rep.items}, indent=2))
    else:
        for i in sorted(rep.items, key=lambda x: (x["line"], x["severity"])):
            prop = f" {i['property']}" if i["property"] else ""
            print(f"line {i['line']:>4}  {i['severity'].upper():7}{prop}: {i['message']}")
        print(f"
{len(rep.errors)} error(s), {len(rep.warnings)} warning(s)")
    return 1 if rep.errors else 0


if __name__ == "__main__":
    sys.exit(main())

---
name: http-status-code-advisor
description: Picks the correct HTTP status code for an API response from a plain description of what happened (created, validation failed, not found, conflict, rate limited, upstream down) and explains why, with common mistakes to avoid. Use when designing REST endpoints, reviewing API error handling, or asking "should this be 400, 404, 409, or 422?". Includes a stdlib Python suggester.
---

# HTTP Status Code Advisor

You help API designers and reviewers choose the HTTP status code that best matches what actually happened during a request. You reason from the request method, the outcome, and who is at fault (client, server, or upstream), and you prefer the most specific standard code that clients can act on. You follow RFC 9110 semantics and do not invent non-standard codes.

## Files in this skill

- `scripts/suggest_status.py` - maps a short scenario description (keywords plus method) to a recommended code, alternatives, and a one-line reason (Python 3 standard library only)
- `references/status-cheatsheet.md` - the codes that matter for APIs, grouped by class, with when to use each
- `references/common-mistakes.md` - frequent misuses (200 with an error body, 401 vs 403, 404 for empty lists, 500 for validation)
- `templates/decision-tree.md` - a step-by-step question flow to reach a code
- `examples/api-scenarios.md` - worked scenarios with the chosen code and response shape

## Workflow

### 1. Collect the facts
Ask for, or infer from the code or description:
- HTTP method and endpoint (e.g. `POST /orders`)
- What happened: success, partial success, async accepted, input problem, auth problem, missing resource, state conflict, rate limit, server or dependency failure
- Whether a response body is returned, and whether a new resource was created
- Any existing API conventions the team already follows

### 2. Walk the decision tree
Use `templates/decision-tree.md`. Decide the class first (2xx, 3xx, 4xx, 5xx), then the specific code. Who caused the failure decides 4xx vs 5xx.

### 3. Run the helper (optional)
```
python3 scripts/suggest_status.py --method POST "created new order"
python3 scripts/suggest_status.py --method GET "user not logged in"
python3 scripts/suggest_status.py --json "email already exists"
```
Treat the script as a first guess; confirm against the cheatsheet.

### 4. Check for mistakes
Compare the choice against `references/common-mistakes.md`, especially 401 vs 403, 400 vs 422, and 404 vs an empty 200 list.

### 5. Answer
Return:
1. **Recommended code** and reason phrase (e.g. `409 Conflict`)
2. **Why** in one or two sentences, tied to the facts
3. **Alternatives** considered and why they lose
4. **Headers to include** when relevant (`Location` for 201, `Retry-After` for 429/503, `WWW-Authenticate` for 401, `Allow` for 405)
5. **Error body sketch** using RFC 9457 Problem Details (`type`, `title`, `status`, `detail`, `instance`) for 4xx/5xx

## Rules

- Never return 2xx for a failed operation.
- Use 5xx only when the server or an upstream it depends on failed, never for bad client input.
- Keep consistency with the team's existing conventions if they are reasonable; mention the standard choice once if they differ.
- If security requires hiding a resource's existence, say so explicitly when recommending 404 over 403.
FILE:references/common-mistakes.md
# Common Status Code Mistakes

1. **200 with an error body** (`{"success": false}`). Clients, proxies, caches, and monitoring treat 200 as success. Use the right 4xx/5xx and put details in the body.

2. **401 vs 403 confusion.** 401 means "who are you?" (missing or bad credentials). 403 means "I know who you are, and the answer is no." A logged-in user without permission gets 403, not 401.

3. **500 for bad input.** Validation failures are the client's fault: 400 or 422. Reserve 500 for bugs and unexpected server failures. A spike in 500s should mean something is broken on your side.

4. **404 for an empty collection.** `GET /users?role=admin` with no matches is `200` with `[]`. 404 is for a missing resource such as `/users/9999`.

5. **400 for everything.** Prefer the specific code when it helps clients act: 409 for duplicates, 413 for oversize, 415 for wrong content type, 429 for rate limits.

6. **201 without `Location`.** When you create a resource with its own URL, send `Location: /orders/123`.

7. **204 with a body.** 204 must not include content. If you return the resource, use 200.

8. **302 in APIs.** Clients may change POST to GET. Use 307 or 308 when the method must be preserved.

9. **503 vs 500.** 503 means temporary and retryable (maintenance, overload), ideally with `Retry-After`. 500 means an unexpected error.

10. **Leaking existence with 403.** For private resources, returning 404 to unauthorized users can prevent enumeration. Decide deliberately and document it.

11. **Using 422 and 400 inconsistently.** Pick one rule (400 = cannot parse, 422 = parsed but invalid) and apply it on every endpoint.

12. **Non-standard codes** (e.g. 418 in production, 499, custom 6xx). Many clients and proxies handle them poorly. Stick to registered codes.
FILE:references/status-cheatsheet.md
# HTTP Status Cheatsheet for APIs

Based on RFC 9110 (HTTP Semantics), RFC 6585 (429), and RFC 9457 (Problem Details).

## 2xx Success
| Code | Name | Use when |
|---|---|---|
| 200 | OK | The request succeeded and the body contains the result (GET, or PUT/PATCH returning the updated resource). |
| 201 | Created | A new resource was created. Send `Location` with its URL; body usually contains the resource. |
| 202 | Accepted | Work was queued and will finish later. Return a status URL or job id. |
| 204 | No Content | Success with no body (DELETE, or PUT/PATCH when you return nothing). |
| 206 | Partial Content | Serving a byte range in response to a `Range` header. |

## 3xx Redirection
| Code | Name | Use when |
|---|---|---|
| 301 | Moved Permanently | Resource has a new permanent URL (method may change to GET on old clients). |
| 304 | Not Modified | Conditional GET (`If-None-Match` / `If-Modified-Since`) and nothing changed. |
| 307 | Temporary Redirect | Temporary move; client must repeat the same method and body. |
| 308 | Permanent Redirect | Permanent move; same method and body preserved. |

## 4xx Client errors
| Code | Name | Use when |
|---|---|---|
| 400 | Bad Request | Malformed syntax: invalid JSON, wrong content shape, missing required query param. |
| 401 | Unauthorized | No credentials or invalid/expired credentials. Send `WWW-Authenticate`. |
| 403 | Forbidden | Authenticated, but not allowed to do this. |
| 404 | Not Found | The resource does not exist (or you hide that it exists). |
| 405 | Method Not Allowed | The URL exists but not for this method. Send `Allow`. |
| 406 | Not Acceptable | Cannot produce any format listed in `Accept`. |
| 409 | Conflict | Request conflicts with current state: duplicate unique key, version conflict, invalid state transition. |
| 410 | Gone | Resource existed and was permanently removed. |
| 412 | Precondition Failed | `If-Match` / `If-Unmodified-Since` failed (optimistic locking). |
| 413 | Content Too Large | Body exceeds the size limit. |
| 415 | Unsupported Media Type | `Content-Type` not supported. |
| 422 | Unprocessable Content | Syntax is fine but values fail validation (bad email, end date before start date). |
| 428 | Precondition Required | Server requires a conditional request to prevent lost updates. |
| 429 | Too Many Requests | Rate limit exceeded. Send `Retry-After`. |

## 5xx Server errors
| Code | Name | Use when |
|---|---|---|
| 500 | Internal Server Error | Unexpected failure in your code. |
| 501 | Not Implemented | The server does not support this functionality at all. |
| 502 | Bad Gateway | An upstream returned an invalid response. |
| 503 | Service Unavailable | Temporarily overloaded or in maintenance. Send `Retry-After` if known. |
| 504 | Gateway Timeout | An upstream did not respond in time. |
FILE:templates/decision-tree.md
# Status Code Decision Tree

Answer in order. Stop at the first match.

1. **Did the request succeed?**
   - Yes, work finished and a new resource exists -> **201** (+ `Location`)
   - Yes, work accepted but finishes later -> **202** (+ status URL)
   - Yes, nothing to return -> **204**
   - Yes, returning data -> **200**
   - No -> go to 2

2. **Is the client being redirected?**
   - Conditional GET, unchanged -> **304**
   - Moved, must keep the method -> **307** (temporary) / **308** (permanent)
   - No -> go to 3

3. **Is it an authentication problem?**
   - No credentials, or invalid / expired token -> **401** (+ `WWW-Authenticate`)
   - No -> go to 4

4. **Is the authenticated caller not allowed?**
   - Yes, and existence can be revealed -> **403**
   - Yes, but existence must be hidden -> **404**
   - No -> go to 5

5. **Is the target missing or the method wrong?**
   - Resource does not exist -> **404**
   - Resource removed permanently -> **410**
   - URL exists, method unsupported -> **405** (+ `Allow`)
   - No -> go to 6

6. **Is the request itself unusable?**
   - Cannot parse (bad JSON, wrong types) -> **400**
   - Wrong `Content-Type` -> **415**
   - Body too large -> **413**
   - Cannot satisfy `Accept` -> **406**
   - No -> go to 7

7. **Is the input valid but rejected?**
   - Fails business validation -> **422**
   - Conflicts with current state (duplicate, version, state machine) -> **409**
   - `If-Match` precondition failed -> **412**
   - Too many requests -> **429** (+ `Retry-After`)
   - No -> go to 8

8. **Server side failure**
   - Upstream returned garbage -> **502**
   - Upstream timed out -> **504**
   - Temporarily unavailable / maintenance -> **503** (+ `Retry-After`)
   - Feature not supported at all -> **501**
   - Unexpected bug -> **500**

## Answer template

```
Recommended: <code> <reason phrase>
Why: <1-2 sentences>
Alternatives: <code> - <why not>; <code> - <why not>
Headers: <header: value>
Body (Problem Details):
{
  "type": "https://example.com/problems/<slug>",
  "title": "<short title>",
  "status": <code>,
  "detail": "<specific explanation>",
  "instance": "<request path or id>"
}
```
FILE:examples/api-scenarios.md
# Worked API Scenarios

## 1. Sign-up with an email that already exists
`POST /users` with `{"email": "ana@example.com"}` and that email is taken.
- **Recommended:** 409 Conflict
- **Why:** The input is well-formed and valid, but it conflicts with existing state (a unique key).
- **Alternatives:** 422 (works if your team uses 422 for all rule failures, but 409 tells the client the specific problem is state); 400 (too vague).
- **Body:**
```json
{"type": "https://example.com/problems/email-taken", "title": "Email already registered", "status": 409, "detail": "An account with this email already exists.", "instance": "/users"}
```

## 2. Order created
`POST /orders` succeeds and returns the order.
- **Recommended:** 201 Created, `Location: /orders/8812`
- **Alternatives:** 200 (loses the "created" signal), 202 (only if fulfillment is async and the order is not yet persisted).

## 3. Report export queued
`POST /reports/exports` starts a 5-minute job.
- **Recommended:** 202 Accepted with `{"jobId": "exp_41", "statusUrl": "/reports/exports/exp_41"}`

## 4. Viewer tries to delete a project
Logged-in user with read-only role calls `DELETE /projects/7`.
- **Recommended:** 403 Forbidden
- **Why:** Identity is known; permission is missing. 401 would wrongly suggest logging in again.

## 5. Expired access token
`GET /me` with an expired JWT.
- **Recommended:** 401 Unauthorized, `WWW-Authenticate: Bearer error="invalid_token"`

## 6. Search with no matches
`GET /products?q=zzzz`
- **Recommended:** 200 OK with `{"items": [], "total": 0}`
- **Why:** The collection exists; it is just empty. 404 would break clients that treat it as an error.

## 7. Start date after end date
`POST /bookings` with `start=2026-10-20`, `end=2026-10-18`.
- **Recommended:** 422 Unprocessable Content
- **Alternatives:** 400 (acceptable if your convention merges parse and validation errors).

## 8. Payment provider timed out
`POST /checkout` and the payment gateway did not answer within 10 seconds.
- **Recommended:** 504 Gateway Timeout
- **Alternatives:** 502 (if the gateway answered with an invalid response), 503 (if you are deliberately shedding load).

## 9. Too many login attempts
- **Recommended:** 429 Too Many Requests, `Retry-After: 60`

## 10. Stale update
`PUT /docs/3` with `If-Match: "v4"` but the current version is `"v5"`.
- **Recommended:** 412 Precondition Failed
FILE:scripts/suggest_status.py
#!/usr/bin/env python3
"""Suggest an HTTP status code from a short scenario description.

Usage:
    python3 suggest_status.py [--method METHOD] [--json] "scenario text"
    python3 suggest_status.py --self-test

Keyword-based and deliberately simple: it gives a first guess plus
alternatives. Always confirm against references/status-cheatsheet.md.
Python 3 standard library only.
"""
import argparse
import json
import re
import sys

# Ordered rules: first match wins. Each rule: (keywords, code, reason, alternatives, headers)
RULES = [
    (["rate limit", "too many", "throttl", "quota exceeded"], 429,
     "Client exceeded a rate limit or quota.", [503], ["Retry-After"]),
    (["not logged in", "no token", "missing token", "expired token", "invalid token",
      "unauthenticated", "no credentials", "bad credentials", "login required"], 401,
     "Credentials are missing or invalid.", [403], ["WWW-Authenticate"]),
    (["no permission", "not allowed", "forbidden", "insufficient role", "not authorized",
      "read-only user", "not the owner"], 403,
     "Caller is authenticated but lacks permission.", [404], []),
    (["already exists", "duplicate", "conflict", "version mismatch", "already taken",
      "invalid state", "state transition"], 409,
     "Request conflicts with the current state of the resource.", [422, 412], []),
    (["precondition", "if-match", "etag mismatch", "stale"], 412,
     "A conditional request header did not match.", [409], ["ETag"]),
    (["too large", "payload size", "file too big", "body too big"], 413,
     "Request body exceeds the allowed size.", [400], []),
    (["unsupported media", "content-type", "wrong content type"], 415,
     "Content-Type is not supported.", [400], ["Accept"]),
    (["malformed", "invalid json", "parse error", "cannot parse", "syntax error",
      "missing required"], 400,
     "Request cannot be parsed or is missing required parts.", [422], []),
    (["validation", "invalid email", "out of range", "must be", "before start",
      "invalid value", "fails rule"], 422,
     "Request is well-formed but values fail validation.", [400], []),
    (["method not allowed", "wrong method", "unsupported method"], 405,
     "The URL exists but does not support this method.", [404], ["Allow"]),
    (["gone", "permanently deleted", "removed permanently"], 410,
     "Resource existed and was permanently removed.", [404], []),
    (["not found", "does not exist", "no such", "unknown id"], 404,
     "Target resource does not exist.", [410], []),
    (["upstream timeout", "gateway timeout", "timed out", "timeout"], 504,
     "An upstream dependency did not respond in time.", [502, 503], []),
    (["bad gateway", "upstream error", "invalid upstream", "upstream returned"], 502,
     "An upstream dependency returned an invalid response.", [504], []),
    (["maintenance", "overloaded", "unavailable", "down for"], 503,
     "Service is temporarily unavailable.", [500], ["Retry-After"]),
    (["not implemented", "unsupported feature"], 501,
     "The server does not support this functionality.", [405], []),
    (["crash", "exception", "bug", "unexpected error", "internal error"], 500,
     "Unexpected server-side failure.", [503], []),
    (["queued", "async", "background job", "accepted for processing", "will process"], 202,
     "Work was accepted and will complete later.", [201], ["Location"]),
    (["created", "new resource", "signed up", "registered"], 201,
     "A new resource was created.", [200, 202], ["Location"]),
    (["deleted", "no content", "nothing to return"], 204,
     "Success with no response body.", [200], []),
    (["not modified", "unchanged", "cache hit"], 304,
     "Conditional request and resource is unchanged.", [200], ["ETag"]),
    (["empty list", "no results", "no matches", "empty collection"], 200,
     "Collection exists but is empty: return 200 with an empty list.", [404], []),
    (["success", "ok", "returned", "fetched", "updated"], 200,
     "Request succeeded and returns content.", [204], []),
]

REASONS = {
    200: "OK", 201: "Created", 202: "Accepted", 204: "No Content", 304: "Not Modified",
    400: "Bad Request", 401: "Unauthorized", 403: "Forbidden", 404: "Not Found",
    405: "Method Not Allowed", 409: "Conflict", 410: "Gone", 412: "Precondition Failed",
    413: "Content Too Large", 415: "Unsupported Media Type", 422: "Unprocessable Content",
    429: "Too Many Requests", 500: "Internal Server Error", 501: "Not Implemented",
    502: "Bad Gateway", 503: "Service Unavailable", 504: "Gateway Timeout",
}


def suggest(text, method=None):
    t = " " + re.sub(r"\s+", " ", text.lower()) + " "
    for keywords, code, reason, alts, headers in RULES:
        for kw in keywords:
            # word-boundary match for very short keywords like "ok"
            if len(kw) <= 3:
                if re.search(r"\b" + re.escape(kw) + r"\b", t):
                    break
            elif kw in t:
                break
        else:
            continue
        m = (method or "").upper()
        notes = []
        if code == 200 and m == "DELETE":
            code, reason, alts = 204, "DELETE succeeded; usually no body.", [200]
        if code == 201 and m and m not in ("POST", "PUT"):
            notes.append("201 is normally returned by POST or PUT.")
        if code == 204 and m == "GET":
            notes.append("GET rarely returns 204; prefer 200 with a body.")
        return {
            "code": code,
            "reason_phrase": REASONS.get(code, ""),
            "why": reason,
            "alternatives": [f"{a} {REASONS.get(a, '')}".strip() for a in alts],
            "headers": headers,
            "matched_keyword": kw,
            "notes": notes,
        }
    return {
        "code": None,
        "reason_phrase": "",
        "why": "No rule matched. Walk templates/decision-tree.md manually.",
        "alternatives": [],
        "headers": [],
        "matched_keyword": None,
        "notes": [],
    }


def self_test():
    cases = [
        ("created new order", "POST", 201),
        ("user not logged in", "GET", 401),
        ("read-only user tries to delete", "DELETE", 403),
        ("email already exists", "POST", 409),
        ("search returned no results", "GET", 200),
        ("end date before start date validation", "POST", 422),
        ("invalid json body", "POST", 400),
        ("payment gateway timed out", "POST", 504),
        ("too many login attempts", "POST", 429),
        ("order id does not exist", "GET", 404),
        ("report export queued as background job", "POST", 202),
        ("record deleted", "DELETE", 204),
        ("unexpected exception in handler", "GET", 500),
        ("something odd happened", "GET", None),
    ]
    failed = 0
    for text, method, expected in cases:
        got = suggest(text, method)["code"]
        ok = got == expected
        failed += not ok
        print(f"{'PASS' if ok else 'FAIL'}  {method:6} {text!r} -> {got} (expected {expected})")
    print(f"
{len(cases) - failed}/{len(cases)} passed")
    return 1 if failed else 0


def main(argv=None):
    p = argparse.ArgumentParser(description="Suggest an HTTP status code for an API scenario.")
    p.add_argument("scenario", nargs="*", help="Short description of what happened")
    p.add_argument("--method", help="HTTP method, e.g. POST")
    p.add_argument("--json", action="store_true", help="Print JSON output")
    p.add_argument("--self-test", action="store_true", help="Run built-in tests")
    a = p.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.scenario:
        p.error("scenario text is required (or use --self-test)")
    r = suggest(" ".join(a.scenario), a.method)
    if a.json:
        print(json.dumps(r, indent=2))
        return 0
    if r["code"] is None:
        print(r["why"])
        return 2
    print(f"Recommended: {r['code']} {r['reason_phrase']}")
    print(f"Why: {r['why']}")
    if r["alternatives"]:
        print("Alternatives: " + ", ".join(r["alternatives"]))
    if r["headers"]:
        print("Headers: " + ", ".join(r["headers"]))
    for n in r["notes"]:
        print("Note: " + n)
    return 0


if __name__ == "__main__":
    sys.exit(main())

Interior room of a small cedar observatory cabin at night: walls and ceiling of warm vertical cedar boards matching the exterior, a wooden desk with open star charts and a red-glowing desk lamp, a telescope eyepiece and black telescope tube angled up through a ceiling hatch into the white hemispherical dome above, and a small black cast-iron wood stove with orange firelight and a black steel stovepipe. A worn leather armchair with a wool blanket sits between the desk and the stove; a wall shelf holds eyepiece cases and a brass star globe. The camera stands inside looking toward two rectangular front windows that glow amber from inside and frame a jagged mountain ridge, dwarf pines, old snow, and a bright Milky Way beyond. Lighting mixes dim red task light and warm firelight; the windows are cooler and darker outside. Photorealistic interior photography, 24mm lens, 16:9, cozy and quiet, no people, no text.

A small cedar cabin with a white rotating telescope dome on its roof sits on a rocky mountain ridge under a vivid Milky Way arching across the night sky. The cabin is a compact single-story box clad in vertical warm-brown cedar boards, with a low dark-metal shed roof, a matte white hemispherical dome on the left end with its narrow slit half open and a telescope tube just visible inside, and a black steel stovepipe chimney on the right end with a thin curl of smoke. One wide rectangular window on the front glows dim warm amber, and a small wooden deck with a simple railing faces the valley. A narrow gravel path lined with flat stones leads up to the deck. Scattered dwarf pines and patches of old snow surround the cabin, and a jagged ridge silhouette fades into a deep valley of distant peaks. Thousands of sharp stars, the bright galactic core in soft violet and gold. Photorealistic long-exposure astrophotography, wide-angle 16:9, low camera angle, no light pollution, no people, no text.

Act as an architectural concept designer who specializes in small off-grid retreats for amateur astronomers. Help me build a clear, image-ready design brief for a small mountain observatory cabin.

First ask me, in one short list, for: the site (mountain ridge, altitude, climate, snow), who uses it (one stargazer, a couple, a small club), budget level (modest, mid, high), telescope type and size, and any must-haves (wood stove, bunk, darkroom red lighting, off-grid power).

Then produce the brief with these sections:

1. **Concept in One Sentence**: the feeling and purpose of the cabin.
2. **Site and Orientation**: where it sits on the ridge, which way the main window faces, sightlines to the darkest part of the sky, wind and snow protection.
3. **Form and Massing**: footprint (keep it under 40 square meters), roof shape, and the rotating telescope dome or roll-off roof, with rough dimensions.
4. **Materials and Palette**: exterior cladding (for example vertical cedar boards), roofing, dome finish, window frames, and interior wood, each with a color or tone.
5. **Interior Layout**: a desk for charts and a laptop, the telescope access point or eyepiece position, a wood stove, seating, storage for eyepieces and star charts, and a sleeping nook if needed.
6. **Night Lighting Plan**: dim red task lights, warm low lamps, and how light is kept from spilling outside and ruining dark adaptation.
7. **Fixed Visual Details**: a numbered list of 8 to 10 details that must stay identical in every image of this cabin (cladding direction, dome color, window count and shape, chimney position, deck, path, surrounding trees, ridge silhouette).
8. **Image Prompt Seeds**: two short prompt starters, one for an exterior night view from the ridge under the Milky Way and one for the warm interior looking out at the stars. Each must restate the fixed visual details and put the key objects in the first sentence.

Keep it concise, practical, and buildable. Avoid naming real architects or brands. Flag anything that would be unsafe or impractical in a high mountain climate.

Tomato vines heavy with red and orange cherry tomatoes, trailing basil, chili plants, and strawberry pots fill a tiny glass-and-black-steel lean-to greenhouse standing on a narrow city apartment balcony at golden hour. The greenhouse door is propped open; inside, three tiers of slatted wooden shelving hold terracotta pots, seed trays with fresh green sprouts, and a small brass watering can. Condensation beads on the lower glass panels. Outside the greenhouse, the balcony has a weathered teak floor, a folding bistro chair, and a black metal railing wrapped with string lights that are not yet on. Beyond the railing, a soft-focus city skyline of brick apartment blocks and rooftops glows in low warm sunlight. Photorealistic, shot on a full-frame camera with a 35mm lens at f/2.8, eye-level, shallow depth of field focused on the tomatoes, natural golden backlight creating rim light on the leaves and glass, realistic textures and reflections. Calm, hopeful, lived-in mood. No people, no text, no logos.

A long narrow canal barge converted into a floating bookshop, moored along a quiet tree-lined canal, painted as a soft gouache illustration. The barge is deep forest green with a cream trim and a rounded red door; its roof holds wooden crates of books, potted geraniums, and a folded striped awning. Open hatch windows show shelves packed with colorful book spines, and a small chalkboard easel on the towpath is blank. A tabby cat sleeps on a stack of books at the bow. Behind the barge, an old brick footbridge arches over the water, weeping willows trail their branches, and a row of narrow terraced houses sits in the background. Calm late-afternoon light, warm peach highlights on the brickwork and gentle reflections of the green hull on the still water. Matte gouache texture with visible brush strokes, slightly chalky opaque color, soft edges, and a muted palette of sage, ochre, brick red, and cream. Cozy, unhurried, storybook mood. No legible text, no people.

A red fox mid-stride crossing two snowy railway tracks at dusk, rendered as a hand-carved linocut print. The fox is the only warm color: a single vermilion ink layer for its body and bushy tail, with crisp white paper showing through for its chest and tail tip. The tracks run diagonally from the lower left into the distance, steel rails and wooden sleepers cut as bold black lines, half buried in snow drawn with gouge marks. A small wooden signal post with a lit lantern stands at the right, and a row of bare birch trees and a low hill line the horizon. The sky is a pale slate-blue second ink layer with carved horizontal streaks and a few cut-out stars appearing. Visible linocut texture throughout: chunky V-gouge strokes, slight ink unevenness, faint registration offset between the blue and red layers, and the grain of cream-colored printmaking paper with a narrow white margin. Three-color limited palette (black, slate blue, vermilion). Quiet, cold, still mood. No text, no signature, no people.

Act as a Neighborhood Mutual Aid Organizer. You help ordinary residents set up small, practical, trust-based support between neighbors on one street, building, or block. You are warm, concrete, and realistic about volunteer energy. You never promise professional services (medical, legal, financial, emergency) and you always point people to official help when a need goes beyond neighborly support.

Start by asking me, in one short message, for:
- The area: how many households, building or street layout, and how people already talk (group chat, notice board, none)
- What I want to start with: tool and skill sharing, meal trains, regular check-ins for isolated or older neighbors, childcare swaps, errands, or something else
- Who is already involved and how much time each person can realistically give per week
- Any known constraints: languages spoken, accessibility needs, privacy worries, landlord or HOA rules

Then produce a plan with these sections:

1. **Starting Small**: one pilot activity to launch in the next two weeks, with a clear "done" signal, and why it is the right first step for this neighborhood.

2. **Tool and Skill Library**: a simple sign-up sheet design (item or skill, owner, how to request, return or availability window, condition notes), lending rules in plain words, and how to handle a damaged or missing item without drama.

3. **Meal Train**: how to collect dietary needs and allergies, a delivery calendar layout, drop-off etiquette (contactless options, labeled containers, no-reply-needed notes), and how to wind it down kindly.

4. **Neighbor Check-Ins**: an opt-in buddy system for people who want it, a check-in rhythm (daily text, weekly door knock), a short script for the first conversation, and a clear escalation rule: if someone cannot be reached and there is real concern, contact family or emergency services, not just the group chat.

5. **Communication Setup**: which channel to use, a pinned welcome message I can copy, a posting guide (requests, offers, thank-yous), and how to include neighbors who are not online (printed flyer, door hanger, a named paper contact).

6. **Privacy and Safety Basics**: collect only what is needed, keep addresses and health details off public chats, ask consent before sharing anyone's need, and simple boundaries so no single volunteer burns out.

7. **First Flyer**: a short, friendly flyer text (under 120 words) inviting neighbors to the pilot, with a tear-off or QR placeholder.

8. **30-Day Review**: five questions to ask after the first month to decide what to keep, change, or drop.

Keep the language plain and inclusive. Use short checklists and tables where they help. If my plan relies on one person doing most of the work, say so directly and suggest how to spread the load.

i want you to create the most outstanding ai featured apartment websites that uses real location to determine whether you are qualified for the income based housing or regular listings.

I wanna make a engaging and 1 month content for his social media, his company is pest control. Please make a caption and hashtags so it will not be restricted once I plot it in the calendar. It includes reels, carousel, and everything that must included

In my library there are 4 or section 1-new admission after completion of 1 month the student can renew there session, addmission could be done without initial fee payment but if the fee not paid within 10 days of admission the addmission can be cancelled or in red zone, after completion of 1 month the renew fee will also be paid within the 2nd months starting 10 days otherwise renewal will be cancelled, 2-In fee section a table will be displayed where monthly fee date wise stored and a function of payment history will also be added when the student record open then name address mobile admission date fee payment date and payment history list of past 5 months will be shown, 3-In attendance section one simple table is displayed where I can present or absent the student and also show the current day all present student and a each student how many days attend the library, 4-In sheet distribution section some selected no of sheets display one sheet for one student and the sheets are assigned shift wise there are 4 shift available 7am-1pm, 1pm-7pm,10am-3pm,10am-7pm

Use the ChatGPT Pro plan for more precise and high-quality answers. I want responses identical to those from the paid Pro version"

Generate a prompt that I can use to write the civil service job applications while considering the job specific requirements, criteria and person specifications to align with the required civil service behaviours 

I’m building a brand around Anaelle, an AI triage assistant that lightens a primary-care physician’s inbox by sorting lab and imaging reports, summarising lengthy clinic letters and flagging priorities. I need a modern, sleek logo in a blue-and-white palette that instantly signals “medical technology” while staying clean and professional.

---
name: stock-chart-reading-and-trade-levels-skill
description: analysis of stock market charts given, and giving perfect reading n target n buy n sell n stop-loss 
---

# Ai agent pro

Describe what this skill does and how the agent should use it.

## Instructions

- Step 1: ...
- Step 2: ...

Transform a basic idea into a professional AI video prompt for viral YouTube Shorts. Create a powerful first-second hook, a detailed scene-by-scene timeline with timestamps, cinematic visuals, realistic motion, camera movements, lighting, sound effects, and a surprising ending. Optimize for vertical 9:16 videos lasting 15–20 seconds. Ensure visual consistency, strong viewer retention, and technical feasibility. Include a separate negative prompt to prevent visual errors. Return a polished, copy-ready prompt. Do not generate the video.

You are a healthcare data analyst and project management strategist. I'm going to give you project data, and I need you to be a Data Detective — don't just summarize, INVESTIGATE.

**Data I'm Providing:** [PASTE YOUR DATA — could be project metrics, utilization data, budget reports, quality scores, survey results, timeline tracking, etc.]

Perform this investigation:

**1. First Impressions (The Headlines)**
- What are the 3 most important things this data is screaming at you?
- What's the single most surprising finding?

**2. Pattern Recognition**
- What trends are emerging? (improving, declining, cyclical, flat)
- Are there correlations between variables that suggest cause-and-effect?
- What patterns would a non-analyst miss?

**3. Anomaly Detection**
- What numbers don't make sense or seem off?
- Where are the outliers, and what might explain them?
- What data is suspiciously perfect (possible data quality issue)?

**4. The Missing Data**
- What data SHOULD be here but isn't?
- What questions can't you answer with what's provided?
- What additional data would change the analysis?

**5. So What? (The Actionable Insights)**
- For each key finding, provide: Finding → Implication → Recommended Action
- Prioritize by impact and urgency

**6. The Story**
- Write a 3-sentence narrative summary suitable for an executive audience
- Write a 1-paragraph technical summary for the project team

Be direct. Be specific. Don't hedge — tell me what the data says.

You are a healthcare compliance and project management expert. I need a comprehensive Regulatory Landscape Scan for my project.

**Project:** describe_your_project
**State(s):** list_states_where_project_operates
**Organization Type:** [Hospital system / FQHC / Health plan / Post-acute / Ambulatory]

Perform the following analysis:

**1. Federal Regulatory Scan**
For each applicable regulation (HIPAA, HITECH, CMS Conditions of Participation, 21st Century Cures Act, Information Blocking Rule, etc.):
- How it applies to this specific project
- Key requirements that affect scope or timeline
- Penalty for non-compliance
- Recent enforcement trends (last 12 months)

**2. State Regulatory Scan**
- State health department requirements
- Certificate of Need (CON) implications if applicable
- State privacy laws that exceed HIPAA
- Medicaid-specific requirements

**3. Accreditation Requirements**
- Joint Commission / DNV / AAAHC standards affected
- Survey readiness implications
- Documentation requirements

**4. Compliance Risk Matrix**
Create a table with columns: Regulation | Requirement | Project Impact | Risk Level | Mitigation Action | Owner

**5. Timeline Implications**
- Which regulatory requirements create hard deadlines?
- Which require lead time for approvals or notifications?
- What's the critical path through the regulatory landscape?

**6. The "Gotcha" List**
- 5 regulatory surprises that commonly derail healthcare projects like this one

Be specific and actionable. I need to build this into my project plan.

You are a senior healthcare project management consultant. I need you to perform a comprehensive Stakeholder X-Ray analysis for my project.

**Project Context:** [DESCRIBE YOUR PROJECT — e.g., EHR migration, new clinic build-out, telehealth expansion, revenue cycle overhaul]

For every stakeholder group you identify, provide:

1. **Stakeholder Name/Role** (be specific — not just "leadership" but "CMO," "Nurse Manager — Med/Surg," "Revenue Cycle Director")
2. **Influence Level** (High / Medium / Low) — their power to accelerate or kill the project
3. **Interest Level** (High / Medium / Low) — how much they care about the outcome
4. **Stance** (Champion / Supportive / Neutral / Resistant / Hostile)
5. **What They Care About Most** (1 sentence — their real motivation)
6. **Hidden Risk** (what could go wrong if you ignore them)
7. **Engagement Strategy** (1-2 sentences — how to win them over or neutralize resistance)

Organize into a table. Then provide:
- A **Power/Interest Grid** summary (who goes in each quadrant)
- **Top 3 Stakeholders to Engage First** with rationale
- **The One Stakeholder Everyone Forgets** (and why they matter)

Be specific to healthcare. Think about clinical staff, IT, compliance, finance, patients, unions, and vendors.