vylth-annotator 0.0.1__tar.gz

vylth_annotator-0.0.1/.gitignore

@@ -0,0 +1,10 @@
+node_modules
+dist
+.venv
+__pycache__
+*.pyc
+.env
+.env.local
+.DS_Store
+*.log
+.annot/

vylth_annotator-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vylth Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vylth_annotator-0.0.1/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: vylth-annotator
+Version: 0.0.1
+Summary: Drop-in design-feedback widget. Click → page freezes → drag a rect → engineer pulls the diagnostic envelope. Self-hostable on localhost.
+Project-URL: Homepage, https://github.com/VYLTH/annotator
+Project-URL: Repository, https://github.com/VYLTH/annotator
+Project-URL: Issues, https://github.com/VYLTH/annotator/issues
+Author-email: Vylth Labs <labs@vylth.com>
+License: MIT
+License-File: LICENSE
+Keywords: annotation,developer-tools,diagnostics,feedback,screenshot,widget
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: click>=8.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# annotator
+
+**Drop-in design-feedback widget for any web app.**
+
+Click the bubble → page freezes → drag a rectangle → type one sentence → an annotation drops onto the engineer's filesystem with the screenshot, the URL, the clicked element selector, console logs, network errors, and JS exceptions captured at the moment of the click.
+
+Self-hostable on localhost. Zero infrastructure.
+
+```bash
+pipx install vylth-annotator   # or: npm i -g vylth-annotator
+annotator run                  # opens dashboard at http://localhost:8092
+```
+
+Drop this into your dev site:
+
+```html
+<script src="http://localhost:8092/w.js"
+        data-project="local"
+        data-token="local"
+        data-webhook="http://localhost:8092/v1/feedback"></script>
+```
+
+Done. Submitted annotations appear as a `.png` + `.md` pair under `./.annot/local/` and on the dashboard. Run `annotator skill install` once and Claude Code / Codex / Cursor will pick them up automatically.
+
+## How it works
+
+```
+[bubble click]
+   ↓
+1. dom-to-image → static PNG of the viewport (≈80ms)        ← page freezes
+2. PNG becomes the backdrop, you draw rects on a <canvas>
+3. Comment + Send → POST diagnostic envelope to the API
+   ↓
+4. Server writes:
+   - SQLite row (queryable)
+   - .annot/<project>/<id8>-<slug>.png   (screenshot with rects baked in)
+   - .annot/<project>/<id8>-<slug>.md    (frontmatter + readable envelope)
+   - dashboard updates live
+   - optional: webhook fanout (Slack / Discord / Linear / custom HTTP)
+```
+
+The diagnostic envelope is collected automatically — the user only types the comment. `console.log/warn/error`, `fetch`, `XHR`, `window.onerror`, and `unhandledrejection` are tapped the moment `w.js` loads, ring-buffered, dumped at submit time.
+
+## Three install modes for the widget
+
+| Mode | When to use |
+|------|------------|
+| `<script>` tag | Any web app you control. One line, ≤30KB, vanilla, Shadow DOM isolated. |
+| Browser extension | Annotate any third-party site (competitor analysis, design refs). |
+| `@vylth/annotator-react` | React app that wants the widget visible only in dev/staging. |
+
+Mode 1 is shipped. Mode 2 + 3 are scaffolded — see `/mnt/vylth/labs/directives/annotator/DIR-0073-productize-annotator.md`.
+
+## Layout
+
+```
+src/vylth_annotator/      — pip-installable Python service
+  cli.py                  — `annotator run | list | pull | resolve | init | skill`
+  main.py                 — FastAPI app
+  models.py               — SQLAlchemy (SQLite locally, Postgres for hosted)
+  sink.py                 — disk writer (PNG + Markdown per annotation)
+  fanout.py               — Slack / Discord / Linear / HTTP webhook dispatch
+  templates/dashboard.html
+  static/w.js             — built widget bundle
+  skill/SKILL.md          — agent instructions
+
+packages/
+  widget/                 — TypeScript widget source (Vite single-file)
+  cli/                    — npm shim that forwards to the Python CLI
+
+pyproject.toml            — vylth-annotator on PyPI
+LICENSE                   — MIT
+```
+
+## Agent integration
+
+```bash
+annotator skill install --target auto
+```
+
+Drops `SKILL.md` into the right place for the agents present in your project — `.claude/skills/annotator/`, `AGENTS.md`, `.cursor/rules/`. Now the agent knows how to find new `.md` files in `.annot/`, read the diagnostic envelope, fix the underlying issue, and mark the annotation resolved.
+
+## License
+
+MIT. Built by [Vylth Labs](https://vylth.com).

vylth_annotator-0.0.1/README.md

@@ -0,0 +1,85 @@
+# annotator
+
+**Drop-in design-feedback widget for any web app.**
+
+Click the bubble → page freezes → drag a rectangle → type one sentence → an annotation drops onto the engineer's filesystem with the screenshot, the URL, the clicked element selector, console logs, network errors, and JS exceptions captured at the moment of the click.
+
+Self-hostable on localhost. Zero infrastructure.
+
+```bash
+pipx install vylth-annotator   # or: npm i -g vylth-annotator
+annotator run                  # opens dashboard at http://localhost:8092
+```
+
+Drop this into your dev site:
+
+```html
+<script src="http://localhost:8092/w.js"
+        data-project="local"
+        data-token="local"
+        data-webhook="http://localhost:8092/v1/feedback"></script>
+```
+
+Done. Submitted annotations appear as a `.png` + `.md` pair under `./.annot/local/` and on the dashboard. Run `annotator skill install` once and Claude Code / Codex / Cursor will pick them up automatically.
+
+## How it works
+
+```
+[bubble click]
+   ↓
+1. dom-to-image → static PNG of the viewport (≈80ms)        ← page freezes
+2. PNG becomes the backdrop, you draw rects on a <canvas>
+3. Comment + Send → POST diagnostic envelope to the API
+   ↓
+4. Server writes:
+   - SQLite row (queryable)
+   - .annot/<project>/<id8>-<slug>.png   (screenshot with rects baked in)
+   - .annot/<project>/<id8>-<slug>.md    (frontmatter + readable envelope)
+   - dashboard updates live
+   - optional: webhook fanout (Slack / Discord / Linear / custom HTTP)
+```
+
+The diagnostic envelope is collected automatically — the user only types the comment. `console.log/warn/error`, `fetch`, `XHR`, `window.onerror`, and `unhandledrejection` are tapped the moment `w.js` loads, ring-buffered, dumped at submit time.
+
+## Three install modes for the widget
+
+| Mode | When to use |
+|------|------------|
+| `<script>` tag | Any web app you control. One line, ≤30KB, vanilla, Shadow DOM isolated. |
+| Browser extension | Annotate any third-party site (competitor analysis, design refs). |
+| `@vylth/annotator-react` | React app that wants the widget visible only in dev/staging. |
+
+Mode 1 is shipped. Mode 2 + 3 are scaffolded — see `/mnt/vylth/labs/directives/annotator/DIR-0073-productize-annotator.md`.
+
+## Layout
+
+```
+src/vylth_annotator/      — pip-installable Python service
+  cli.py                  — `annotator run | list | pull | resolve | init | skill`
+  main.py                 — FastAPI app
+  models.py               — SQLAlchemy (SQLite locally, Postgres for hosted)
+  sink.py                 — disk writer (PNG + Markdown per annotation)
+  fanout.py               — Slack / Discord / Linear / HTTP webhook dispatch
+  templates/dashboard.html
+  static/w.js             — built widget bundle
+  skill/SKILL.md          — agent instructions
+
+packages/
+  widget/                 — TypeScript widget source (Vite single-file)
+  cli/                    — npm shim that forwards to the Python CLI
+
+pyproject.toml            — vylth-annotator on PyPI
+LICENSE                   — MIT
+```
+
+## Agent integration
+
+```bash
+annotator skill install --target auto
+```
+
+Drops `SKILL.md` into the right place for the agents present in your project — `.claude/skills/annotator/`, `AGENTS.md`, `.cursor/rules/`. Now the agent knows how to find new `.md` files in `.annot/`, read the diagnostic envelope, fix the underlying issue, and mark the annotation resolved.
+
+## License
+
+MIT. Built by [Vylth Labs](https://vylth.com).

vylth_annotator-0.0.1/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vylth-annotator"
+version = "0.0.1"
+description = "Drop-in design-feedback widget. Click → page freezes → drag a rect → engineer pulls the diagnostic envelope. Self-hostable on localhost."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Vylth Labs", email = "labs@vylth.com" }]
+keywords = ["annotation", "feedback", "screenshot", "widget", "diagnostics", "developer-tools"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Web Environment",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+dependencies = [
+  "fastapi>=0.110",
+  "uvicorn[standard]>=0.27",
+  "sqlalchemy[asyncio]>=2.0",
+  "aiosqlite>=0.20",
+  "pydantic>=2.6",
+  "pydantic-settings>=2.2",
+  "httpx>=0.27",
+  "click>=8.1",
+]
+
+[project.optional-dependencies]
+postgres = ["asyncpg>=0.29", "psycopg[binary]>=3.1"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/VYLTH/annotator"
+Repository = "https://github.com/VYLTH/annotator"
+Issues = "https://github.com/VYLTH/annotator/issues"
+
+[project.scripts]
+annotator = "vylth_annotator.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vylth_annotator"]
+artifacts = [
+  "src/vylth_annotator/static/*",
+  "src/vylth_annotator/templates/*",
+  "src/vylth_annotator/migrations/*",
+  "src/vylth_annotator/skill/*",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/README.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]

vylth_annotator-0.0.1/src/vylth_annotator/.env.example

@@ -0,0 +1,9 @@
+DATABASE_URL=postgresql+asyncpg://annotator:annotator@localhost:5432/annotator
+HOST=0.0.0.0
+PORT=8092
+ALLOWED_ORIGINS=*
+# R2 (optional — used for images > 500KB)
+R2_ACCOUNT_ID=
+R2_ACCESS_KEY=
+R2_SECRET_KEY=
+R2_BUCKET=annotator

vylth_annotator-0.0.1/src/vylth_annotator/auth.py

@@ -0,0 +1,56 @@
+"""
+Token auth: X-Annot-Token header → project_id.
+
+Tokens are stored hashed (SHA-256). The widget supplies the raw token; we hash
++ compare. No JWTs, no rotation logic in v0 — single shared token per project.
+
+Local mode (CLI): a single project + token is auto-provisioned on first request,
+so the user can `annotator run` and immediately point a widget at localhost
+without any setup.
+"""
+import hashlib
+
+from fastapi import Depends, Header, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .config import settings
+from .db import get_session
+from .models import Project
+
+
+def hash_token(raw: str) -> str:
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+async def _ensure_local_project(session: AsyncSession) -> Project:
+    result = await session.execute(select(Project).where(Project.id == settings.local_project))
+    proj = result.scalar_one_or_none()
+    if proj is None:
+        proj = Project(
+            id=settings.local_project,
+            name="Local",
+            token_hash=hash_token(settings.local_token),
+            destinations=[],
+        )
+        session.add(proj)
+        await session.commit()
+        await session.refresh(proj)
+    return proj
+
+
+async def project_from_token(
+    x_annot_token: str | None = Header(None, alias="X-Annot-Token"),
+    session: AsyncSession = Depends(get_session),
+) -> Project:
+    if settings.local_mode:
+        return await _ensure_local_project(session)
+
+    if not x_annot_token:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "missing X-Annot-Token")
+    token_hash = hash_token(x_annot_token)
+    result = await session.execute(select(Project).where(Project.token_hash == token_hash))
+    project = result.scalar_one_or_none()
+    if project is None:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "invalid token")
+    return project

