rdstudio 0.2.0__py3-none-any.whl

rdstudio/serve.py

@@ -0,0 +1,214 @@
+"""Serve the dashboard with the standard library, rebuilding when sources change."""
+
+from __future__ import annotations
+
+import email.utils
+import functools
+import gzip
+import io
+import json
+import os
+import secrets
+import sys
+import threading
+import time
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlsplit
+
+from . import learner
+from .build import WEB_DIR, build
+from .config import Config
+
+POLL_SECONDS = 1.0
+
+
+LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+# Text worth compressing: on a slow link (a VS Code tunnel, say) the dashboard's
+# 1.3 MB of scripts and data shrink to about 0.5 MB.
+COMPRESSIBLE = (".html", ".js", ".mjs", ".css", ".json", ".md", ".svg", ".txt", ".webmanifest", ".map")
+_gzipped: dict[tuple[str, int, int], bytes] = {}
+
+
+class _Handler(SimpleHTTPRequestHandler):
+    """Static files, plus ``/api/learner`` for the private learner record.
+
+    Writes are accepted only from the dashboard's own pages: the Origin must
+    match the Host, the body must be JSON, and the request must carry the token
+    handed out by GET (which other sites cannot read). When bound to localhost,
+    the API answers only to localhost names, Tailscale names (``*.ts.net``, as
+    ``tailscale serve`` passes them through) and ``--allow-host`` names, against
+    DNS rebinding."""
+
+    # Keep connections open between requests: through a tunnel, each new
+    # connection is slow to set up and more likely to be dropped.
+    protocol_version = "HTTP/1.1"
+
+    cfg: Config
+    token: str
+    loopback: bool
+    allowed: frozenset[str] = frozenset()
+
+    def _host_ok(self) -> bool:
+        host = urlsplit("//" + (self.headers.get("Host") or "")).hostname or ""
+        return not self.loopback or host in LOOPBACK or host.endswith(".ts.net") or host in self.allowed
+
+    def _json(self, status: int, value: object) -> None:
+        body = json.dumps(value, ensure_ascii=False).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        if self.close_connection:
+            self.send_header("Connection", "close")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self) -> None:
+        if urlsplit(self.path).path != "/api/learner":
+            return super().do_GET()
+        if not self._host_ok():
+            return self._json(403, {"error": "host not allowed"})
+        on = learner.enabled(self.cfg)
+        self._json(200, {
+            "enabled": on,
+            "token": self.token if on else None,
+            "dir": str(learner.record_dir(self.cfg)) if on else None,
+            "events": learner.events(self.cfg) if on else [],
+        })
+
+    def do_POST(self) -> None:
+        self.close_connection = True  # a refused body is never read; do not reuse the connection
+        if urlsplit(self.path).path != "/api/learner":
+            return self._json(404, {"error": "not found"})
+        origin = urlsplit(self.headers.get("Origin") or "").netloc
+        if not self._host_ok() or origin != self.headers.get("Host"):
+            return self._json(403, {"error": "cross-origin request refused"})
+        if self.headers.get("X-Rdstudio-Token") != self.token:
+            return self._json(403, {"error": "bad token"})
+        if not (self.headers.get("Content-Type") or "").startswith("application/json"):
+            return self._json(415, {"error": "JSON only"})
+        if not learner.enabled(self.cfg):
+            return self._json(409, {"error": "the learner record is off ([learner] enabled in the user config)"})
+        length = int(self.headers.get("Content-Length") or 0)
+        if length > learner.MAX_EVENT_BYTES:
+            return self._json(413, {"error": "event too large"})
+        try:
+            event = learner.append(self.cfg, json.loads(self.rfile.read(length) or b"null"))
+        except (ValueError, learner.LearnerError) as exc:
+            return self._json(400, {"error": str(exc)})
+        self._json(200, event)
+
+    def _cache_control(self) -> str | None:
+        path = urlsplit(self.path).path
+        if path.startswith("/vendor/"):
+            return "public, max-age=604800"  # changes only when rdstudio is upgraded
+        if path.startswith("/data/") or path.endswith((".html", ".js", ".css")) or path == "/":
+            return "no-cache"  # revalidate (cheap: 304 when unchanged)
+        return None
+
+    def end_headers(self) -> None:
+        if cc := self._cache_control():
+            self.send_header("Cache-Control", cc)
+        super().end_headers()
+
+    def send_head(self):  # type: ignore[override]
+        """Serve text gzipped when the browser accepts it; everything else as usual."""
+        path = self.translate_path(self.path)
+        if os.path.isdir(path) and urlsplit(self.path).path.endswith("/"):
+            path = os.path.join(path, "index.html")
+        if ("gzip" not in (self.headers.get("Accept-Encoding") or "") or not path.endswith(COMPRESSIBLE)
+                or not os.path.isfile(path)):
+            return super().send_head()
+        st = os.stat(path)
+        since = self.headers.get("If-Modified-Since")
+        if since:
+            try:
+                if int(st.st_mtime) <= email.utils.parsedate_to_datetime(since).timestamp():
+                    self.send_response(304)
+                    self.send_header("Vary", "Accept-Encoding")
+                    self.end_headers()
+                    return None
+            except (TypeError, ValueError, OverflowError):
+                pass
+        key = (path, st.st_mtime_ns, st.st_size)
+        body = _gzipped.get(key)
+        if body is None:
+            with open(path, "rb") as fh:
+                body = gzip.compress(fh.read(), compresslevel=6)
+            if len(_gzipped) > 512:
+                _gzipped.clear()
+            _gzipped[key] = body
+        self.send_response(200)
+        self.send_header("Content-Type", self.guess_type(path))
+        self.send_header("Content-Encoding", "gzip")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Last-Modified", self.date_time_string(int(st.st_mtime)))
+        self.send_header("Vary", "Accept-Encoding")
+        self.end_headers()
+        return io.BytesIO(body)
+
+    def log_message(self, format: str, *args: object) -> None:  # noqa: A002 - stdlib signature
+        pass
+
+
+def _fingerprint(cfg: Config) -> tuple:
+    """A cheap summary of everything the build reads."""
+    roots = [cfg.knowledge_dir, cfg.reports_dir, cfg.root / ".claude", WEB_DIR]
+    files = [cfg.root / "rdstudio.toml", cfg.root / ".git" / "HEAD", cfg.root / ".git" / "index"]
+    stamp: list[tuple[str, int, int]] = []
+    for root in roots:
+        if not root.is_dir():
+            continue
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+            for name in filenames:
+                p = os.path.join(dirpath, name)
+                try:
+                    st = os.stat(p)
+                except OSError:
+                    continue
+                stamp.append((p, st.st_mtime_ns, st.st_size))
+    for f in files:
+        if f.exists():
+            st = f.stat()
+            stamp.append((str(f), st.st_mtime_ns, st.st_size))
+    return tuple(sorted(stamp))
+
+
+def _watch(cfg: Config, stop: threading.Event) -> None:
+    last = _fingerprint(cfg)
+    while not stop.wait(POLL_SECONDS):
+        current = _fingerprint(cfg)
+        if current == last:
+            continue
+        try:
+            build(cfg)
+            print(f"[{time.strftime('%H:%M:%S')}] rebuilt", flush=True)
+        except Exception as exc:  # keep serving the last good build
+            print(f"[{time.strftime('%H:%M:%S')}] build failed: {exc}", file=sys.stderr, flush=True)
+        last = _fingerprint(cfg)  # the build may regenerate index.md files
+
+
+def serve(cfg: Config, *, host: str = "127.0.0.1", port: int = 8000, watch: bool = True,
+          allow_hosts: tuple[str, ...] = ()) -> None:
+    site = build(cfg)
+    handler_cls = type("Handler", (_Handler,), {
+        "cfg": cfg, "token": secrets.token_urlsafe(24), "loopback": host in LOOPBACK,
+        "allowed": frozenset(h.lower() for h in allow_hosts)})
+    handler = functools.partial(handler_cls, directory=str(site))
+    server = ThreadingHTTPServer((host, port), handler)
+    stop = threading.Event()
+    if watch:
+        threading.Thread(target=_watch, args=(cfg, stop), daemon=True).start()
+    shown = "localhost" if host in ("127.0.0.1", "0.0.0.0") else host
+    print(f"Serving {cfg.title} at http://{shown}:{port}/  (Ctrl+C to stop)", flush=True)
+    if host == "0.0.0.0":
+        print("Listening on all interfaces (reachable over your tailnet/LAN).", flush=True)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        stop.set()
+        server.server_close()
+

