From e967482df79ed94ea1889e16c0f74d1f35c7e691 Mon Sep 17 00:00:00 2001 From: Eras256 <219895655+Eras256@users.noreply.github.com> Date: Thu, 8 Oct 2026 20:28:31 -0600 Subject: [PATCH] chore: keep the public repo to project content; align LITEPAPER with the pitch Moves local AI-workflow files out of the public repo (playbooks/continue, images, git and .claude/commands/session-close; copies kept privately) and replaces the .gitignore block that listed internal tooling by name with a generic one. AGENTS.md keeps its rules but no longer describes internal files or where they live. LITEPAPER section 5 now matches pitch slide 08 (free reads, revenue on the issuance side) instead of the old $0.50 per checkCompliance call. M3 says issuance fee, the expired "close within two weeks" line is replaced by the Sep 30 Fuji pilot, and the multisig commitment is anchored to fee activation, since the contracts are already on Mainnet C-Chain. Audit section 5 keeps the technical finding (no missed gas optimization) and drops a funding-program aside that didn't belong in a public audit. Co-Authored-By: Claude Opus 5.5 --- .claude/commands/session-close.md | 27 ---- .gitignore | 19 +-- AGENTS.md | 75 +++-------- LITEPAPER.md | 26 ++-- SETUP.md | 6 +- .../avalanche-ecosystem-audit-2026-08-17.md | 13 +- playbooks/continue.md | 56 -------- playbooks/git.md | 127 ------------------ playbooks/images.md | 74 ---------- 9 files changed, 46 insertions(+), 377 deletions(-) delete mode 100644 .claude/commands/session-close.md delete mode 100644 playbooks/continue.md delete mode 100644 playbooks/git.md delete mode 100644 playbooks/images.md diff --git a/.claude/commands/session-close.md b/.claude/commands/session-close.md deleted file mode 100644 index 1b3623d..0000000 --- a/.claude/commands/session-close.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: session-close -description: End-of-session hygiene check — audits CLAUDE.md, AGENTS.md, SKILL.md, and the memory system for what genuinely needs updating, file by file, against each file's real purpose, not a generic "make sure it's current." ---- - -Before ending this session, audit each of the following against its own -real purpose — don't touch a file just because it's on this list, only -if something concrete actually changed today that belongs there. - -**`CLAUDE.md` / `AGENTS.md`** — only update if a hard rule that should -apply to every future session was decided or changed today. Not facts, -not project status, not history — only standing rules. Confirm -`AGENTS.md` is still imported via `@AGENTS.md` if both exist. If nothing -rule-level changed, say so explicitly instead of padding the file. - -**`.claude/skills/*/SKILL.md`** — only update if the actionable process -a skill describes changed today, not if a fact behind it changed. If a -recurring task done today doesn't have a Skill yet and clearly will -repeat, propose one — don't create it silently without flagging it. - -**The memory system** — real facts, decisions, and their reasoning from -today go here, for whatever a future session would need to know. - -Report back in this shape: CLAUDE.md/AGENTS.md — changed / not needed. -Skills — changed / new one proposed / not needed. Memory — what was -added, or "nothing new to persist." If everything reports "not needed," -that's valid — don't invent a change to have something to report. diff --git a/.gitignore b/.gitignore index d78cc46..440c823 100644 --- a/.gitignore +++ b/.gitignore @@ -82,18 +82,9 @@ KumplyMainnet.md /.windsurfrules /.agents/ -# Internal agent skills and playbooks - kept locally and in kumplyprotocol/internal (private), -# not in the public repo. Removed from tracking 30-Sep-2026; history not rewritten. -/.claude/skills/teammate-commit-identity/ -/.claude/skills/full-context-loading/ -/.claude/skills/mexico-legal-check/ -/.claude/skills/grants-track-record/ -/.claude/skills/portfolio-funding-rollup/ -/.claude/skills/hackathon-fit-check/ -/.claude/skills/doc-accuracy-audit/ -/.claude/skills/public-claim-verify/ -/.claude/skills/repo-security-sweep/ -/.claude/skills/avalanche/ -/.claude/skills/claude-antigravity-setup/ -/PLAYBOOK-claude-antigravity-setup.md +# Local agent tooling (not part of the project) +/.claude/skills/ +/.claude/commands/ +/playbooks/ +/PLAYBOOK-*.md /skills-lock.json diff --git a/AGENTS.md b/AGENTS.md index d993ab9..761025a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,10 +2,7 @@ This file carries the hard rules that apply to any AI agent working in this repo, regardless of tool (Claude Code, Antigravity, Cursor, etc.). It is -public and safe to read by anyone — internal strategy, team, and grant -context live in `CLAUDE.md` / `claude_estrategico.md` / `Memory.md`, which -are gitignored on purpose (see "Public/private boundary" below) and never -duplicated here. +public and safe to read by anyone. For architecture, contracts, and full technical detail, start with [README.md](README.md) and [LITEPAPER.md](LITEPAPER.md), not this file — @@ -13,20 +10,12 @@ this is rules, not documentation. ## Public/private boundary -`CLAUDE.md`, `claude_estrategico.md`, `Memory.md`, `.agents/`, -`.cursorrules`/`.windsurfrules`/`.clinerules`, and `docs/submissions/` are -intentionally excluded from this public repo (see `.gitignore`). They hold -internal strategy, team contacts, and grant-negotiation context; copies sync -manually to a private repo. Never move content from those files into this -one or into any other public file — if something in them needs to be public, -it gets rewritten for a public audience first (see `docs/AI-USAGE.md` and -the README's "Security & Engineering Rigor" section for the pattern already -used). - -Internal agent skills and playbooks (for example `mexico-legal-check` and -`teammate-commit-identity`) are gitignored here. Copies live in -`kumplyprotocol/internal` under `ai-rules/skills/` and `playbooks/`. Don't -add them back to this repo. +Local agent files (`CLAUDE.md`, editor rule files, root `.claude/skills/` +and `.claude/commands/`, `playbooks/`) and internal planning notes are +gitignored on purpose and kept outside this repo. Never copy content from +them into a tracked file. If something there needs to be public, rewrite it +for a public audience first (see `docs/AI-USAGE.md` and the README's +"Security & Engineering Rigor" section for the pattern already used). ## Solidity @@ -134,45 +123,19 @@ add them back to this repo. already-deployed and verified contract get reported and confirmed by a human before being applied — not applied automatically. -## Session resumption and hallucination discipline +## Accuracy -**When resuming with `claude --continue`, don't re-read what's already -in context or re-verify what's already verified this session.** Answer -directly on what's already established. Detail and why in -`playbooks/continue.md`. - -**Zero hallucination. Anything date-dependent gets verified live before -being stated, never from training memory — versions, prices, platform -rules, legal deadlines.** It's fine to say "I don't know, that needs -verifying." Every claim should trace back to something verifiable; if -not, mark it as inference. Full guidance in `playbooks/continue.md`. - -## Images and screenshots - -**Image token cost is area-based, not file-weight-based — crop to the -relevant region before pasting.** Compressing the file (JPEG/WebP) -doesn't reduce tokens and can hurt text legibility; cropping dimensions -does. Detail and verified figures in `playbooks/images.md`. - -**Batch multiple images into the same turn instead of pasting them one -at a time across separate turns.** Each new image invalidates the -prompt cache from that point forward — pasting one at a time forces -repeated cache rewrites instead of cheap reads. Detail in -`playbooks/images.md`. +- Anything date-dependent (versions, prices, platform rules, legal + deadlines) is verified live before it is stated, never from memory. + If it can't be verified, say so or mark it as inference. ## Writing PRs, issues, and comments on GitHub -**Every PR, issue, and comment published to GitHub is written humanized -and tight - no padding, no AI-writing tells (em dashes, curly quotes, -unicode ellipsis), and the Co-Authored-By disclosure stays visible, -never stripped out to look more human.** Detail in `playbooks/git.md`. - -**When the root cause is already confirmed, propose the actual fix, not -just the report.** A diff, corrected line, or exact reproduction beats -"this seems broken." Detail in `playbooks/git.md`. - -**When citing or paraphrasing another thread, re-read the actual source -today before writing the citation - the disclosure's re-verification -sentence is only added if that re-read really happened.** A short, true -disclosure beats a longer one nothing backs up. Detail in -`playbooks/git.md`. +- Tight and specific: state the finding, the evidence, and what was done. + No padding. +- The AI-assistance disclosure stays visible on every PR and comment that + had AI help. It is never removed. +- When the root cause is confirmed, include the fix (a diff or the + corrected line), not just the report. +- When citing another thread, re-read the source the same day before + quoting it. diff --git a/LITEPAPER.md b/LITEPAPER.md index 376f6ea..7a64398 100644 --- a/LITEPAPER.md +++ b/LITEPAPER.md @@ -160,16 +160,18 @@ This unlocks **agentic DeFi with safety rails**: an autonomous market-making bot ## 5. Business Model - Software-Only, B2B -KUMPLY operates as **infrastructure software**, not a financial institution. We do not custody funds, do not facilitate fiat/crypto exchange, do not issue tradable assets. Revenue comes from: +KUMPLY operates as **infrastructure software**, not a financial institution. We do not custody funds, do not facilitate fiat/crypto exchange, do not issue tradable assets. -| Stream | Customer | Pricing | Channel | +**Free reads. Verification is the product.** Integrators call `verify()` for free, with no subscription, on Fuji and Mainnet C-Chain. It is a view function that never touches the fee settings, so reads are free by contract design, not only by policy. Revenue sits on the issuance side: + +| Stream | Customer | Pricing | Status | |---|---|---|---| -| **SaaS subscription** | Regulated institutions (banks, enterprises) | MXN/USD monthly fixed (CFDI billing) | Direct sales | -| **Pay-per-use API** | DApps, autonomous agents, small teams | $0.50 USD per `checkCompliance` call, paid in AVAX | Smart contract | -| **L1 gas (KMP)** | Validators, DApps deploying on KUMPLY L1 | Native gas fees on L1 transactions | On-chain | -| **Verifier-as-a-Service** | KYC providers wanting on-chain distribution | License + revenue share | Partnership | +| **Issuance fee** | Businesses (Tier 4, KYB) and agent owners (Tier 5, KYA) | Fee per verified business or agent, paid by the owner, covering the identity-provider check and review | Planned for M3. No fee is active today | +| **Service plans** | Integrators that depend on KUMPLY in production | Optional: support and response times, priority issuance for their users, revocation alerts. Billed off-chain; nothing in the contracts gates reads | Planned | +| **L1 gas (KMP)** | DApps deploying on the KUMPLY L1 | Native gas fees on L1 transactions | Planned, after L1 activation | +| **Verifier-as-a-Service** | KYC providers wanting on-chain distribution | License + revenue share | Planned | -Pricing benchmark: traditional KYC providers (Sumsub, Onfido, Veriff) charge $1–8 per verification with no on-chain composability and no programmatic API for smart contracts. Our $0.50 per-check is a 50–94% cost reduction, plus the compliance data is reusable across every Avalanche DApp the user touches - meaning per-user lifetime cost trends toward zero as the network effect compounds. +Why issuance and not reads: the identity-provider check is the real cost, and it happens once. After that, the attestation is readable by every Avalanche DApp the user touches at no charge, so no integrator pays again for a check that was already done. ## 6. Token: KMP @@ -203,16 +205,16 @@ The weakest part of this project is unproven demand (§1.1), so closing it is th **Deliverable:** a published findings document with attributable quotes, and either (a) 2 confirmed pilot integrators - Avalanche builders or startups willing to test `ComplianceGate` or the SDK, KUMPLY's actual near-term buyer, not necessarily a regulated institution - or (b) a documented decision to re-target the ideal customer profile. Outcome (b) is a valid result, not a failure - it is cheaper to learn it in week two than in month six. Outcome (a)'s integrators are the candidates for M4's pilot integrations - the demand-validation and proof-of-concept work share one pipeline, not two. -**Status:** M0 is already producing signal, not just plans. One candidate integrator is in active conversation, with an expected close date within the next two weeks - not signed yet. A separate early conversation closed with a clear "not yet": no real funds at stake today, revisit once third parties can publish paid agents on the platform. That answer is itself real-time M0 evidence, not a setback. +**Status (October 2026):** M0 is already producing signal, not just plans. A technical pilot with an external infrastructure team ran live on Fuji on Sep 30, 2026 (gas sponsorship gated by KUMPLY attestations, details at [kumply.xyz/pitch](https://kumply.xyz/pitch)). Integration conversations continue; nothing is signed yet. A separate early conversation closed with a clear "not yet": no real funds at stake today, revisit once third parties can publish paid agents on the platform. That answer is itself real-time M0 evidence, not a setback. ## 8. Team & Traction - **Two co-founders.** Giovanny Amador - Engineering Lead: smart contracts, L1, SDK and infrastructure (authorship visible in the public commit history); also a hackathon winner outside Avalanche - ETH Uruguay 2025, 1st place at ETH Mexico Monterrey (Creator Economies track), 3rd place Arbitrum Innovation track. Monserrat Mendoza - Dev Lead: frontend UX/UI and backend developer; also a hackathon winner outside Avalanche - ETH Uruguay 2025. Both are Team1 Network Collaborators (accepted July 2026). - **Bus factor.** Most shipped code still runs through one founder today (Giovanny - every commit attributable to him, verifiable in the repo's public history). Monse has now shipped a real fix here too (commit `49177e0`, address validation before `readContract`) - a second contributor is real, just not yet at parity. - **Code:** monorepo with pnpm workspaces - contracts, SDK, API, web - full test suite (contracts, SDK, API), CI on every push (GitHub Actions, 4 parallel jobs). -- **Go-to-market:** targeting Mexican digital banks, venture funds and LatAm enterprises. No commercial agreements are signed to date; any partner will be named only once a relationship is formalized. +- **Go-to-market:** targeting Mexican digital banks, venture funds and LatAm enterprises. No commercial agreements are signed to date; a partner is named only with their written permission. - **Open source:** Apache 2.0 licensed (express patent grant, no trademark license), public GitHub, no proprietary lock-in. -- **Public commitment:** all smart contracts will be immutably renounced to a 3-of-5 multisig before mainnet; KMP mainnet genesis defined by community governance; quarterly treasury transparency reports starting Q4 2026. +- **Public commitment:** admin roles on the deployed contracts move to a 3-of-5 multisig before any fee is activated on Mainnet C-Chain (part of M3's cold-key treasury); KMP mainnet genesis defined by community governance; quarterly treasury transparency reports starting Q4 2026. ## 9. Grant Programs & Funding Asks @@ -220,11 +222,11 @@ We are applying to: | Program | Amount | Use of funds | |---|---|---| -| **Team1 Mini-Grant** | $10,000 USD, modular | Five milestones, fundable in tranches: **M0 ($0)** demand validation - 5 structured interviews with published findings, runs regardless of funding and is not a disbursement gate (§7.1) · **M1 ($2,000)** security hardening of `AttestationStore` + `ComplianceGate` (Slither, Aderyn, fuzzing, threat model) plus failure detection and alerting on the issuance path · **M2 ($3,000)** Mexican legal entity incorporated (a hard prerequisite for Sumsub's production tier), Sumsub production activated, first real KYC on-chain - includes a ring-fenced reserve against the pending Enterprise quote for Tier-4 KYB · **M3 ($2,000)** on-chain query-fee activation on Mainnet C-Chain, written Mexican fintech legal opinion, IMPI trademark, cold-key treasury · **M4 ($3,000)** Fuji L1 validator activation, ICM integration, 2 integration pilots. $5,000 funds M1–M2; $7,000 adds M3; $10,000 completes M4. Excludes formal L1 audit. Full itemisation at [kumply.xyz/pitch](https://kumply.xyz/pitch). | +| **Team1 Mini-Grant** | $10,000 USD, modular | Five milestones, fundable in tranches: **M0 ($0)** demand validation - 5 structured interviews with published findings, runs regardless of funding and is not a disbursement gate (§7.1) · **M1 ($2,000)** security hardening of `AttestationStore` + `ComplianceGate` (Slither, Aderyn, fuzzing, threat model) plus failure detection and alerting on the issuance path · **M2 ($3,000)** Mexican legal entity incorporated (a hard prerequisite for Sumsub's production tier), Sumsub production activated, first real KYC on-chain - includes a ring-fenced reserve against the pending Enterprise quote for Tier-4 KYB · **M3 ($2,000)** issuance fee activation on Mainnet C-Chain (reads stay free), written Mexican fintech legal opinion, IMPI trademark, cold-key treasury · **M4 ($3,000)** Fuji L1 validator activation, ICM integration, 2 integration pilots. $5,000 funds M1–M2; $7,000 adds M3; $10,000 completes M4. Excludes formal L1 audit. Full itemisation at [kumply.xyz/pitch](https://kumply.xyz/pitch). | | **Avalanche Retro9000** (C-Chain, future round) | Retroactive | Bringing KUMPLY to mainnet as compliance infrastructure: institutional validator-set bootstrap and formal smart-contract audit | | **Blizzard Fund** | Seed round, terms TBD | Operating runway 12 months (legal, audits, BD) and engineering hires | -Capital efficiency is core: at $0.50 per-check pricing, breakeven on operating costs is reached at ~50K monthly verifications - a single mid-size LatAm enterprise customer. +Capital efficiency is core: reads are view calls that any Avalanche RPC serves, so KUMPLY's operating cost scales with issuance, which is also where revenue sits. ## 10. Why We Win diff --git a/SETUP.md b/SETUP.md index 8630991..7a6c9e2 100644 --- a/SETUP.md +++ b/SETUP.md @@ -30,9 +30,9 @@ cd .. ``` Both `.claude/skills/avalanche-skills/` and `.reference/` are gitignored (see `.gitignore`, -"Avalanche reference tooling" section). The gitignore entry is scoped specifically to -`avalanche-skills/`, not all of `.claude/skills/`, so it never hides any of KUMPLY's own skills -if some get added there later. +"Avalanche reference tooling" section). Everything under the root `.claude/skills/` is local +tooling and stays out of the repo. KUMPLY's own project skill, `run-web`, lives under +`apps/web/.claude/skills/` and is tracked. None of this is committed to the public repo, under any circumstance: - `avalanche-starter-kit` ships with no `LICENSE` file at all. diff --git a/docs/audits/avalanche-ecosystem-audit-2026-08-17.md b/docs/audits/avalanche-ecosystem-audit-2026-08-17.md index 77b5b12..cb684ab 100644 --- a/docs/audits/avalanche-ecosystem-audit-2026-08-17.md +++ b/docs/audits/avalanche-ecosystem-audit-2026-08-17.md @@ -157,19 +157,16 @@ Reporting this plainly rather than inventing an item to fill the category. ## Add - flagged, not applied -### 5. Gas optimization vs Retro9000 +### 5. Gas optimization `skills/gas` and `skills/precompiles` list standard storage-packing, calldata, and unchecked-loop optimizations. AttestationStore, ComplianceGate, and KumplyValidatorSetManager already follow the main patterns those skills recommend: custom errors instead of require strings, calldata for external function inputs, events over storage-based history, checked arithmetic outside of -explicitly bounded loops. No unsafe or clearly-missed optimization was found. +explicitly bounded loops. No unsafe or clearly-missed optimization was found, so no gas changes +were made in this pass. -Flagging the tension explicitly, as asked: KUMPLY intends to apply to Retro9000, which rewards -AVAX burned via gas on Mainnet C-Chain. Reducing gas per call directly reduces that metric. Any -future gas optimization pass on these contracts should be a deliberate business decision made -with that trade-off in view, not a default "smaller is better" pass. Not applying anything gas -related here for that reason, beyond what was already true before this audit. +*(Section 5 edited 8 Oct 2026 for scope: it now records only the technical finding.)* ### 6. ReentrancyGuard on AttestationStore.withdrawFees @@ -245,7 +242,7 @@ https://github.com/Ayomisco/avaxskills/issues/2 | 2 | Fix | contracts/contracts/KumplyValidatorSetManager.sol | Medium | Fixed in same redeploy | | 3 | Fix | apps/web/src/app/api/webhook/route.ts, apps/api/src/index.ts | Medium | Fixed | | 4 | Improve | contracts/scripts/verify-contracts.ts | N/A | Applied | -| 5 | Add | gas optimization | N/A | Flagged, not applied (Retro9000 trade-off) | +| 5 | Add | gas optimization | N/A | Reviewed, no missed optimization found | | 6 | Add | contracts/contracts/AttestationStore.sol | Low | Reported, needs confirmation | | 7 | External (upstream) | AVAXSKILLS skills/precompiles | N/A | Filed, avaxskills#3, open | | 8 | External (upstream) | AVAXSKILLS skills/validator-management | N/A | Filed as comment on avaxskills#2, open | diff --git a/playbooks/continue.md b/playbooks/continue.md deleted file mode 100644 index 97f2da2..0000000 --- a/playbooks/continue.md +++ /dev/null @@ -1,56 +0,0 @@ -# continue.md — resume a session without wasting extra tokens - -## What `claude --continue` (or `-c`) actually does - -Confirmed, can't be changed from a project file: `--continue` reloads -the full conversation — every prompt, every file change, every -decision — by design, not a light summary. It loads the most recent -conversation in the current folder, no ID needed. If you genuinely want -something lighter than a full reload, use `/recap` *inside* an already- -open session instead of reopening with `--continue` — it gives a -summary of where things stand without replaying the full history. - -## The real rule for not wasting tokens on resume - -The saving isn't in avoiding the reload — it's in what the session does -with the context it already has: - -- Don't re-read a file that's already in the loaded context. -- Don't re-verify a fact that was already verified with a source this - session, unless real time has passed or it's the kind of fact that - changes fast. -- Answer directly on what's already established, instead of - summarizing the whole history before acting. - -## The zero-hallucination, fresh-information rule - -Based on Anthropic's own guidance for reducing hallucinations: - -- It's fine to say "I don't know" or "that needs verifying" — explicit - permission to admit uncertainty measurably reduces false information. -- Anything date-dependent (versions, prices, platform rules, legal - deadlines) gets verified live before being stated, never from - training memory. -- Every claim should trace back to something verifiable — a citation, a - link, a hash, a test. If it can't, mark it as inference. -- If something can't be confirmed, retract it instead of defending it - just because it was already said. - -## Installing this in a new project — two steps, not one - -This file alone does nothing — nothing loads it automatically. Copy it -to `playbooks/continue.md` (or wherever this project keeps playbooks), -then add this to the end of `AGENTS.md`: - -``` -**When resuming with `claude --continue`, don't re-read what's already -in context or re-verify what's already verified this session.** Answer -directly on what's already established. Detail and why in -`playbooks/continue.md`. - -**Zero hallucination. Anything date-dependent gets verified live before -being stated, never from training memory — versions, prices, platform -rules, legal deadlines.** It's fine to say "I don't know, that needs -verifying." Every claim should trace back to something verifiable; if -not, mark it as inference. Full guidance in `playbooks/continue.md`. -``` diff --git a/playbooks/git.md b/playbooks/git.md deleted file mode 100644 index 7d030a0..0000000 --- a/playbooks/git.md +++ /dev/null @@ -1,127 +0,0 @@ -# git.md - how PRs, issues, and comments get written on GitHub - -## Scope - -Anything published to GitHub from this workspace - a PR description, an -issue report (own repo or upstream), or a comment on either. Commit -message conventions (the `Co-Authored-By` trailer itself) already live in -`AGENTS.md`'s Commits section; this file covers the surface a human -actually reads: PR/issue bodies and comments, where the writing quality -is what gets a maintainer to act instead of skim past. - -## Humanized, not verbose - -Write like a person reporting something they actually found, not like a -template being filled in. Concretely: - -- No em dashes, no curly quotes, no unicode ellipsis. Plain hyphens, - straight quotes, `...` if truly needed. -- No filler openers ("I wanted to reach out about...", "Upon further - investigation..."). Start with the finding. -- One clear claim per paragraph. If a reproduction needs five commands, - show five commands in a code block, don't narrate them in prose. -- Say what you checked and what you didn't, in one line, not a - disclaimer paragraph. "Checked X against Y; didn't check Z" beats - hedging every sentence. - -This is the same discipline already applied to the AVAXSKILLS issues -filed from this workspace (#2, #3, #4 at Ayomisco/avaxskills): a title -that states the bug, a reproduction anyone can run, and a suggested fix -- no preamble, no "hope this helps" close. - -## Co-authorship stays visible, never stripped for polish - -Every AI-assisted commit already carries `Co-Authored-By: Claude Sonnet 5 -` (or the equivalent model), per `AGENTS.md`. When -that commit becomes part of a PR, the trailer rides along in the commit -history whether or not the PR description repeats it - never rewrite -history (`git commit --amend`, a squash that drops the trailer) just to -make the PR read as fully human-authored. If an issue or comment was -drafted with AI assistance and isn't just relaying a commit, say so -plainly rather than let it pass as unassisted. Matches the disclosure -already public in `docs/AI-USAGE.md`: the point isn't to hide the -tooling, it's to make the finding itself hold up on its own regardless -of who or what found it. - -## Re-read before quoting another thread - -When a PR, issue, or comment cites or paraphrases something from another -thread, the order of operations matters: - -1. Re-read the actual source today, before writing the citation - never - quote from what this session already read earlier. -2. Only then, and only if the source really was re-read, does the - disclosure get a second sentence: - -``` -Disclosure: drafted with AI assistance under my direction and reviewed -by hand. Both quotations above were re-verified against the linked -comments today. -``` - -Adjust "Both" / "the" to the actual number of quotes. - -That second sentence is the consequence of re-reading, not a template -pasted first and justified after the fact. If there wasn't time to -re-read the source before publishing, leave the sentence out - a short, -true disclosure beats a longer one nothing backs up. A specific claim -that turns out false is worse than a vague one nobody ever checks, -because now there's something concrete to contradict if someone -verifies it. - -Applies to new comments going forward, not a retroactive fix for -anything already published. - -## Propose the fix, not just the report - when the root cause is confirmed - -If the investigation already nailed the root cause, the issue includes -the fix, not just the symptom. Two real precedents from this workspace: - -- The AVAXSKILLS issues each closed with a "Suggested fix" line stating - the exact correction (e.g. `txAllowListConfig` instead of - `transactionAllowListConfig`), not just "this key looks wrong." -- The `icm-contracts` CONTRIBUTING.md typo was prepared as an actual diff - on a fork branch before anything was reported - the report and the fix - were the same action, not two separate steps. - -When the cause isn't confirmed yet - a hunch, a symptom without a -traced-through explanation - say that explicitly instead of guessing at -a fix. A wrong proposed fix is worse than no proposed fix; an honest "I -found X, haven't traced the cause yet" is a valid report on its own. - -## Before publishing, check - -1. Title states the bug/change, not a vague category ("bug in X" is - worse than "X returns wrong value when Y"). -2. Reproduction steps are copy-pasteable, not paraphrased. -3. If the root cause is confirmed: a fix is proposed, ideally as a diff - or the exact corrected value/line. -4. No em dash, curly quote, or unicode ellipsis anywhere in the text. -5. If AI assisted the finding or the writeup, that's not hidden. -6. If citing or paraphrasing another thread: the source was re-read - today, and the disclosure's re-verification sentence appears only if - that's actually true. -7. Read it once as the maintainer who'll see it cold - does it explain - itself without needing the conversation that produced it? - -## Installing this in a new project - two steps, not one - -This file alone does nothing - nothing loads it automatically. Copy it -to `playbooks/git.md`, then add this to the end of `AGENTS.md`: - -``` -**Every PR, issue, and comment published to GitHub is written humanized -and tight - no padding, no AI-writing tells (em dashes, curly quotes, -unicode ellipsis), and the Co-Authored-By disclosure stays visible, -never stripped out to look more human.** Detail in `playbooks/git.md`. - -**When the root cause is already confirmed, propose the actual fix, not -just the report.** A diff, corrected line, or exact reproduction beats -"this seems broken." Detail in `playbooks/git.md`. - -**When citing or paraphrasing another thread, re-read the actual source -today before writing the citation - the disclosure's re-verification -sentence is only added if that re-read really happened.** A short, true -disclosure beats a longer one nothing backs up. Detail in -`playbooks/git.md`. -``` diff --git a/playbooks/images.md b/playbooks/images.md deleted file mode 100644 index ac1aafa..0000000 --- a/playbooks/images.md +++ /dev/null @@ -1,74 +0,0 @@ -# images.md — paste images, screenshots and links without wasting tokens - -## What actually costs tokens - -Confirmed against `platform.claude.com/docs/en/build-with-claude/vision`: -Claude sees images in 28×28-pixel patches, not file weight. The formula -is `tokens = ⌈width / 28⌉ × ⌈height / 28⌉`. Cropping cuts tokens -proportional to the area removed — compressing the file (JPEG/WebP) -does not reduce tokens at all, and heavy compression can hurt text -legibility, which the official docs flag as a real risk, not just a -non-benefit. - -Each model has a native resolution ceiling. Claude 4.7+ models (high- -resolution tier) cap at 2576px long edge / 4784 visual tokens; all other -models (standard tier) cap at 1568px / 1568 tokens. A full 1920x1080 -screenshot costs 2691 tokens uncropped on the high-resolution tier, -versus 1560 on standard (auto-downscaled to 1456x819). Claude does not -read image metadata (EXIF, GPS) — stripping it does not save tokens. - -## Request limits - -20 images per turn on claude.ai; 100 per API request for 200k-context -models, 600 for others; 8000x8000px max dimension; 10MB max size -(base64) on the direct API and claude.ai, 5MB on Bedrock/Google Cloud; -JPEG, PNG, GIF (first frame only), WebP supported. - -## Why batching beats pasting one at a time - -Confirmed against `platform.claude.com/docs/en/build-with-claude/prompt-caching`: -images can be cached like text blocks, but adding or removing an image -anywhere in the prompt invalidates the message cache from that point -forward. A cache read costs ~10% of base price; a fresh cache write -costs 125% (5-min TTL) or 200% (1-hour TTL). Pasting five related -screenshots across five separate turns forces five full cache rewrites; -pasting them together in one message pays for one. - -## Pasting in Claude Code - -Confirmed against `code.claude.com/docs/en/common-workflows`: drag-and- -drop, Ctrl+V (Cmd+V also works in macOS iTerm2), or a direct file path. -No Claude-Code-specific size limit lower than the general API limits is -stated on that page — don't repeat third-party figures (e.g. a "5MB -Claude Code limit") as confirmed fact without a citation. - -## Checklist before pasting - -1. Crop to the relevant region instead of the full screen — the highest- - impact technique, free, no tooling needed. -2. Don't over-compress dense text (terminal, code, dashboards) — the - official docs warn this can make text illegible, which hurts analysis - quality more than the tokens saved are worth. -3. Batch related screenshots into one message instead of separate turns. -4. If the content already exists as text in the repo, reference the file - directly instead of screenshotting it. -5. For links and research, paste the URL and let WebFetch/WebSearch pull - it as clean text instead of screenshotting a browser tab. - -## Installing this in a new project — two steps, not one - -Copy this file to `playbooks/images.md`, then add this to the end of -`AGENTS.md`: - -``` -**Image token cost is area-based, not file-weight-based — crop to the -relevant region before pasting.** Compressing the file (JPEG/WebP) -doesn't reduce tokens and can hurt text legibility; cropping dimensions -does. Detail and verified figures in `playbooks/images.md`. - -**Batch multiple images into the same turn instead of pasting them one -at a time across separate turns.** Each new image invalidates the -prompt cache from that point forward — pasting one at a time forces -repeated cache rewrites instead of cheap reads. Detail in -`playbooks/images.md`. -```