vylth_annotator-0.0.1/src/vylth_annotator/cli.py

@@ -0,0 +1,252 @@
+"""
+`annotator` CLI entry point.
+
+Subcommands:
+  run       Start the API + dashboard locally (SQLite, zero config).
+  list      Show open feedback (your project, scoped by token).
+  pull      Download feedback envelopes + images to ./.annot/<project>/.
+  resolve   Mark a feedback item resolved.
+  init      Print the <script> snippet to embed into your dev site.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import webbrowser
+from pathlib import Path
+from typing import Optional
+
+import click
+import httpx
+
+from .config import settings
+
+
+def _set_local_mode() -> None:
+    """Force local mode for this process (the CLI default)."""
+    os.environ.setdefault("ANNOTATOR_LOCAL_MODE", "true")
+    settings.local_mode = True
+
+
+def _api_base(host: str | None = None, port: int | None = None) -> str:
+    h = host or settings.host or "127.0.0.1"
+    p = port or settings.port
+    return f"http://{h}:{p}"
+
+
+@click.group(help="Annotator — drop-in design-feedback widget. Self-hostable on localhost.")
+@click.version_option(package_name="vylth-annotator")
+def cli() -> None:
+    pass
+
+
+@cli.command(help="Run the annotator API + dashboard locally on http://localhost:8092.")
+@click.option("--host", default=None, help="Bind host (default 127.0.0.1).")
+@click.option("--port", default=None, type=int, help="Bind port (default 8092).")
+@click.option("--open/--no-open", "open_browser", default=True, help="Open dashboard in browser.")
+@click.option("--db", default=None, help="Override SQLite path or sqlalchemy URL.")
+@click.option("--sink", "sink_dir", default=".annot",
+              help="Write PNG + Markdown per annotation under this dir (default ./.annot). Pass '' to disable.")
+def run(host: Optional[str], port: Optional[int], open_browser: bool, db: Optional[str], sink_dir: str) -> None:
+    import uvicorn
+
+    _set_local_mode()
+    if db:
+        os.environ["ANNOTATOR_DATABASE_URL"] = (
+            db if "://" in db else f"sqlite+aiosqlite:///{Path(db).resolve()}"
+        )
+    if host:
+        os.environ["ANNOTATOR_HOST"] = host
+    if port:
+        os.environ["ANNOTATOR_PORT"] = str(port)
+
+    abs_sink = str(Path(sink_dir).resolve()) if sink_dir else ""
+    os.environ["ANNOTATOR_SINK_DIR"] = abs_sink
+
+    # Re-import settings so env overrides take effect.
+    from .config import settings as fresh
+    fresh.local_mode = True
+    fresh.sink_dir = abs_sink
+
+    base = _api_base(host=host or fresh.host, port=port or fresh.port)
+    click.echo(f"\n  annotator → {base}")
+    if abs_sink:
+        click.echo(f"  sink     → {abs_sink}/<project>/  (png + md per annotation)")
+    click.echo(f"\n  embed this in your dev site:")
+    click.echo(f"    <script src=\"{base}/w.js\" data-project=\"local\" data-token=\"local\" data-webhook=\"{base}/v1/feedback\"></script>\n")
+
+    if open_browser:
+        try:
+            webbrowser.open(base)
+        except Exception:
+            pass
+
+    uvicorn.run(
+        "vylth_annotator.main:app",
+        host=host or fresh.host,
+        port=port or fresh.port,
+        log_level="info",
+        reload=False,
+    )
+
+
+@cli.command("list", help="List open feedback for your token's project.")
+@click.option("--api", default=None, help=f"API base URL (default {_api_base()}).")
+@click.option("--token", default=None, help="Token (default $ANNOTATOR_TOKEN or 'local').")
+@click.option("--status", "status_filter", default="open", help="Filter by status.")
+@click.option("--limit", default=20, type=int)
+def list_cmd(api: Optional[str], token: Optional[str], status_filter: str, limit: int) -> None:
+    base = api or _api_base()
+    tok = token or os.environ.get("ANNOTATOR_TOKEN") or "local"
+    r = httpx.get(f"{base}/v1/feedback", params={"status": status_filter, "limit": limit}, headers={"X-Annot-Token": tok}, timeout=10)
+    if r.status_code != 200:
+        click.echo(f"error: {r.status_code} {r.text}", err=True)
+        sys.exit(1)
+    items = r.json().get("items", [])
+    if not items:
+        click.echo("no open feedback")
+        return
+    for fb in items:
+        click.echo(f"  {fb['id'][:8]}  {fb['pathname']:<32}  {fb['comment'][:80]}")
+
+
+@cli.command(help="Download feedback (envelope JSON + image) to ./.annot/<project>/.")
+@click.option("--api", default=None)
+@click.option("--token", default=None)
+@click.option("--out", default=".annot", help="Output directory.")
+def pull(api: Optional[str], token: Optional[str], out: str) -> None:
+    base = api or _api_base()
+    tok = token or os.environ.get("ANNOTATOR_TOKEN") or "local"
+    headers = {"X-Annot-Token": tok}
+    r = httpx.get(f"{base}/v1/feedback", params={"status": "open", "limit": 100}, headers=headers, timeout=10)
+    r.raise_for_status()
+    items = r.json().get("items", [])
+
+    if not items:
+        click.echo("no open feedback to pull")
+        return
+
+    out_dir = Path(out)
+    for fb in items:
+        proj_dir = out_dir / fb["project_id"]
+        proj_dir.mkdir(parents=True, exist_ok=True)
+        slug = fb["id"][:8]
+        env_path = proj_dir / f"{slug}.json"
+        img_path = proj_dir / f"{slug}.png"
+        env_path.write_text(json.dumps(fb, indent=2, default=str))
+        img = httpx.get(f"{base}/v1/feedback/{fb['id']}/image", headers=headers, timeout=15)
+        if img.status_code == 200:
+            img_path.write_bytes(img.content)
+        click.echo(f"  pulled {slug} → {env_path}")
+
+
+@cli.command(help="Mark a feedback item resolved.")
+@click.argument("fb_id")
+@click.option("--api", default=None)
+@click.option("--token", default=None)
+def resolve(fb_id: str, api: Optional[str], token: Optional[str]) -> None:
+    base = api or _api_base()
+    tok = token or os.environ.get("ANNOTATOR_TOKEN") or "local"
+    r = httpx.post(f"{base}/v1/feedback/{fb_id}/resolve", headers={"X-Annot-Token": tok}, timeout=10)
+    if r.status_code != 200:
+        click.echo(f"error: {r.status_code} {r.text}", err=True)
+        sys.exit(1)
+    click.echo(f"resolved {fb_id}")
+
+
+@cli.command(help="Print the <script> snippet to embed in your dev site.")
+@click.option("--host", default="localhost")
+@click.option("--port", default=8092, type=int)
+@click.option("--project", default="local")
+@click.option("--token", default="local")
+def init(host: str, port: int, project: str, token: str) -> None:
+    base = f"http://{host}:{port}"
+    snippet = (
+        f'<script src="{base}/w.js"\n'
+        f'        data-project="{project}"\n'
+        f'        data-token="{token}"\n'
+        f'        data-webhook="{base}/v1/feedback"></script>'
+    )
+    click.echo(snippet)
+
+
+@cli.group(help="Install the annotator skill so agents (Claude Code, Codex, Cursor, …) read .annot/ automatically.")
+def skill() -> None:
+    pass
+
+
+def _skill_text() -> str:
+    """Read the bundled SKILL.md."""
+    from importlib.resources import files
+    return (files("vylth_annotator") / "skill" / "SKILL.md").read_text(encoding="utf-8")
+
+
+@skill.command("install", help="Drop SKILL.md into the right place for the detected agent(s). Defaults to all that apply.")
+@click.option("--target", type=click.Choice(["auto", "claude", "codex", "cursor", "all"]), default="auto",
+              help="Which agent flavor(s) to install for.")
+@click.option("--cwd", default=".", help="Project root (default current dir).")
+def skill_install(target: str, cwd: str) -> None:
+    root = Path(cwd).resolve()
+    text = _skill_text()
+    written: list[Path] = []
+
+    targets: list[str]
+    if target == "auto":
+        targets = []
+        if (root / ".claude").exists() or (root / "CLAUDE.md").exists(): targets.append("claude")
+        if (root / "AGENTS.md").exists() or any(root.glob("*.codex*")):  targets.append("codex")
+        if (root / ".cursor").exists() or (root / ".cursorrules").exists(): targets.append("cursor")
+        if not targets:
+            targets = ["claude", "codex"]  # safe defaults
+    elif target == "all":
+        targets = ["claude", "codex", "cursor"]
+    else:
+        targets = [target]
+
+    for t in targets:
+        if t == "claude":
+            dst = root / ".claude" / "skills" / "annotator" / "SKILL.md"
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            dst.write_text(text, encoding="utf-8")
+            written.append(dst)
+        elif t == "codex":
+            # AGENTS.md convention — append a section if the file already has unrelated content.
+            dst = root / "AGENTS.md"
+            section = "\n\n## annotator\n\n" + text
+            if dst.exists():
+                existing = dst.read_text(encoding="utf-8")
+                if "## annotator" in existing:
+                    # rewrite the annotator section
+                    head, _, _ = existing.partition("## annotator")
+                    dst.write_text(head.rstrip() + section, encoding="utf-8")
+                else:
+                    dst.write_text(existing.rstrip() + section, encoding="utf-8")
+            else:
+                dst.write_text("# AGENTS\n" + section, encoding="utf-8")
+            written.append(dst)
+        elif t == "cursor":
+            dst = root / ".cursor" / "rules" / "annotator.md"
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            dst.write_text(text, encoding="utf-8")
+            written.append(dst)
+
+    click.echo("Installed:")
+    for p in written:
+        click.echo(f"  {p.relative_to(root)}")
+    click.echo()
+    click.echo("Now any time you submit an annotation, the agent will see new files appear in .annot/")
+    click.echo("and know how to read + resolve them. Run `annotator run` to start collecting.")
+
+
+@skill.command("show", help="Print the SKILL.md content to stdout (for piping into custom locations).")
+def skill_show() -> None:
+    click.echo(_skill_text())
+
+
+def main() -> None:  # entry point for pyproject.toml
+    cli()
+
+
+if __name__ == "__main__":
+    main()

vylth_annotator-0.0.1/src/vylth_annotator/config.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _default_db_url() -> str:
+    """SQLite under the user's data dir — zero-config local mode."""
+    home = Path.home() / ".vylth-annotator"
+    home.mkdir(parents=True, exist_ok=True)
+    return f"sqlite+aiosqlite:///{home / 'annotator.db'}"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore", env_prefix="ANNOTATOR_")
+
+    database_url: str = _default_db_url()
+    host: str = "127.0.0.1"
+    port: int = 8092
+    allowed_origins: str = "*"
+
+    # Local mode: when true, accept any token (single-user laptop scenario).
+    # The CLI sets this. Hosted deployments leave it false.
+    local_mode: bool = False
+    local_token: str = "local"
+    local_project: str = "local"
+
+    # Filesystem sink: when set, every accepted feedback writes a PNG + .md
+    # pair under <sink_dir>/<project_id>/. Agents (Claude Code, Codex, Cursor)
+    # read these directly — no API access required.
+    sink_dir: str = ""
+
+    r2_account_id: str = ""
+    r2_access_key: str = ""
+    r2_secret_key: str = ""
+    r2_bucket: str = "annotator"
+
+
+settings = Settings()