rdstudio/store.py

@@ -0,0 +1,161 @@
+"""Writing concepts with provenance: create, update (whole body or one section), verify."""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .okf import (
+    RESERVED,
+    FrontmatterError,
+    headings,
+    now,
+    render_concept,
+    split_frontmatter,
+)
+
+_SAFE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]*$")
+
+
+class StoreError(ValueError):
+    pass
+
+
+@dataclass
+class WriteResult:
+    id: str
+    path: str
+    created: bool
+    significant: bool
+    decided_by: str = "caller"
+
+    def as_dict(self) -> dict[str, Any]:
+        return {"id": self.id, "path": self.path, "created": self.created, "significant": self.significant,
+                "decided_by": self.decided_by}
+
+
+def concept_path(root: Path, cid: str) -> Path:
+    cid = cid.strip().lstrip("/")
+    if cid.endswith(".md"):
+        cid = cid[:-3]
+    norm = posixpath.normpath(cid)
+    if not _SAFE_ID.match(norm) or norm.startswith("..") or "/../" in f"/{norm}/":
+        raise StoreError(f"invalid concept id: {cid!r}")
+    if posixpath.basename(norm) + ".md" in RESERVED:
+        raise StoreError(f"{posixpath.basename(norm)}.md is reserved by OKF")
+    return root / f"{norm}.md"
+
+
+def _read(path: Path) -> tuple[dict[str, Any], str]:
+    meta, body = split_frontmatter(path.read_text(encoding="utf-8"))
+    return (meta or {}), body
+
+
+def replace_section(body: str, heading: str, content: str) -> str:
+    """Replace the content under ``heading`` (keeping the heading line); append the
+    section at the end when it does not exist."""
+    wanted = heading.strip().lstrip("#").strip()
+    hs = headings(body)
+    lines = body.split("\n")
+    for idx, h in enumerate(hs):
+        if h.text.lower() == wanted.lower():
+            end = len(lines)
+            for later in hs[idx + 1 :]:
+                if later.level <= h.level:
+                    end = later.line
+                    break
+            new = lines[: h.line + 1] + ["", content.strip(), ""] + lines[end:]
+            return "\n".join(new)
+    return body.rstrip() + f"\n\n# {wanted}\n\n{content.strip()}\n"
+
+
+def record(
+    root: Path,
+    cid: str,
+    *,
+    actor: str,
+    body: str | None = None,
+    meta: dict[str, Any] | None = None,
+    section: str | None = None,
+    append: str | None = None,
+    significant: bool | None = True,
+    classifier: Any = None,
+) -> WriteResult:
+    """Create or update a concept.
+
+    - ``meta`` keys overwrite existing keys; a ``None`` value deletes the key.
+      Unknown keys already present are preserved.
+    - ``body`` replaces the whole body; ``section`` + ``body`` replaces only that
+      section; ``append`` adds text at the end.
+    - ``significant`` edits stamp ``generated: {by, at}`` (OKF: last meaningful
+      change). Minor edits leave provenance untouched. ``None`` lets the
+      classifier decide from the before and after text.
+    """
+    path = concept_path(root, cid)
+    created = not path.exists()
+    if created:
+        current_meta: dict[str, Any] = {}
+        current_body = ""
+        significant = True
+    else:
+        try:
+            current_meta, current_body = _read(path)
+        except FrontmatterError as exc:
+            raise StoreError(f"cannot update {path.name}: {exc}") from exc
+
+    new_meta = dict(current_meta)
+    for key, value in (meta or {}).items():
+        if value is None:
+            new_meta.pop(key, None)
+        else:
+            new_meta[key] = value
+    if not new_meta.get("type"):
+        raise StoreError("a concept needs a non-empty 'type'")
+
+    new_body = current_body
+    if body is not None:
+        new_body = replace_section(current_body, section, body) if section else body
+    if append:
+        new_body = new_body.rstrip() + "\n\n" + append.strip() + "\n"
+
+    decided_by = "caller"
+    if significant is None:
+        headline = any(new_meta.get(k) != current_meta.get(k) for k in ("type", "title", "description"))
+        if headline:
+            significant, decided_by = True, "rules"
+        else:
+            from .classify import RulesClassifier
+
+            decision = (classifier or RulesClassifier()).choose(
+                "edit_significance", ["minor", "significant"], {"before": current_body, "after": new_body})
+            significant, decided_by = decision.choice != "minor", decision.backend
+
+    if significant:
+        new_meta["generated"] = {"by": actor, "at": now()}
+
+    # Keep 'type' first for readability.
+    ordered = {"type": new_meta.pop("type"), **new_meta}
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_concept(ordered, new_body), encoding="utf-8")
+    rel = path.relative_to(root).as_posix()
+    return WriteResult(rel[:-3], rel, created, bool(significant), decided_by if not created else "new")
+
+
+def verify(root: Path, cid: str, *, actor: str) -> WriteResult:
+    """Append a verification event by ``actor`` at the current time."""
+    path = concept_path(root, cid)
+    if not path.exists():
+        raise StoreError(f"no such concept: {cid}")
+    meta, body = _read(path)
+    events = meta.get("verified")
+    if isinstance(events, dict):
+        events = [events]
+    events = list(events or [])
+    events.append({"by": actor, "at": now()})
+    meta["verified"] = events
+    path.write_text(render_concept(meta, body), encoding="utf-8")
+    rel = path.relative_to(root).as_posix()
+    return WriteResult(rel[:-3], rel, False, False)

