codecall 1.2.3 → 1.4.0

package/README.md

@@ -1,30 +1,44 @@
 # codecall
 
-[**Website**](https://codecall-theta.vercel.app/) · [npm](https://www.npmjs.com/package/codecall) · [GitHub](https://github.com/GAURAV-1313/codecall)
+`npx skills add GAURAV-1313/codecall` · Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Kiro, Copilot · no API key, nothing uploaded
 
-**codecall teaches you the code you just wrote.**
+![A codecall receipt: the change in a line, each idea marked could explain or could not, a score of 3 of 4](https://raw.githubusercontent.com/GAURAV-1313/codecall/main/docs/receipt.png)
 
-After you (or your AI coding assistant) finish building something, codecall
-turns that work into a quick, friendly quiz — so you actually understand what
-was built, not just that it works. It runs inside Codex or Claude Code, the
-AI coding tools you already use. No extra app, no signup, no API key.
+**codecall quizzes you on the code the agent just wrote.** When an
+implementation lands, it offers a four-minute session: it teaches the 2 to 4
+ideas behind the change using your actual code, checks each one with two
+questions, and ends with a one-page receipt you can keep or post. No API key,
+nothing uploaded, nothing remembered unless you keep the receipt.
 
-**Why use it?** It's easy to accept code from an AI assistant without fully
-understanding it. codecall closes that gap: right after something is built,
-it teaches you the 2–4 key ideas behind it, asks a couple of simple questions
-to check your understanding, and tells you what to double check before you
-reuse the same pattern elsewhere.
+## Install
 
-You're always in control — it only starts when you say "yes," and you can
-skip it every time if you want.
+```bash
+npx skills add GAURAV-1313/codecall
+```
 
-### What it looks like
+Then type `/codecall` (or `$codecall` in Codex) after your agent finishes
+something. You are always asked **Start Learning / Skip** first.
 
-Say your AI assistant just added login to your app. You type `$codecall` (or
-`/codecall`), and this happens:
+Want it to *offer* automatically after meaningful changes, not just when you
+ask? Install the plugin instead; it adds a small local hook that reminds the
+agent to check, and never decides for you:
 
 ```text
-You: $codecall
+/plugin marketplace add https://github.com/GAURAV-1313/codecall
+/plugin install codecall@codecall
+```
+
+(Codex: `codex plugin marketplace add https://github.com/GAURAV-1313/codecall`
+then `codex plugin add codecall@codecall`. The plugin's command is
+`/codecall:codecall` in Claude Code.) `npm install -g codecall` also works and
+installs the skill for both Codex and Claude Code.
+
+## What a session looks like
+
+Say your agent just added login to your app.
+
+```text
+You: /codecall
 
 codecall: Implementation completed.
           Learning opportunity: this adds authentication middleware and a
@@ -42,223 +56,106 @@ You: Heard of it
 
 codecall: Let's start with why every request now passes through a check
           before reaching your account routes...
-          (explains the concept in plain terms, using YOUR actual code)
+          (explains the idea in plain terms, using YOUR actual code)
 
           Quick check: if someone sends a request without logging in,
           what should happen?
-          [ multiple-choice answer ]
 
-You: (pick an answer)
+You: (answer)
 
-codecall: (tells you if you're right, and why — then moves to the next idea)
+codecall: (tells you if you're right, and why, then moves to the next idea)
 
 ...
 
-codecall: Session complete.
-          You learned: authentication middleware, token verification.
-          Remember: always check the token before touching user data.
-          Watch out for: forgetting this check on a new route you add later.
-```
-
-That's the whole product — a short, focused conversation about the code that
-was just written, grounded in what actually happened, not a generic
-tutorial.
-
-### It's not just for auth
-
-Say your assistant instead added retry logic with exponential backoff around
-a flaky payment API call. codecall would recommend a session on *why* retries
-need backoff and jitter instead of just trying again immediately, teach that
-using your actual retry code, then check whether you can spot when retrying
-is the wrong call (like after a non-idempotent request that already went
-through). Same short format — a couple of ideas, a couple of questions, a
-summary — just grounded in whatever you actually built.
-
-Or say your assistant added a database index to speed up a slow query.
-codecall would recommend a session on *why* that specific index helps — how
-the query planner uses it, which column order matters, and when an index
-actually hurts (like on a write-heavy table). It would teach that using your
-real schema and query, then check whether you can predict which future queries
-this index will and won't help. Same short format — a couple of ideas, a
-couple of questions, a summary — grounded in the change you just made.
-
-## Requirements
-
-- Codex or Claude Code, already installed.
-- No account, no signup, no API key, no internet access needed.
-
-## Install it (pick one)
-
-### If you use Codex
-
-```bash
-codex plugin marketplace add https://github.com/GAURAV-1313/codecall
-codex plugin add codecall@codecall
-```
-
-Then restart Codex (or start a new task) and type `$codecall`.
-
-### If you use Claude Code
-
-```text
-/plugin marketplace add https://github.com/GAURAV-1313/codecall
-/plugin install codecall@codecall
-/reload-plugins
-```
-
-Then type `/codecall:codecall`.
-
-### Either tool, the simple way (no plugin store)
-
-```bash
-npm install -g codecall
-```
-
-This installs it for both Codex and Claude Code at once. In Codex, type
-`$codecall`. In Claude Code, type `/codecall`.
-
-> **Note:** codecall isn't in the searchable plugin list inside Codex or
-> Claude Code yet — you have to install it with the command above, once.
-> After that it works normally every time.
->
-> **Note:** the plugin install (not the `npm install -g` path) includes a
-> small local script that reminds the agent to check whether a session is
-> worth offering, so you may see a one-time "this plugin can run code"
-> review prompt during setup. It makes no network calls — see
-> [Privacy](#privacy--the-short-version).
-
-### How do I know it worked?
-
-Type the command for whichever way you installed it. You should see
-something like this:
-
-```text
-Implementation completed.
-Learning opportunity: <a short reason>
-Estimated learning time: <a few minutes>
-
-Start Learning / Skip
+codecall: Receipt: ./codecall/0007-auth-middleware.html
+          Could explain 3 of 4. Keep it, print it, or post it.
 ```
 
-If you see that, it's working. If nothing happens, try restarting Codex or
-Claude Code — a session that was already open won't pick up a fresh install.
-
-## How to use it
-
-1. Finish some work with Codex or Claude Code, like normal.
-2. Type the command for your install (`$codecall` or `/codecall`).
-3. It asks: **Start Learning or Skip?** Nothing happens until you choose.
-4. If you start: it asks how confident you already are, then teaches one idea
-   at a time — what it is, why the code needed it, and what breaks without
-   it — followed by a quick question to check your understanding.
-5. At the end, you get a short summary: what you learned, what to remember,
-   and any gotchas to watch for if you reuse the same pattern in another
-   project.
-
-A typical session covers 2–4 ideas and takes just a few minutes.
-
-## Want it to offer to teach you automatically?
-
-If you installed the **Codex or Claude Code plugin**, this mostly just
-works already: a small local check runs after each turn and reminds the
-agent to consider offering codecall when something meaningful just
-happened — it never decides *for* you, it just makes sure the agent
-actually checks. (Only the plugin install gets this; `npm install -g`
-doesn't, since it isn't a plugin.)
-
-Either way, for the strongest guarantee — and the only option for the
-`npm install -g` path — copy one small file into your project so the agent's
-own instructions always include this check:
-
-- **Codex:** copy [this file](plugins/codecall/skills/codecall/references/AGENTS.codecall.md)
-  into your project's `AGENTS.md`.
-- **Claude Code:** copy [this file](plugins/codecall/skills/codecall/references/CLAUDE.codecall.md)
-  into your project's `CLAUDE.md`.
-
-It's selective on purpose — it only offers after real, meaningful changes
-(like a new integration, a security-related change, or an architecture
-decision), never for typo fixes, formatting, or routine changes. And it
-never teaches without you choosing Start Learning first, automatic or not.
-
-## Privacy — the short version
-
-- No API key, no account, no signup.
-- Nothing is uploaded anywhere. It uses the same AI tool and conversation you
-  already have open — there's no separate model call.
-- It doesn't remember anything between sessions or projects. It only avoids
-  repeating the same suggestion twice in one sitting.
-- The plugin install's automatic-check script runs entirely on your machine,
-  makes no network calls, and only ever adds a text reminder — it can't edit
-  files or run other commands on its own.
-- On the Claude Code plugin, some of the read-only "figure out if this is
-  worth teaching" work runs in an isolated helper (so it doesn't clutter your
-  main conversation) — it can only read files, never edit them, and it never
-  talks to you directly or teaches anything itself.
+The receipt is one screen: the change in a line, each idea marked ✅ could
+explain or ❌ could not, the score, three points to remember, and the edge
+cases to check before you reuse the pattern somewhere else.
+
+It is not just for auth. Retry logic with backoff, a new database index, a
+cache layer, a webhook handler: anything with a *why* behind it gets the same
+short format, grounded in what was actually built.
+
+## Why it exists
+
+It is easy to accept code from an AI assistant without fully understanding it.
+Reading the diff back is not the same as being asked about it. codecall asks,
+right after the change lands, while the reasons are still fresh, and leaves a
+receipt you can return to.
+
+## How the score is measured
+
+Each session covers 2 to 4 ideas. An idea counts as *could explain* when you
+answer both of its checks correctly without a reteach. The score is `N of M`
+ideas, nothing else: no time-on-task, no mastery claim, no guess at what you
+would have known anyway. Earlier receipts in `./codecall/` add a streak line
+(sessions this week, running explain rate) and nothing more.
+
+## Backend concept map
+
+For server-side changes, codecall uses a small built-in map of about 80
+backend concepts: HTTP, auth, databases, caching, queues, webhooks, real-time,
+storage, testing and delivery. It gives concepts stable names, orders them by
+what you need to know first, and supplies known misconceptions. You never see
+the map. If a change matches nothing in it, codecall works exactly as before.
+
+When you miss a mapped concept, the receipt adds one **Go deeper** line: the
+matching chapter of Sriniously's free
+[Backend from first principles](https://www.youtube.com/playlist?list=PLui3EUkuMTPgZcV0QhQrOcwMPcBCcd_Q1)
+series, plus an official reference (MDN, OWASP, PostgreSQL and similar). The
+map's wording is codecall's own and links to the videos; it does not copy
+them. codecall is not affiliated with or endorsed by the series' creator.
+
+## Privacy
+
+- No API key, no account, no signup, no network call.
+- It uses the agent and conversation you already have open. There is no
+  separate model call.
+- The receipt is the only thing it writes, into `./codecall/` in your
+  project. Delete the folder to forget every session.
+- The plugin's automatic-offer script runs entirely on your machine and only
+  ever adds a text reminder; it cannot edit files or run commands.
+- On the Claude Code plugin, the read-only planning step runs in an isolated
+  helper so it does not fill your main conversation. It can only read files
+  and never talks to you.
 
 ## Troubleshooting
 
-**I can't find it when I search inside Codex or Claude Code's plugin list.**
-That's expected for now — install it with the command above instead of
-searching for it. Once installed, it works like any other plugin.
-
-**Which command do I type?** `$codecall` in Codex. In Claude Code: `/codecall:codecall`
-if you installed the plugin, or plain `/codecall` if you used `npm install -g codecall`.
-
-**I installed it, but nothing happens.** Restart Codex/Claude Code, or start a
-new task — an already-open session won't see a fresh install.
+**Nothing happens after installing.** Restart the agent or start a new
+session; an open session does not pick up a fresh install.
 
-**Does it ever send my code anywhere?** No — see Privacy above.
+**Which command?** `/codecall` after `npx skills add` or `npm install -g`;
+`/codecall:codecall` for the Claude Code plugin; `$codecall` in Codex.
 
-**Why did installing the plugin ask me to review/trust something?** That's
-the one-time review for the small local script that powers the "offer to
-teach automatically" feature above. It's normal, runs locally, and you can
-still decline it — codecall still works, you'll just need to type the
-command yourself instead of being offered it.
-
-**What's the "helper" mentioned in Privacy — is that someone else reading my
-code?** No — it's the same AI tool you're already using, just working in an
-isolated scratch space so figuring out what's worth teaching doesn't fill up
-your main conversation. You won't see it unless you go looking; it only
-hands back a short plan.
+**The plugin asked me to trust something.** That is the one-time review for
+the small local hook behind the automatic offer. Decline it and codecall still
+works; you type the command yourself.
 
 ## For developers
 
-Want to build, test, or contribute? See [ARCHITECTURE.md](ARCHITECTURE.md)
-for the full technical design.
-
 ```bash
 npm install
 npm run build
 npm test
-```
-
-Validate the plugin before releasing:
-
-```bash
 claude plugin validate ./plugins/codecall
 ```
 
-Want codecall to show up in Codex's or Claude Code's built-in searchable
-plugin list (not just install-by-link)? That needs a separate submission to
-each company — see
-[Getting listed in curated marketplaces](#getting-listed-in-curated-marketplaces).
-
-### Getting listed in curated marketplaces
-
-**Claude Code** — submit via the
-[Plugin Directory Submission Form](https://clau.de/plugin-directory-submission).
-The plugin `name` becomes permanent once accepted.
-
-**Codex** — submit through `platform.openai.com/plugins`, which requires a
-verified OpenAI Platform identity and at least five positive and three
-negative test cases. Review is asynchronous with no fixed timeline.
+The backend concept map lives in
+`plugins/codecall/skills/codecall/references/backend-map/`, one Markdown file
+per cluster. Edit those files, then run `node scripts/backend-map.mjs` to
+validate them and regenerate `index.md`; `npm test` fails on a stale index, a
+broken prerequisite, a timestamp that is not a real chapter start, or a link
+outside the documentation allowlist.
 
-### Advanced: using it as a code library
+The canonical skill lives in `plugins/codecall/skills/codecall/`. The
+TypeScript runtime in `src/` is an offline, deterministic test harness for the
+session state machine, not the product; see [ARCHITECTURE.md](ARCHITECTURE.md).
 
-If you're building your own tool on top of codecall, the core runtime is also
-a plain TypeScript library (`import { codecall } from "codecall"`). This is a
-deterministic, offline demo/test runtime, not the AI-powered product
-experience above. See [ARCHITECTURE.md](ARCHITECTURE.md) for the API.
+Listings: Claude Code's [plugin directory submission form](https://clau.de/plugin-directory-submission);
+Codex via `platform.openai.com/plugins`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecall",
-  "version": "1.2.3",
+  "version": "1.4.0",
   "license": "MIT",
   "type": "module",
   "description": "Implementation-grounded adaptive learning skills for Codex and Claude Code.",

package/plugins/codecall/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codecall",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "Adaptive implementation-grounded learning for Claude Code.",
   "author": {
     "name": "Gaurav",
@@ -9,5 +9,9 @@
   "homepage": "https://www.npmjs.com/package/codecall",
   "repository": "https://github.com/GAURAV-1313/codecall",
   "license": "MIT",
-  "keywords": ["learning", "developer-education", "implementation"]
+  "keywords": [
+    "learning",
+    "developer-education",
+    "implementation"
+  ]
 }

package/plugins/codecall/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codecall",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "Adaptive implementation-grounded learning for Codex.",
   "author": {
     "name": "Gaurav",
@@ -9,7 +9,12 @@
   "homepage": "https://www.npmjs.com/package/codecall",
   "repository": "https://github.com/GAURAV-1313/codecall",
   "license": "MIT",
-  "keywords": ["codex", "claude-code", "learning", "developer-education"],
+  "keywords": [
+    "codex",
+    "claude-code",
+    "learning",
+    "developer-education"
+  ],
   "skills": "./skills/",
   "interface": {
     "displayName": "Codecall",
@@ -17,7 +22,11 @@
     "longDescription": "A consent-first, adaptive learning skill grounded in completed implementation work.",
     "developerName": "Gaurav",
     "category": "Productivity",
-    "capabilities": ["Interactive"],
-    "defaultPrompt": ["Teach me the implementation I just completed with Codecall."]
+    "capabilities": [
+      "Interactive"
+    ],
+    "defaultPrompt": [
+      "Teach me the implementation I just completed with Codecall."
+    ]
   }
 }

package/plugins/codecall/agents/codecall-planner.md

@@ -40,6 +40,11 @@ your starting evidence — you were not part of the conversation that built it.
    anti-patterns, architecture decisions, and misconceptions distinct. Order by
    prerequisite. Do not reduce a multi-concept implementation to one
    vocabulary item.
+5. Only when the change touches server-side code, read the codecall skill's
+   `references/backend-map/index.md` and follow the skill's "Backend concept
+   map" rule: at most one map id per concept, only when it truly fits, never
+   forced. Order with the ids' `requires`. You may grep `./codecall/*.html`
+   for `codecall-concepts` meta tags to find ids missed in earlier sessions.
 
 ## Output
 
@@ -51,7 +56,7 @@ Judgment: recommend | optional | skip
 Reason: <evidence-backed reason, citing the specific file/decision/signal>
 Estimated minutes: <N>
 Plan:
-  1. <concept> — <one-line why this matters here> [prerequisite: none|<concept>]
+  1. <concept> — <one-line why this matters here> [prerequisite: none|<concept>] [map: <id>|none]
   2. ...
 Evidence limits: <anything the given input didn't establish, if applicable>
 ```