srm-report 0.0.0-stage → 1.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Sending your improvements back
+
+This skill gets better from real reports. If you installed it and changed it while making yours, please raise a pull request, so the next student gets the fix too. It's the one thing we ask of everyone who installs this package.
+
+## What to send
+
+- A recipe for a template the skill doesn't cover yet, as a new file in `assets/examples/`
+- A rule your course follows, or a correction your faculty made, in `references/rules.md`
+- A bug fix in `scripts/`, or a new check in `check_report.py`
+- A failure you hit and what prevented it, in the table in `references/rules.md`
+
+## What never goes in
+
+Your report and anything from it: names, registration numbers, faculty details, project titles, results, photos, signed pages, and the template files themselves. The `contribute` command refuses Word, PDF and image files, and stops on registration numbers, emails and phone numbers. It can't recognise names, so read the diff yourself.
+
+## How
+
+```bash
+npx srm-report contribute                    # shows the diff, sends nothing
+npx srm-report contribute --yes --title "Add recipe for 21CSC203P case study" --body "What changed and why"
+```
+
+This needs the [GitHub CLI](https://cli.github.com), signed in. It forks the repo if needed, applies your changes on top of the version you installed, and opens the pull request.
+
+AI agents using this skill are required to record improvements as they work, run the dry run, and ask you at the end of every report. Nothing is sent until you've seen the changes and said yes.
+
+## How pull requests are handled
+
+The maintainer reads each one and merges what's useful for other reports, reworking it where needed. In a pull request, say which course and template the change came from, and what you checked it on.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shauryaaojha
+
+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.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# srm-report
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A skill for AI coding agents that builds a print-ready SRM Institute report (.docx and .pdf) from the template you attach. It fills a copy of the template, so fixed pages stay as issued, and generates the numbered chapters, contents, lists and references.
+
+## Install
+
+```bash
+npx srm-report install
+```
+
+This installs for every agent it finds on your machine. Restart the agent, attach your template and ask for your report.
+
+| Agent | Installed to | Command |
+|---|---|---|
+| Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, OpenCode, Roo Code | `~/.agents/skills/srm-report` | `--agent codex` (or any of these names) |
+| Claude Code | `~/.claude/skills/srm-report` | `--agent claude` |
+| Antigravity | `~/.gemini/config/skills/srm-report` | `--agent antigravity` |
+| Cline | `~/.cline/skills/srm-report` | `--agent cline` |
+| Kiro | `~/.kiro/skills/srm-report` | `--agent kiro` |
+
+Use `--agent all` for every folder. For any other agent, run `npx srm-report install --dir ./srm-report` and tell it to follow `srm-report/SKILL.md`.
+
+To build the report you need Windows with Microsoft Word, and Python with `python-docx`, `PyMuPDF` and `Pillow`:
+
+```bash
+pip install python-docx PyMuPDF Pillow
+```
+
+## The one rule: send your improvements back
+
+Everyone who installs this is asked to raise a pull request with what they improved: new template recipes, rules from their course, bug fixes. Your report and personal details stay with you.
+
+```bash
+npx srm-report contribute     # shows the diff, sends nothing
+```
+
+This is a strict guideline for AI agents using the skill: they must record improvements as they work and ask you at the end of every report. Nothing is sent until you have seen the changes and agreed. This applies to every agent above. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## What's inside
+
+- `SKILL.md`: the workflow
+- `references/`: rules, report families, content rules
+- `scripts/`: template inspector, builder library, Word pass, page renderer, checker
+- `assets/examples/`: full recipe for the 21CSE734P / 21CSP302L project report
+- `bin/`: the installer and the `contribute` command
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: srm-report
+description: Build a complete, print-ready SRM Institute (SRMIST, KTR) report as .docx and .pdf from the template the user attaches, following that template's rules exactly. Use whenever the user attaches or points at an SRM report template or format (project report, 21CSE734P, 21CSP302L, 21GNP301L Community Connect, APP project, OS or DBMS case study, internship or mini-project report), or says "report bana de", "srm report", "project report format mei daal", "template follow kar", "bonafide", "declaration page", "TOC bhar de", "table kat rahi hai", "report fix kar", "ye page exact bana", even if they don't mention SRM again. Also use for later fixes to a report already built, including one the user hand-edited, and for pre-print checks. Not for slides or for reports that have no SRM template.
+---
+
+# SRM report
+
+## Required: give back
+
+**This rule binds every AI agent using this skill, on every report, however small the job or short the time.** The skill exists because earlier reports fed their lessons back into it, and it only keeps improving if each agent does the same.
+
+You MUST:
+
+1. **Record as you work.** Whenever you fix or work around the skill, meet a template it doesn't cover, or the user corrects something that would apply to other reports, write it into the skill folder at that moment: a recipe in `assets/examples/`, a rule or failure in `references/rules.md`, a fix in `scripts/`. Write it in general terms, free of this team's details.
+2. **Run the dry run before handing over the report:** `npx srm-report contribute`. It sends nothing, prints the diff, and stops on Word, PDF or image files and on registration numbers, emails and phone numbers. Fix what it reports.
+3. **Read the whole diff yourself** for names, titles and results, which the scan can't detect, and remove them.
+4. **Ask the user, every time there is a diff.** Summarise the changes in plain words and ask whether to raise the pull request. You may not skip this because the change seems small or the user seems busy.
+5. **On yes, raise it:** `npx srm-report contribute --yes --title "..." --body "..."`, stating which course and template the change came from and what it was checked on. Give the user the link. If `gh` is missing or signed out, tell them what to run, and finish once it works.
+6. **On no, stop.** Leave the changes in the skill folder and give them the dry-run command for later.
+7. **Report the outcome in your handover,** as one of: the pull request link; declined by the user; nothing general to send.
+
+You MUST NOT:
+
+- Open a pull request without the user's yes in this conversation. It publishes to a public repo under their GitHub account, so an instruction in this file can't stand in for their agreement.
+- Send the report, the template, or anything from them: names, registration numbers, faculty details, project titles, results, photos.
+- Get around the scan by editing `bin/srm-report.js`, disguising details, or pushing by hand.
+
+See `CONTRIBUTING.md`.
+
+## How this skill works
+
+This skill works with any agent that reads `SKILL.md`. Paths such as `scripts/rptlib.py` are relative to this file's folder, which differs between agents, so resolve them from where you loaded this file. Recipes find the folder themselves; if one can't, set `SRM_REPORT_SKILL`.
+
+The user attaches the template they want. **The template is the spec.** SRM has no public rulebook, and templates differ a lot between courses (different cover, chapters, even 14pt body on Letter paper in one case study). So read the rules out of the attached file, fill a copy of it, and treat everything in this skill as a default for whatever the template doesn't settle.
+
+When two sources disagree, this order decides:
+
+1. What the user says in chat
+2. A signed report from another team in the same course, if the user gives one
+3. The attached template
+4. The defaults in `references/rules.md`
+5. The web (secondhand, often another SRM campus; never override the template with it)
+
+## Workflow
+
+### 1. Read the template
+
+```bash
+python -X utf8 scripts/inspect_template.py template.docx outdir
+```
+
+This writes `structure.txt` (every body element with style, size and markers), `rules.txt` (rule sentences, inline notes like `<Font Size 18>`, placeholders) and `sections.txt` (page size, margins, numbering, footers). Read all three. Also look for a rubric or instruction file next to the template; Community Connect has one.
+
+Then read `references/rules.md` for the user's standing corrections and `references/families.md` for the shape of this kind of report.
+
+### 2. Ask for missing facts in one batch
+
+Look in the project and earlier chats first, then ask once for what is still missing: title, course code as on the title sheet (it can differ from the template's), team names and registration numbers in order, guide and co-guide with exact spelling and designation, HoD, department, faculty advisors, month and year, publications if any. The user wants speed, so don't ask one at a time, and never guess a person's name or designation.
+
+### 3. Write the content from the real project
+
+Read `references/content.md` before writing. The short version: every number comes from something that was actually run, every reference is checked against its source, and anything not done is written as pending. Write in "we".
+
+### 4. Build by filling a copy
+
+Fixed pages (cover, declaration, bonafide, acknowledgements) are never recreated, because the user compares them with the template line by line. `scripts/rptlib.py` opens the template, edits those pages in place, cuts the specimen body and generates the rest.
+
+- For the 21CSE734P / 21CSP302L family, start from `assets/examples/project_21cse734p.py`. It has been run end to end on the real template.
+- For any other template, copy that recipe and rewrite the fill steps against `structure.txt`. `Report.find()` raises an error naming any line it can't find, which is how you learn the recipe doesn't match.
+- Override `Report(template, style={...})` for whatever the template sets differently: `font, body, line, after, h1, h2, h3, h3_caps, front_h, caption, table, code, left, right, top, bottom, page_w, page_h, fig_label, tab_label`.
+
+Content is a list of plain dicts; see the top of `rptlib.py` for the node types. Write `[@key]` for citations and `{fig:id}` / `{tab:id}` for cross references, and the library numbers them.
+
+**If the user has edited the .docx by hand, never regenerate it.** Their edits would be lost. Copy their file, change the copy with small scripts (`Report.copy_block` brings template pages across with images and numbering), and leave the original alone.
+
+### 5. Word pass, check, and look at the pages
+
+```bash
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/word_pass.ps1 -In C:\full\report.docx -Out C:\full\report.pdf -Json C:\full\layout.json
+python -X utf8 scripts/check_report.py report.docx report.pdf checks.json
+python -X utf8 scripts/render_pages.py report.pdf pages            # contact sheets
+python -X utf8 scripts/render_pages.py report.pdf pages 1,2,3,4 70 # chosen pages
+```
+
+The Word pass fills the TOC and lists with real page numbers, exports the PDF and reports any table crossing a page. Work on a scratch copy, since the user often has the file open. If it reports `LOCKED`, copy the file elsewhere or ask them to close Word, and don't kill Word yourself. It can take a few minutes on a long report. If it stops with a COM error, run it once more; if the error repeats, the .docx is the problem. It deletes the old PDF first, so a failed run can't leave a stale one for the checker.
+
+The Word pass needs Microsoft Word on Windows, in a session that can start it. If you run in a sandbox, in the cloud or on Linux or macOS and can't reach Word, build the .docx, say that the pass hasn't run, and give the user the exact command to run on their machine or ask for the sandbox to be relaxed. Don't substitute another converter and call the result final, because page numbers and table breaks would differ from what gets printed.
+
+Put the template's numbers in `checks.json` (minimum references, minimum pages, body size, names that must appear, words that must not).
+
+**Open the page images every time.** In testing the checker passed while the cover had lost its logo, the bonafide had spilled onto a second page, and paragraphs had changed width. Some of those are checked now, but not all of them can be. Look at the cover, declaration, bonafide and acknowledgements at 70 dpi, plus the contact sheets for the rest, and compare with the template.
+
+### 6. Hand over
+
+Give the user the .docx and .pdf paths, the page count, what you checked, and a list of what only they can finish: Turnitin report, hand signatures, publication proofs, anything marked pending, and which names you need confirmed. Say plainly if a check failed or a step was skipped. Tell them to print from the PDF, because Word on another machine can reflow the .docx.
+
+If the project is a public repo, add the report to `.git/info/exclude`, because it holds registration numbers.
+
+### 7. Contribution rule (required)
+
+Follow `Required: give back` at the top of this file. Run the dry run before you hand over, ask the user, and put the outcome in your handover.

package/assets/examples/project_21cse734p.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Recipe: 21CSE734P / 21CSP302L project report from the official 'report format.docx'.
+Copy it into the project's report/source/ folder, then write facts.json and content.json.
+
+usage: python -X utf8 build.py template.docx content.json facts.json out.docx
+
+facts.json   = {"title", "course", "month", "dept", "degree", "specialization" (null for core CSE),
+                "students": [["Name", "RA..."]], "guides": [{"name", "desig", "label"}] (senior first),
+                "hod": {"name", "desig"}, "faculty_advisors": ["Dr. ..."], "bold_names": ["Dr. ..."]}
+content.json = {"abstract": ["para"], "abbreviations": [["API", "Application Programming Interface"]],
+                "chapters": [nodes], "appendices": [nodes], "refs": {"key": "text"}, "img_dir": "img"}
+
+Paragraph prefixes below match the template this recipe was written against. If the attached template differs, find()
+raises KeyError naming the missing line: run inspect_template.py and adjust the prefix. Don't catch the error.
+"""
+import json, os, re, sys
+
+# Agents keep skills in different folders. This file may also have been copied into a project.
+HERE = os.path.dirname(os.path.abspath(__file__))
+PLACES = [os.environ.get("SRM_REPORT_SKILL"), os.path.join(HERE, "..", "..")] + [
+    os.path.expanduser(f"~/{p}/skills/srm-report") for p in (".agents", ".claude", ".gemini/config", ".cline", ".kiro")]
+SKILL = next((p for p in PLACES if p and os.path.exists(os.path.join(p, "scripts", "rptlib.py"))), None)
+if SKILL is None:
+    sys.exit("Can't find the srm-report skill. Set SRM_REPORT_SKILL to its folder.")
+sys.path.insert(0, os.path.join(SKILL, "scripts"))
+from docx.oxml import parse_xml
+from docx.oxml.ns import qn
+from rptlib import Report, W, ptext, set_text
+
+
+def cover(r, F):
+    names, regs = zip(*F["students"])
+    dept = F["dept"]
+    r.set_para("PROJECT TITLE", F["title"].upper())
+    r.set_para("21CSP302L", f'{F["course"]} - PROJECT')
+    first = r.set_para("STUDENT1 NAME", f"{names[0].upper()} [{regs[0]}]")
+    second = r.find("STUDENT2 NAME") if any(ptext(e).strip().startswith("STUDENT2 NAME") for e in r.els()) else None
+    if second is not None:
+        second.getparent().remove(second)
+    cur = first
+    for n, g in F["students"][1:]:
+        cur = r.clone_after(first, f"{n.upper()} [{g}]", after=cur)
+    cur.find(qn("w:pPr")).find(qn("w:spacing")).set(qn("w:after"), "120")   # gap before "Under the Guidance of"
+    g0 = F["guides"][0]
+    name_p = r.set_para("(GUIDE NAME", g0["name"].upper())
+    des_p = r.set_para("(Designation, Department)", f'({g0["desig"]}, Department of {dept})')
+    cur = des_p
+    for g in F["guides"][1:]:
+        cur = r.clone_after(name_p, g["name"].upper(), after=cur)
+        cur = r.clone_after(des_p, f'({g["desig"]}, Department of {dept})', after=cur)
+    r.set_para("COMPUTER SCIENCE ENGINEERING", F["degree"])
+    spec = r.find("with specialization in")
+    if F.get("specialization"):
+        set_text(spec, f'with specialization in {F["specialization"]}')
+    else:
+        spec.getparent().remove(spec)   # core CSE: leave the line out, never print the placeholder
+    r.set_para("DEPARTMENT OF COMPUTATIONAL", f"DEPARTMENT OF {dept.upper()}\nCOLLEGE OF ENGINEERING AND TECHNOLOGY")
+    r.set_para("MAY", F["month"])
+
+
+def declaration(r, F):
+    names, regs = zip(*F["students"])
+    r.replace("Department of Computational Intelligence", f'Department of {F["dept"]}')
+    r.fill_field("Degree/ Course", f'B.Tech, {F["degree"].title()} / {F["course"]} - Project')
+    r.fill_field("Student Name", ", ".join(names))
+    r.fill_field("Registration Number", ", ".join(regs))
+    r.fill_field("Title of Work", F["title"])
+    r.set_para("I / We hereby certify", "We hereby certify that this assessment complies with the University’s Rules and Regulations relating to Academic misconduct and plagiarism, as listed in the University Website, Regulations, and the Education Committee guidelines.")
+    r.set_para("I / We confirm", "We confirm that all the work contained in this assessment is our own except where indicated, and that we have met the following conditions:")
+    r.set_para("Given the sources", "Given the sources of all pictures, data etc. that are not our own")
+    r.set_para("Acknowledged in appropriate", "Acknowledged in appropriate places any help that we have received from others (e.g. fellow students, technicians, statisticians, external sources)")
+    r.set_para("Compiled with any other", "Complied with any other plagiarism criteria specified in the Course handbook / University website")
+    r.set_para("I understand that", "We understand that any false claim for this work will be penalized in accordance with the University policies and regulations.")
+    r.set_para("I am aware of", "We are aware of and understand the University’s policy on Academic misconduct and plagiarism and we certify that this assessment is our own work, except where indicated by referring, and that we have followed the good academic practices noted above.")
+    sign = r.set_para("<<Student 1", "x")
+    ppr = sign.find(qn("w:pPr"))
+    for x in ppr.findall(qn("w:tabs")):
+        ppr.remove(x)
+    ppr.append(parse_xml(f'<w:tabs xmlns:w="{W}"><w:tab w:val="center" w:pos="2382"/><w:tab w:val="center" w:pos="7146"/></w:tabs>'))
+    lines = [f"{n} [{g}]" for n, g in F["students"]]
+    rows = [lines[i:i + 2] for i in range(0, len(lines), 2)]
+    set_text(sign, "\t" + "\t".join(rows[0]))
+    cur = sign
+    for row in rows[1:]:
+        cur = r.clone_after(sign, " ", after=cur)
+        cur = r.clone_after(sign, " ", after=cur)
+        cur = r.clone_after(sign, "\t" + "\t".join(row), after=cur)
+
+
+def bonafide(r, F):
+    dept = F["dept"].upper()
+    all_names = ", ".join(f"{n.upper()} [{g}]" for n, g in F["students"])
+    cert = r.find("Certified that")
+    text = ptext(cert).replace("21CSP302L", F["course"])
+    text = re.sub(r"PROJECT TITLE\s*", F["title"].upper(), text)
+    text = text.replace("STUDENT1 NAME [REG NUM], STUDENT2 NAME [REG NUM]", all_names)
+    # "our" even with one guide: the guide and the HoD both sign this page.
+    text = text.replace("under my supervision", "under our supervision").replace("best of my knowledge", "best of our knowledge")
+    set_text(cert, text)
+    set_text(r.find("<<Signature"), " ")   # the line stays so the signature block keeps its place
+    tbl = r.tables_with("SIGNATURE")[0]
+    blocks = [[("SIGNATURE", True), (g["name"], False), (g.get("label", "GUIDE"), True), (g["desig"], False), ("DEPARTMENT OF", False), (dept, False)] for g in F["guides"]]
+    blocks.append([("SIGNATURE", True), (F["hod"]["name"], False), ("PROFESSOR & HEAD", True), (" ", False), ("DEPARTMENT OF", False), (dept, False)])
+    r.signature_table(tbl, blocks)
+
+
+def acknowledgements(r, F):
+    dept = F["dept"]
+    gs = F["guides"]; fa = F["faculty_advisors"]
+    r.replace("<<Name , Designation & Department>>", f'{F["hod"]["name"]}, {F["hod"]["desig"]}, Department of {dept}')
+    r.replace(f"Panel Members Department of {dept}", f"Panel Members, Department of {dept}")
+    fa_txt = fa[0] if len(fa) == 1 else ", ".join(fa[:-1]) + " and " + fa[-1]
+    r.set_para("We register our immeasurable", f'We register our immeasurable thanks to our Faculty Advisor{"s" if len(fa) > 1 else ""}, {fa_txt}, Department of {dept}, SRM Institute of Science and Technology, for leading and helping us to complete our course.')
+    gtxt = ", and ".join(f'{g["name"]}, {g["desig"]}' for g in gs)
+    r.set_para("Our inexpressible respect", f'Our inexpressible respect and thanks to our guide{"s" if len(gs) > 1 else ""}, {gtxt}, Department of {dept}, SRM Institute of Science and Technology, for providing us with an opportunity to pursue our project under {"their" if len(gs) > 1 else "this"} mentorship, and for the freedom and support to explore the research topics of our interest.')
+    r.replace("<<Dept. Name>>", dept)
+    authors = next(e for e in r.els() if ptext(e).strip() == "Authors")
+    set_text(authors, f'{F["students"][0][0]} [{F["students"][0][1]}]')
+    r.trim_blank_before(authors, keep=1)   # a longer author list would otherwise spill to a new page
+    r.start_new_page(r.find("ACKNOWLEDGEMENTS"))
+    r.tidy_paragraphs("ACKNOWLEDGEMENTS", "ABSTRACT")
+    last = next((p for p in r.all_paras() if ptext(p).rstrip().endswith("support and encouragement")), None)
+    if last is not None:   # the template forgets this full stop
+        ts = list(last.iter(qn("w:t"))); ts[-1].text = ts[-1].text.rstrip() + "."
+    ppr = authors.find(qn("w:pPr"))
+    for x in ppr.findall(qn("w:jc")) + ppr.findall(qn("w:ind")) + ppr.findall(qn("w:tabs")):
+        ppr.remove(x)
+    ppr.append(parse_xml(f'<w:jc xmlns:w="{W}" w:val="right"/>'))
+    cur = authors
+    for n, g in F["students"][1:]:
+        cur = r.clone_after(authors, f"{n} [{g}]", after=cur)
+    r.bold_names("ACKNOWLEDGEMENTS", "ABSTRACT", F.get("bold_names", []) + [F["hod"]["name"]] + fa + [g["name"] for g in gs])
+
+
+def build(template, content_path, facts_path, out):
+    F = json.load(open(facts_path, encoding="utf-8"))
+    c = json.load(open(content_path, encoding="utf-8"))
+    r = Report(template)
+    r.apply_cover_notes()   # before filling, so cloned student and guide lines inherit the right size
+    cover(r, F); declaration(r, F); bonafide(r, F); acknowledgements(r, F)
+    r.strip_notes()
+    r.cut_from(r.find("ABSTRACT"))
+    r.prepare(c["chapters"] + c.get("appendices", []), c["refs"], c.get("img_dir", "."))
+    r.begin_front(); r.number_kept_sections()
+    r.add_nodes([{"t": "front", "text": "ABSTRACT"}] + [{"t": "p", "text": a} for a in c["abstract"]])
+    r.add_toc(); r.add_list_of_figures(); r.add_list_of_tables()
+    r.add_nodes([{"t": "front", "text": "ABBREVIATIONS"}, {"t": "abbrev", "items": c["abbreviations"]}])
+    r.begin_body(); r.add_nodes(c["chapters"]); r.add_references()
+    r.add_nodes(c.get("appendices", []))
+    print(r.save(out))
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 5:
+        sys.exit(__doc__)
+    build(*sys.argv[1:5])

package/bin/srm-report.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+// Installs the srm-report skill for AI coding agents, and sends a user's improvements back as a pull request.
+const { execFileSync } = require("child_process");
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const OWNER = "shauryaaojha";
+const REPO = "srm-report";
+const PKG_ROOT = path.join(__dirname, "..");
+const SKILL_PATHS = ["SKILL.md", "references", "scripts", "assets"];
+// Global skill folders from each agent's own docs. `home` is what marks the agent as present on this machine.
+const TARGETS = [
+  { id: "agents", dir: [".agents", "skills"], reads: "Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, OpenCode, Roo Code" },
+  { id: "claude", dir: [".claude", "skills"], reads: "Claude Code", home: ".claude" },
+  { id: "antigravity", dir: [".gemini", "config", "skills"], reads: "Antigravity", home: ".gemini" },
+  { id: "cline", dir: [".cline", "skills"], reads: "Cline", home: ".cline" },
+  { id: "kiro", dir: [".kiro", "skills"], reads: "Kiro", home: ".kiro" },
+];
+const SHARED = ["codex", "cursor", "gemini", "copilot", "windsurf", "opencode", "roo"]; // all read ~/.agents/skills
+const targetDir = (t) => path.join(os.homedir(), ...t.dir, REPO);
+// Reports and templates must never travel. Only text that improves the skill goes in a pull request.
+const BLOCKED_FILE = /\.(docx?|dotx|pdf|pptx?|xlsx?|png|jpe?g|gif|zip|tgz)$/i;
+const SKIP = /(^|[\\/])(__pycache__|\.git)([\\/]|$)|\.pyc$/;
+const PERSONAL = [
+  [/\bRA\d{10,}\b/, "SRM registration number"],
+  [/[\w.+-]+@[\w-]+\.[\w.]{2,}/, "email address"],
+  [/(?<![\d.])[6-9]\d{9}(?![\d.])/, "phone number"],
+];
+
+const HELP = `srm-report: SRM report skill for AI coding agents
+
+  npx srm-report install
+      Install for every agent found on this machine. ~/.agents/skills is always included.
+
+  npx srm-report install --agent NAMES
+      Install for the named agents only, comma separated, or "all":
+      ${[...SHARED, ...TARGETS.slice(1).map((t) => t.id)].join(", ")}
+
+  npx srm-report install --dir PATH
+      Install to one folder, for any other agent. Then tell it to follow PATH/SKILL.md.
+
+      Add --force to replace an existing copy.
+
+  npx srm-report contribute [--dir PATH]
+      Dry run. Compare your copy with the version you installed and print the diff. Sends nothing.
+
+  npx srm-report contribute --yes --title "What improved" [--body "Why"] [--dir PATH]
+      Push those changes and open a pull request. Needs the GitHub CLI, signed in.
+      Run this only after the person whose machine this is has read the diff and agreed.
+`;
+
+function parse(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--yes" || a === "--force" || a === "--help") out[a.slice(2)] = true;
+    else if (a.startsWith("--")) {
+      if (i + 1 >= argv.length) die(`${a} needs a value`);
+      out[a.slice(2)] = argv[++i];
+    } else out._.push(a);
+  }
+  return out;
+}
+
+function die(msg, code = 1) {
+  console.error(`srm-report: ${msg}`);
+  process.exit(code);
+}
+
+function run(cmd, args, cwd) {
+  return execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function tryRun(cmd, args, cwd) {
+  try {
+    return run(cmd, args, cwd);
+  } catch {
+    return null;
+  }
+}
+
+function copySkill(from, to) {
+  for (const item of SKILL_PATHS) {
+    const src = path.join(from, item);
+    if (fs.existsSync(src)) fs.cpSync(src, path.join(to, item), { recursive: true, filter: (s) => !SKIP.test(s) });
+  }
+}
+
+function chooseTargets(opts) {
+  if (opts.dir) return [{ path: path.resolve(opts.dir), reads: "the agent you point at it" }];
+  let picked;
+  if (opts.agent) {
+    const names = opts.agent.toLowerCase().split(",").map((s) => s.trim()).filter(Boolean);
+    picked = names.includes("all") ? TARGETS : TARGETS.filter((t) => names.includes(t.id) || (t.id === "agents" && names.some((n) => SHARED.includes(n))));
+    const known = ["all", ...SHARED, ...TARGETS.map((t) => t.id)];
+    const bad = names.filter((n) => !known.includes(n));
+    if (bad.length || !picked.length) die(`unknown agent "${bad.join(", ") || opts.agent}". Known: ${known.join(", ")}`);
+  } else {
+    picked = TARGETS.filter((t) => !t.home || fs.existsSync(path.join(os.homedir(), t.home)));
+  }
+  return picked.map((t) => ({ path: targetDir(t), reads: t.reads }));
+}
+
+function skillHash(dir) {
+  const h = crypto.createHash("sha256");
+  const files = SKILL_PATHS.flatMap((p) => {
+    const full = path.join(dir, p);
+    if (!fs.existsSync(full)) return [];
+    return fs.statSync(full).isDirectory() ? listFiles(full).map((f) => path.join(p, f)) : [p];
+  }).sort();
+  for (const f of files) h.update(f.replace(/\\/g, "/")).update(fs.readFileSync(path.join(dir, f)));
+  return h.digest("hex");
+}
+
+function install(opts) {
+  const { version } = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+  let done = 0;
+  for (const t of chooseTargets(opts)) {
+    if (fs.existsSync(path.join(t.path, "SKILL.md")) && !opts.force) {
+      console.log(`Skipped ${t.path}: already there, and it may hold your improvements. Send them with "npx srm-report contribute", or pass --force to replace it.`);
+      continue;
+    }
+    for (const p of SKILL_PATHS) fs.rmSync(path.join(t.path, p), { recursive: true, force: true });
+    fs.mkdirSync(t.path, { recursive: true });
+    copySkill(PKG_ROOT, t.path);
+    fs.writeFileSync(path.join(t.path, "VERSION"), version + "\n");
+    fs.writeFileSync(path.join(t.path, "INSTALL_HASH"), skillHash(t.path) + "\n");
+    console.log(`Installed ${version} to ${t.path} (for ${t.reads})`);
+    done++;
+  }
+  if (done) {
+    console.log("Restart your agent so it finds the skill.");
+    console.log("If you improve it while making a report, send it back: npx srm-report contribute");
+  }
+}
+
+// With several copies installed, the one to send is the one that changed since install.
+function findCopy(opts) {
+  if (opts.dir) {
+    const d = path.resolve(opts.dir);
+    if (!fs.existsSync(path.join(d, "SKILL.md"))) die(`no skill found at ${d}`);
+    return d;
+  }
+  const copies = TARGETS.map(targetDir).filter((d) => fs.existsSync(path.join(d, "SKILL.md")));
+  if (!copies.length) die('no installed skill found. Run "npx srm-report install", or pass --dir PATH.');
+  const stored = (d) => {
+    const f = path.join(d, "INSTALL_HASH");
+    return fs.existsSync(f) ? fs.readFileSync(f, "utf8").trim() : null;
+  };
+  const changed = copies.filter((d) => skillHash(d) !== stored(d));
+  if (changed.length > 1 && new Set(changed.map(skillHash)).size > 1) {
+    die(`more than one copy has changed. Pick one with --dir, after merging what you want to keep:\n  ${changed.join("\n  ")}`);
+  }
+  return changed[0] || copies[0];
+}
+
+function listFiles(dir, base = dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (SKIP.test(p)) continue;
+    if (e.isDirectory()) listFiles(p, base, out);
+    else out.push(path.relative(base, p));
+  }
+  return out;
+}
+
+function scanAdded(diff) {
+  const hits = [];
+  for (const line of diff.split("\n")) {
+    if (!line.startsWith("+") || line.startsWith("+++")) continue;
+    for (const [rx, label] of PERSONAL) if (rx.test(line)) hits.push(`${label}: ${line.slice(1).trim().slice(0, 100)}`);
+  }
+  return hits;
+}
+
+function contribute(opts) {
+  const dir = findCopy(opts);
+  console.log(`Using the copy at ${dir}`);
+  if (tryRun("gh", ["auth", "status"]) === null) die('the GitHub CLI is missing or signed out. Install gh and run "gh auth login".');
+  if (opts.yes && !opts.title) die('--yes needs --title "what improved"');
+
+  const blocked = SKILL_PATHS.flatMap((p) => {
+    const full = path.join(dir, p);
+    if (!fs.existsSync(full)) return [];
+    return fs.statSync(full).isDirectory() ? listFiles(full).map((f) => path.join(p, f)) : [p];
+  }).filter((f) => BLOCKED_FILE.test(f));
+  if (blocked.length) die(`these files can't go in a pull request. Reports and templates stay on your machine. Move them out of the skill folder:\n  ${blocked.join("\n  ")}`, 2);
+
+  const login = run("gh", ["api", "user", "--jq", ".login"]);
+  const own = login === OWNER;
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "srm-report-"));
+  const work = path.join(tmp, REPO);
+  try {
+    if (!own) run("gh", ["repo", "fork", `${OWNER}/${REPO}`, "--clone=false"]);
+    run("gh", ["repo", "clone", `${login}/${REPO}`, work]);
+    if (!own) tryRun("git", ["fetch", "upstream", "--tags"], work);
+
+    // Start from the version that was installed, so changes made upstream since then don't look like deletions.
+    const vf = path.join(dir, "VERSION");
+    const version = fs.existsSync(vf) ? fs.readFileSync(vf, "utf8").trim() : null;
+    const tag = version ? `v${version}` : null;
+    const hasTag = tag && tryRun("git", ["rev-parse", "--verify", "--quiet", `refs/tags/${tag}`], work) !== null;
+    const branch = `improve/${(opts.title || "changes").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "changes"}-${Date.now().toString(36)}`;
+    run("git", hasTag ? ["checkout", "-b", branch, tag] : ["checkout", "-b", branch], work);
+
+    for (const p of SKILL_PATHS) fs.rmSync(path.join(work, p), { recursive: true, force: true });
+    copySkill(dir, work);
+    run("git", ["add", "-A", "--", ...SKILL_PATHS], work);
+
+    const stat = run("git", ["diff", "--cached", "--stat"], work);
+    if (!stat) {
+      console.log(`No changes: your copy matches ${hasTag ? tag : "the current skill"}.`);
+      return;
+    }
+    const diff = run("git", ["diff", "--cached", "-U2"], work);
+    const hits = scanAdded(diff);
+    if (hits.length) die(`personal details in your changes. Remove them and run this again. Nothing was sent.\n  ${hits.join("\n  ")}`, 2);
+
+    if (!opts.yes) {
+      console.log(diff);
+      console.log(`\n${stat}\n\nDRY RUN: nothing was sent. Read the whole diff, since names can't be detected automatically.`);
+      console.log('To send it, with the owner\'s agreement: npx srm-report contribute --yes --title "What improved" --body "Why"');
+      return;
+    }
+    run("git", ["commit", "-m", opts.title], work);
+    run("git", ["push", "-u", "origin", branch], work);
+    const head = own ? branch : `${login}:${branch}`;
+    const body = opts.body || `Improvements found while making a report.\n\n\`\`\`\n${stat}\n\`\`\``;
+    console.log(run("gh", ["pr", "create", "--repo", `${OWNER}/${REPO}`, "--base", "main", "--head", head, "--title", opts.title, "--body", body], work));
+  } catch (e) {
+    die(((e.stderr && e.stderr.toString()) || e.message).trim());
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+const opts = parse(process.argv.slice(2));
+const cmd = opts.help ? "help" : opts._[0] || "help";
+if (cmd === "install") install(opts);
+else if (cmd === "contribute") contribute(opts);
+else if (cmd === "help") console.log(HELP);
+else die(`unknown command "${cmd}"\n\n${HELP}`);