rdstudio/templates/agents/critic.md

@@ -0,0 +1,20 @@
+---
+name: critic
+description: Reviews a plan, design, change or claim critically against the project's recorded decisions, conventions and evidence. Use before committing to a plan, after a substantial change, or when a result seems too good.
+tools: Read, Grep, Glob, mcp__rdstudio__search, mcp__rdstudio__outline, mcp__rdstudio__read
+---
+
+You are a critic. Your job is to find what is wrong, missing or unjustified,
+not to praise or rewrite.
+
+Check the material you are given against:
+1. Recorded decisions (search `type: Decision`). Flag any conflict, and whether
+   the decision's stated assumption still holds.
+2. Recorded conventions and procedures.
+3. Internal consistency: do the claims follow from the evidence shown?
+4. Omissions: edge cases, untested paths, unstated assumptions.
+
+Reply with a numbered list of issues, most serious first. For each: what is
+wrong, why it matters, and the evidence (file:line or concept id). Separate
+**blocking** issues from **worth considering**. If you find nothing
+significant, say so in one line. Do not pad.

rdstudio/templates/agents/librarian.md

@@ -0,0 +1,21 @@
+---
+name: librarian
+description: Answers questions from the project knowledge base (OKF) without filling the main agent's context. Use for lookups that need several searches, or to check whether something is already decided, answered or documented.
+tools: mcp__rdstudio__search, mcp__rdstudio__outline, mcp__rdstudio__read, mcp__rdstudio__list_concepts, mcp__rdstudio__backlinks
+---
+
+You are the librarian for this project's knowledge base. You find and report
+what is recorded; you do not write to it and you do not speculate beyond it.
+
+Method:
+1. Search with several phrasings and filters (type, tags, directory).
+2. Use outline before read, and read only the sections you need.
+3. Follow links when the answer spans concepts.
+
+Reply in at most ~200 words:
+- **Answer**: what the knowledge base says, in plain terms.
+- **Sources**: concept ids, each with its trust (human-reviewed,
+  machine-confirmed, unverified; note if changed since review).
+- **Gaps**: what is not recorded, or where concepts disagree.
+
+If nothing relevant is recorded, say so plainly. Never invent content.

rdstudio/templates/agents/searcher.md

@@ -0,0 +1,21 @@
+---
+name: searcher
+description: Finds and summarises external information (web pages, papers, documentation, PDFs) for a specific question. Use for literature or documentation lookups whose raw results would flood the main context.
+tools: WebSearch, WebFetch, Read, Bash
+---
+
+You are a research assistant. Find reliable sources that answer the question
+you are given and summarise them compactly.
+
+- Prefer primary sources: papers, official documentation, specifications.
+- For PDFs available locally, extract only the relevant pages
+  (e.g. `pdftotext -f N -l M file.pdf -`).
+- Record nothing in the knowledge base yourself; the main agent decides what to
+  keep.
+
+Reply in at most ~300 words:
+- **Findings**: bullet points, each with its source.
+- **Sources**: full citation or URL for each, with a stable short id
+  (e.g. `tao2008circular`) the main agent can use in `sources`.
+- **Confidence and gaps**: what is well supported, what is not, and what you
+  could not find.

rdstudio/templates/agents_section.md

@@ -0,0 +1,31 @@
+<!-- rdstudio:start (managed by rdstudio init; edits between these markers are replaced) -->
+## Project knowledge (rdstudio)
+
+This project keeps a knowledge base in `{knowledge}/`, in Open Knowledge Format
+(markdown + YAML frontmatter). It records design, decisions, questions, tasks,
+procedures, references and findings, authored jointly by the developer and
+agents. A read-only dashboard shows it: `rdstudio serve`.
+
+The `rdstudio` MCP server gives access to it, and the skills named below
+(`search-okf`, `record-okf`, ...) describe how to use it; in Claude Code they
+are also slash commands.
+
+- **Start oriented.** If this session did not open with a knowledge-base brief,
+  call the rdstudio `brief` tool first.
+- **Look before re-deriving.** Search the knowledge base (the `search-okf`
+  skill, or the `librarian` subagent) before reopening a question or
+  redesigning something. Recorded decisions stand unless their stated
+  assumption is shown false.
+- **Record as you go.** Decisions (`decision`), questions (`question`),
+  findings and procedures (`record-okf`), tasks (`task`). Write through the
+  rdstudio MCP tools so provenance is stamped. Do not edit `index.md` files.
+- **Report substantial work** as HTML in `{reports}/` (the `report` skill).
+- **Close sessions** with the `handoff` skill.
+- **Global knowledge:** if the developer has a cross-project knowledge base,
+  search it with `scope: "global"` (or `"all"`); suggest the `promote` skill
+  for knowledge that is not specific to this project.
+- **Trust:** only the developer verifies concepts. Mark edits
+  `significant: false` only when trivial or dictated.
+- The developer's actor id for provenance is `{human}`; the rdstudio tools
+  stamp yours.
+<!-- rdstudio:end -->

rdstudio/templates/claude_section.md

@@ -0,0 +1,3 @@
+<!-- rdstudio:start (managed by rdstudio init; edits between these markers are replaced) -->
+@AGENTS.md
+<!-- rdstudio:end -->

rdstudio/templates/knowledge/overview.md

@@ -0,0 +1,20 @@
+---
+type: Overview
+title: {title}
+description: What this project is, in one sentence. (Placeholder; replace.)
+status: draft
+tags: [overview]
+---
+
+# Purpose
+
+What this project sets out to do, and why.
+
+# Scope
+
+What is in and out of scope.
+
+# Where things are
+
+The knowledge base is organised into directories. See the
+[bootstrap task](/tasks/bootstrap-knowledge-base.md) for how to set them up.

rdstudio/templates/knowledge/tasks/bootstrap-knowledge-base.md

@@ -0,0 +1,45 @@
+---
+type: Task
+title: Bootstrap the knowledge base
+description: Tailor this knowledge base to the project with the developer.
+tags: [task, todo]
+---
+
+# Prompt
+
+This knowledge base was just created by `rdstudio init` and holds only
+placeholders. Working with the developer, tailor it to this project.
+
+1. **Learn the project.** Read the repository's README, CLAUDE.md or
+   AGENTS.md, existing docs and recent history. Ask the developer what the
+   project is for, who it is for, and what stage it is at.
+2. **Propose a directory structure** suited to the project, and agree it with
+   the developer before creating anything. Common directories: `design/`,
+   `decisions/`, `questions/`, `tasks/`, `procedures/`, `references/`,
+   `research/`, `experiments/`. Add project-specific ones where they earn their
+   place (for example `thesis/` for a thesis project), and leave out ones that
+   do not.
+3. **Write the overview** ([overview](/overview.md)): purpose, scope, and a map
+   of the directories. Give each directory an `overview.md` (`type: Overview`)
+   when it needs explanation.
+4. **Seed from existing material.** Where the repository already holds design
+   notes, decision logs or references, record them as concepts. Material the
+   developer wrote is recorded with `generated.by` set to their actor id.
+5. **Record procedures** the developer repeats (release steps, data
+   regeneration, bibliography updates) as `type: Procedure` concepts.
+6. Write a short report (`/report`) summarising the structure and what was
+   seeded, and mark this task done.
+
+# Plan
+
+(To be written by the agent and approved by the developer.)
+
+# Acceptance
+
+- The developer has agreed the directory structure.
+- The overview describes the project and maps the directories.
+- `rdstudio check` passes.
+
+# Outcome
+
+Not started.

rdstudio/templates/skills/decision/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: decision
+description: Record a decision with its assumption and the conditions for reopening it. Use when the developer settles a design or research choice, or asks to log a decision.
+---
+
+# Record a decision
+
+Decisions are recorded so they are not relitigated. Each one states what was
+decided, the assumption it rests on, and what would justify reopening it. A
+decision is reopened only when its assumption is shown false or the goal it
+serves changes; an interesting alternative is not enough.
+
+## Steps
+
+1. Search `type: Decision` for an existing decision on the topic. If one
+   exists, update it (and say whether you are revising or reopening it).
+2. Record at `decisions/<short-slug>` with the rdstudio `record` tool:
+
+```markdown
+---
+type: Decision
+title: <the decision, as a statement>
+description: <one sentence>
+tags: [<area>]
+---
+
+# Decision
+
+What was decided, concretely.
+
+# Assumption
+
+What must be true for this to be right, and the evidence for it.
+
+# Alternatives considered
+
+Briefly, and why they lost.
+
+# Reopen if
+
+The specific observations that would justify revisiting it.
+```
+
+3. Link the decision from the concepts it governs (design, tasks) and link to
+   the evidence (references, experiments).
+4. Decisions are the developer's. Record what they decided in their terms; if
+   you are proposing a decision, record it with `status: draft` and say so.

rdstudio/templates/skills/handoff/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: handoff
+description: Close out a working session so the next session (human or agent) can pick up without re-deriving anything. Use at the end of a session or before a long break.
+---
+
+# Hand off
+
+1. **Decisions** made this session: record each with the `decision` skill.
+2. **Questions** raised and not answered: record with the `question` skill. Mark any
+   answered ones.
+3. **Tasks**: update the `# Outcome` and state tag of every task touched.
+4. **Findings and procedures**: record anything learned the hard way with
+   the `record-okf` skill. If a repeated process emerged, record or update a
+   `type: Procedure` concept.
+5. **Report**: if substantial work was done, write one with the `report` skill.
+6. Summarise to the developer in chat: what was recorded (concept ids), what is
+   waiting for their review (the rdstudio `review_queue` tool), and the suggested
+   next step.

rdstudio/templates/skills/ingest-ref/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: ingest-ref
+description: Add a paper or book to the bibliography (papis) and the knowledge base. Use when the developer names a paper, DOI, arXiv id or ISBN to add, or after syncing items captured in Zotero.
+---
+
+# Ingest a reference
+
+Requires `[references] backend = "papis"` in `rdstudio.toml`. If a procedure
+concept for adding references exists (search `type: Procedure`), follow it
+with the rdstudio `procedure_next` tool instead of these generic steps; it holds
+this project's conventions and known pitfalls.
+
+1. **Check it is not already there:** search with the rdstudio `ref_search` tool.
+2. **Add it to papis:** `papis add --from doi <doi>` (or `--from isbn`,
+   `--from arxiv`). Run non-interactively with `--batch` where the project's
+   procedure says so.
+3. **Fix the citekey** to the project's convention if papis generated a
+   different one: `papis update --batch --set ref <key> <current-ref>`.
+4. **Check the metadata:** authors split correctly into family and given names,
+   year, venue. Fix `author_list`, not the flat `author` field.
+5. **Create the knowledge stub:** `rdstudio refs sync`.
+6. **Summarise, if asked:** read only the pages you need with
+   the rdstudio `ref_text` tool (by page range or query), then fill the stub's
+   `# Summary` and `# Relevance` sections with the `record-okf` skill. Link the
+   decisions, questions or designs it bears on.
+7. Regenerate any exported bibliography the project uses (for example
+   `make refs`).
+
+## Items captured in Zotero
+
+If the project pulls phone captures from Zotero (for example `make zotero-sync`),
+run that first; the imported items then go through steps 3 to 6.

rdstudio/templates/skills/lint-okf/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: lint-okf
+description: Check the knowledge base for OKF format errors and broken links, and fix what can be fixed. Use after bulk edits or when the dashboard's Review tab shows format errors.
+---
+
+# Lint the knowledge base
+
+1. Run `rdstudio check -w`.
+2. Fix **errors** (missing frontmatter, missing `type`, frontmatter in a
+   non-root `index.md`) with the rdstudio `record` tool or by editing the file.
+3. **Broken links** point at knowledge that does not exist yet. Do not delete
+   them by reflex: list them for the developer as candidate concepts, and fix
+   only the ones that are typos or moved files.
+4. Run `rdstudio index` if indexes are out of date (the MCP server and the
+   dashboard server regenerate them automatically).