@kitkat-vn/kitcode 0.2.0-staging.9 → 0.3.0-staging.15

package/src/cycle-receipt.mjs

@@ -0,0 +1,97 @@
+import crypto from 'node:crypto';
+
+// A cycle receipt (docs/backend.md, "The cycle receipt"; the plan of 2026-10-21, phase 2): what the claim backend signs once it
+// has issued a voucher, and the dashboard hands to this tracker, so that the tracker begins the next cycle, whose milestones
+// count fresh from that moment (decision 1). Its words are the server's: the install id the claim's bundle carried, the cycle
+// the server counted for it, the claim's id and when its voucher was issued, signed with an Ed25519 key that exists on the
+// claim backend's server alone. This file only reads one, with the matching public key, which a tester build carries
+// (integration-spec.mjs, CYCLE_RECEIPT_PUBLIC_KEY). Pure: it reads no file, keeps nothing, and asks nothing of the network;
+// whether the receipt is this install's, and of the cycle it is in, is the caller's to judge, against the record
+// (milestones-reached.mjs, beginNextCycle).
+//
+//   <payload>.<signature>
+//
+// `payload` is base64url (no padding) of the UTF-8 JSON {"v":1,"installId":…,"cycle":…,"claimId":…,"issuedAt":…}, those five
+// fields alone; `signature`, base64url of the 64-byte Ed25519 signature of the ASCII text `kitcode-cycle-receipt-1.` followed
+// by `payload` as it stands. The signature is checked over the bytes as they came, before anything in them is read: nothing is
+// put in a canonical form, and no field the server did not sign is read. The text names what it is, so that the key signs
+// nothing else that could pass for one. The server's side is apps/api/src/cycle-receipts.ts.
+
+export const CYCLE_RECEIPT_CONTEXT = 'kitcode-cycle-receipt-1.';
+
+// The longest text read: a receipt is about 300 characters.
+export const MAX_CYCLE_RECEIPT_LENGTH = 1024;
+
+const RECEIPT_TEXT = /^([A-Za-z0-9_-]{16,900})\.([A-Za-z0-9_-]{86})$/u;
+const PUBLIC_KEY_TEXT = /^[A-Za-z0-9_-]{43}$/u;
+const INSTALL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const CLAIM_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+const PAYLOAD_KEYS = ['v', 'installId', 'cycle', 'claimId', 'issuedAt'];
+
+function isInstant(value) {
+  if (typeof value !== 'string' || !INSTANT.test(value)) {
+    return false;
+  }
+
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString() === value;
+}
+
+// The public key a build carries: base64url of its 32 raw bytes, the JWK's `x`. Null when it is not one.
+export function cycleReceiptKey(text) {
+  if (typeof text !== 'string' || !PUBLIC_KEY_TEXT.test(text)) {
+    return null;
+  }
+
+  try {
+    const key = crypto.createPublicKey({key: {kty: 'OKP', crv: 'Ed25519', x: text}, format: 'jwk'});
+    return key.asymmetricKeyType === 'ed25519' && key.export({format: 'jwk'}).x === text ? key : null;
+  } catch {
+    return null;
+  }
+}
+
+// Reads `text` with `publicKey` (a KeyObject, cycleReceiptKey's): {ok: true, receipt: {installId, cycle, claimId, issuedAt}},
+// or {ok: false, problem}: 'unreadable', not the shape of a receipt, or its signed words not a receipt's; 'signature', not
+// signed with the key's pair.
+export function readCycleReceipt(text, publicKey) {
+  const parts = typeof text === 'string' && text.length <= MAX_CYCLE_RECEIPT_LENGTH ? RECEIPT_TEXT.exec(text) : null;
+
+  if (parts === null) {
+    return {ok: false, problem: 'unreadable'};
+  }
+
+  const [, payload, signature] = parts;
+  let signed;
+
+  try {
+    signed = crypto.verify(null, Buffer.from(`${CYCLE_RECEIPT_CONTEXT}${payload}`, 'ascii'), publicKey, Buffer.from(signature, 'base64url'));
+  } catch {
+    signed = false;
+  }
+
+  if (!signed) {
+    return {ok: false, problem: 'signature'};
+  }
+
+  let words;
+
+  try {
+    words = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+  } catch {
+    return {ok: false, problem: 'unreadable'};
+  }
+
+  const shaped = words !== null && typeof words === 'object' && !Array.isArray(words)
+    && Object.keys(words).length === PAYLOAD_KEYS.length && PAYLOAD_KEYS.every((key) => Object.hasOwn(words, key))
+    && words.v === 1
+    && typeof words.installId === 'string' && INSTALL_ID.test(words.installId)
+    && Number.isSafeInteger(words.cycle) && words.cycle >= 1
+    && typeof words.claimId === 'string' && CLAIM_ID.test(words.claimId)
+    && isInstant(words.issuedAt);
+
+  return shaped
+    ? {ok: true, receipt: {installId: words.installId, cycle: words.cycle, claimId: words.claimId, issuedAt: words.issuedAt}}
+    : {ok: false, problem: 'unreadable'};
+}

package/src/fonts/jetbrains-mono/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/hook-prompt.mjs

@@ -104,11 +104,21 @@ function notify(title, message) {
 // A milestone reached is said in neutral words (the operator's decisions 5 and 6 of 2026-10-01): its message, from the
 // campaign, is on the dashboard, and no milestone is a reward ready, or a code. Until then this said "Reward ready at",
 // and the announcement below "KitCode break code ready".
+//
+// Since 2026-10-22 (rewards/3-repeat-vouchers, phase 2) the milestones are those of the cycle counted in (reward.mjs): from cycle
+// 2 on the context names it, "KitCode progress (cycle 2): …", and the milestones it lists and announces are that cycle's; the =
+// and the time are the totals, which keep counting. Cycle 1 reads as it always has. The cycle is the record's, read with the
+// rest of the file: no receipt is checked here (hard rule 7).
+function cycleOf(reward) {
+  return Number.isSafeInteger(reward?.cycle) && reward.cycle > 1 ? reward.cycle : null;
+}
+
 function progressContextFor(reward) {
   const nextBreak = reward.nextBreak ?? nextBreakReminder(reward);
   const ready = reward.milestones.filter((entry) => entry.status === 'ready' && !entry.redeemed);
+  const cycle = cycleOf(reward);
   const parts = [
-    `KitCode progress: ${reward.totalEquals} = counted, ${formatBreakDuration(reward.earnedSeconds)} active.`,
+    `KitCode progress${cycle === null ? '' : ` (cycle ${cycle})`}: ${reward.totalEquals} = counted, ${formatBreakDuration(reward.earnedSeconds)} active.`,
   ];
 
   if (ready.length > 0) {
@@ -140,7 +150,8 @@ function hookOutputFor({tiers = [], reward = null}) {
     };
   }
 
-  const labels = tiers.map((tier) => `${tier.percent}%`).join(', ');
+  const cycle = cycleOf(reward);
+  const labels = `${tiers.map((tier) => `${tier.percent}%`).join(', ')}${cycle === null ? '' : `, cycle ${cycle}`}`;
   const command = 'kitcode dashboard';
   const additionalContext = [
     progressContext,
@@ -206,7 +217,8 @@ export async function runPromptHook({source}) {
     }
 
     const label = announced.map((tier) => `${tier.percent}%`).join(', ');
-    notify('KitCode milestone reached', `Milestone ${label} unlocked. Open kitcode dashboard.`);
+    const cycle = cycleOf(reward);
+    notify('KitCode milestone reached', `Milestone ${label}${cycle === null ? '' : ` of cycle ${cycle}`} unlocked. Open kitcode dashboard.`);
     process.stdout.write(`${JSON.stringify(hookOutputFor({tiers: announced, reward}))}\n`);
   } catch (error) {
     failure = error;

package/src/integration-spec.mjs

@@ -1,15 +1,45 @@
-export const CLI_PACKAGE_NAME = '@kitkat-vn/kitcode';
+// The CLI's own package.json, for its name and its version, which live there alone (hard rule 6). Since 2026-10-22
+// (production/1-cli) the production setup prompt installs this version by number, and the dashboard, which bundles this file,
+// takes both from here: a JSON module, which Node loads without a warning from 22.12.0, the engines floor, and of which Vite
+// bundles only the two fields read. Until then this file imported nothing.
+import cliPackage from '../package.json' with {type: 'json'};
+
+// Since 2026-10-22 (production/1-cli; the operator's two names of 2026-10-02, and Q5 and Q7 of the plan of 2026-10-22) the
+// package is production's, `@kitkatvn/kitcode`, at 0.2.0: package.json's name and version. A tester build's copy names the
+// staging package there instead (scripts/tester-build.mjs), and so here. Until then `@kitkat-vn/kitcode`, written here.
+export const CLI_PACKAGE_NAME = cliPackage.name;
+export const CLI_VERSION = cliPackage.version;
 export const CLI_PACKAGE_COMMAND = `npx ${CLI_PACKAGE_NAME}`;
 export const CLI_GLOBAL_INSTALL_COMMAND = `npm install -g ${CLI_PACKAGE_NAME}`;
-// A staging round's tester build, published under npm's `staging` tag: since 2026-10-02 the only way a tester installs it
-// (stagingSetupPromptFor, below).
-export const CLI_STAGING_INSTALL_COMMAND = `${CLI_GLOBAL_INSTALL_COMMAND}@staging`;
+// What the production setup prompt installs: this version, by number, so that the dashboard and the CLI it installs are one
+// commit's. A newer version on npm reaches the prompt only with a deploy of the dashboard built from its commit.
+export const CLI_PINNED_INSTALL_COMMAND = `${CLI_GLOBAL_INSTALL_COMMAND}@${CLI_VERSION}`;
+// The staging package, which every tester build is published as, under npm's `staging` tag: since 2026-10-02 the only way a
+// tester installs one (stagingSetupPromptFor, below). It installs the same `kitcode` command as the production package, so npm
+// refuses to install either over the other: each prompt removes the other package first.
+export const CLI_STAGING_PACKAGE_NAME = '@kitkat-vn/kitcode';
+export const CLI_STAGING_INSTALL_COMMAND = `npm install -g ${CLI_STAGING_PACKAGE_NAME}@staging`;
+// The package's previous name, under which 0.1.39 was published on 2026-08-06 and is still npm's `latest` (docs/project-overview.md,
+// "Current state"). It installs the same `kitcode` command too, so since 2026-10-22 (production/1-cli) each prompt removes it
+// first, in the same command as the other channel's package.
+export const CLI_PREVIOUS_PACKAGE_NAME = '@onedigitas/kitcode';
 export const CLI_GLOBAL_COMMAND = 'kitcode';
+// Production's dashboard since 2026-10-22 (production/1-cli): what `kitcode dashboard` opens, and the origin every tracker
+// `kitcode track` starts allows (src/cors.mjs, bin/kitcode.mjs). A tester build's copy names the staging site here. Until then
+// https://kitcode.vercel.app/, the previous project's site, which is not ours.
 export const DASHBOARD_URL = "https://staging.kitcode.vn/";
 // Where a tester build sends KitCode's own diagnostics (src/diagnostics.mjs; docs/backend.md, "Tester diagnostics"): the
 // staging dashboard's /v1/diagnostics, which scripts/tester-build.mjs alone writes here, as it writes DASHBOARD_URL. null in
 // the repository, and so in every release of it: such a CLI collects, writes and sends no diagnostics at all.
 export const DIAGNOSTICS_URL = "https://staging.kitcode.vn/v1/diagnostics";
+// The claim backend's public key for cycle receipts (src/cycle-receipt.mjs; docs/backend.md, "The cycle receipt"): base64url of
+// the 32 raw bytes of the Ed25519 key whose private half exists on the claim backend's server alone. The tracker begins a
+// cycle only on a receipt it signed (api.mjs, POST /api/claim/receipt). Public, as the repository is, and written here by
+// scripts/tester-build.mjs, from the key the staging server printed (deploy/staging/cycle-receipt.pub), as it writes
+// DIAGNOSTICS_URL; and since 2026-10-22 (production/1-cli) by scripts/release.mjs in a production release's copy, from the key
+// the production server printed (deploy/production/cycle-receipt.pub). null in the repository: a CLI run from it takes no
+// receipt, and never begins a second cycle.
+export const CYCLE_RECEIPT_PUBLIC_KEY = "QsSBNGXhReBhjz0qk32fFLYiVCDtqKEGQwFB30LflTw";
 export const LOCAL_SERVER_URL = 'http://127.0.0.1:4747';
 export const STATE_DISPLAY_PATH = '~/.kitcode/state.json';
 export const RUNNER_PATH_PARTS = ['.kitcode', 'bin', 'kitcode'];
@@ -17,18 +47,61 @@ export const RUNNER_DISPLAY_PATH = `~/${RUNNER_PATH_PARTS.join('/')}`;
 
 // The milestones and the = each needs (docs/reward-rules.md §2). Until 2026-10-01 each had a break code, one fixed line of
 // code shown to everyone; the operator's decision 6 of that day replaced them with a message the claim backend's
-// settings give each milestone, which the dashboard shows. The 10–30 % tiers still hold a record each in the state file:
-// the hook's announcements, and a code shown before then.
-export const KITCODE_REWARD_TIERS = [
-  {percent: 10, requiredEquals: 3},
-  {percent: 20, requiredEquals: 6},
-  {percent: 30, requiredEquals: 9},
-];
-
-export const KITCODE_DISPLAY_MILESTONES = [
-  {percent: 50, requiredEquals: 12, displayOnly: true},
-  {percent: 100, requiredEquals: 15, displayOnly: true},
-];
+// settings give each milestone, which the dashboard shows. A tier holds a record in the state file: the hook's
+// announcements, and a code shown before then.
+//
+// Since 2026-10-08 (rewards/1-milestones-bar; the operator: "change milestone to: 30% - 50% - 100%") the milestones are
+// 30, 50 and 100 %, each with the targets it had: 30 % the one tier, 50 and 100 % shown and never announced, as before.
+// Until then 10 % (3 =, 6 min) and 20 % (6 =, 12 min) were tiers too. A record an earlier version kept of either, an
+// announcement, a code shown or the time it was reached, stays in the file as it is, and nothing reads it.
+//
+// Since 2026-10-20 (rewards/2-no-stack; the plan of that day, decisions 1 and 4) each milestone's targets, its focus time
+// and its =, are counted fresh from the moment the milestone before it was reached, the first's from install, and each
+// milestone names its own focus time, where 3600 s × its percent was the time target until then (reward.mjs). Two tables,
+// both public: the tester table, the short one, which every build of this repository and every tester build counts by,
+// its numbers the ones the milestones had; and the production table, whose numbers are DRAFTS until the client gives the
+// campaign's length: 3 h and 300 =, 5 h and 500 =, 10 h and 1,000 =, so 18 h and 1,800 = in all to reach 100 %.
+// MILESTONE_TABLE names the one in force: 'tester' here, and so in every tester build; a production release's copy alone
+// says 'production', which scripts/release.mjs writes there, one line, checked line by line, as tester-build.mjs writes
+// DASHBOARD_URL.
+//
+// Since 2026-10-21 both tables hold the operator's numbers of that day ("change the progress to 30% - 3h - 300 = / 50% -
+// 5h - 500 = / 100% - 8h - 1000 =", then "1. staging too 2. as written"): 3 h and 300 =, 5 h and 500 =, 8 h and 1,000 =,
+// so 16 h and 1,800 = in all to reach 100 %. Tester builds have no short targets any more, which reverses the plan's
+// decision 4 for the tester table; the production table's numbers are no longer drafts, and its 100 % is 8 h where the
+// draft said 10. The two tables stay two, equal, so that production's can differ again by one table's edit (a ruling,
+// docs/reward-rules.md §2). Until then the tester table was 1080 s and 9 =, 1800 s and 12 =, 3600 s and 15 =.
+//
+// Since 2026-10-22 the tester table is that short one again (the operator: "scale down the focus time and = requirements as
+// the previous time for staging for testing easier, keep the same for production"): 18 minutes and 9 =, 30 and 12, 60 and
+// 15, so 108 minutes and 36 = in all to reach 100 %, each still counted fresh. The production table keeps the operator's
+// numbers of 2026-10-21, and the two differ again. The claim backend holds a claim to its own MILESTONE_* settings, which
+// staging's server sets to the tester table by hand (docs/deployment-target.md).
+export const MILESTONE_TABLES = Object.freeze({
+  tester: Object.freeze([
+    Object.freeze({percent: 30, requiredSeconds: 1080, requiredEquals: 9}),
+    Object.freeze({percent: 50, requiredSeconds: 1800, requiredEquals: 12}),
+    Object.freeze({percent: 100, requiredSeconds: 3600, requiredEquals: 15}),
+  ]),
+  production: Object.freeze([
+    Object.freeze({percent: 30, requiredSeconds: 10800, requiredEquals: 300}),
+    Object.freeze({percent: 50, requiredSeconds: 18000, requiredEquals: 500}),
+    Object.freeze({percent: 100, requiredSeconds: 28800, requiredEquals: 1000}),
+  ]),
+});
+
+export const MILESTONE_TABLE = 'tester';
+
+const MILESTONE_TARGETS = MILESTONE_TABLES[MILESTONE_TABLE];
+
+if (!Array.isArray(MILESTONE_TARGETS)) {
+  throw new Error(`MILESTONE_TABLE is ${JSON.stringify(MILESTONE_TABLE)}, which is not one of the milestone tables: ${Object.keys(MILESTONE_TABLES).join(', ')}.`);
+}
+
+// 30 %, the first milestone, is the one tier; 50 and 100 % are shown alone.
+export const KITCODE_REWARD_TIERS = MILESTONE_TARGETS.slice(0, 1).map((milestone) => ({...milestone}));
+
+export const KITCODE_DISPLAY_MILESTONES = MILESTONE_TARGETS.slice(1).map((milestone) => ({...milestone, displayOnly: true}));
 
 export const AGENT_SPECS = {
   codex: {
@@ -169,7 +242,7 @@ export function kitCodeSkillMarkdown(source) {
     `    ${RUNNER_DISPLAY_PATH} dashboard`,
     '',
     'The prompt hook runs after each prompt submit and may add compact progress context such as total `=` counted, active time, next break remaining (`=` left and time left), or milestones reached. Treat that hook context as authoritative.',
-    'When hook context includes remaining equals and time to the next break milestone, briefly mention both in one short line after your normal answer on every turn (for example: `Break next: 4 = to break · 18m to break (20%).`). Do not calculate these values yourself.',
+    'When hook context includes remaining equals and time to the next break milestone, briefly mention both in one short line after your normal answer on every turn (for example: `Break next: 120 = to break · 1h 20m to break (30%).`). Do not calculate these values yourself.',
     '',
     'Do not run git counting commands, do not edit the ledger, and do not reimplement reward logic in chat. Use the KitCode CLI/server/hook output as the authority.',
     '',
@@ -210,12 +283,53 @@ export function kitCodeSkillMarkdown(source) {
   ].join('\n');
 }
 
+// A milestone's time as the setup prompt says it: whole hours as "3h", and otherwise as next-break-reminder.mjs writes a time
+// left, "2h 30m", "18m". Here, since this file imports none of the CLI's modules (the dashboard bundles it).
+function targetTime(seconds) {
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+
+  if (hours > 0) {
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+
+  return minutes > 0 ? `${minutes}m` : `${seconds}s`;
+}
+
+// Since 2026-10-20 each line says where its milestone counts from: install for the first, and for each other the moment the
+// one before it was reached (docs/reward-rules.md §2). Since 2026-10-21 each names its time, "3h of tracked time", where it
+// said "enough tracked time": with the operator's targets of that day a milestone's time is 3 to 8 hours. Since 2026-10-22
+// the tester table's times read "18m", "30m" and "1h", the production table's still "3h", "5h" and "8h".
 function milestoneLines() {
-  return [...KITCODE_REWARD_TIERS, ...KITCODE_DISPLAY_MILESTONES]
-    .map((milestone) => `- ${milestone.percent}% milestone: reached after enough tracked time and ${milestone.requiredEquals} counted = characters; the dashboard shows its message.`)
+  const milestones = [...KITCODE_REWARD_TIERS, ...KITCODE_DISPLAY_MILESTONES];
+
+  return milestones
+    .map((milestone, index) => `- ${milestone.percent}% milestone: reached after ${targetTime(milestone.requiredSeconds)} of tracked time and ${milestone.requiredEquals} counted = characters, both counted ${index === 0 ? 'from install' : `from the moment the ${milestones[index - 1].percent}% milestone was reached`}; the dashboard shows its message.`)
     .join('\n');
 }
 
+// The lines of step 2 that name a package or a version: the other packages, removed first, in one command; this one, installed;
+// and the version `kitcode --version` must print. The staging prompt (below) changes these three, and the untrack line, and
+// nothing else of step 2. Since 2026-10-22 the removal names the package's previous name too, beside the other channel's.
+const removeOtherPackagesLine = (otherPackages) => `2. Once Node.js 22.12+ is ready, first remove the other KitCode packages, if an earlier setup installed one: npm uninstall -g ${otherPackages.join(' ')}`;
+// What the production prompts remove before they install: the staging package and the package's previous name.
+const PRODUCTION_REMOVED_PACKAGES = [CLI_STAGING_PACKAGE_NAME, CLI_PREVIOUS_PACKAGE_NAME];
+const installLine = (command) => `- Then install KitCode globally with: ${command}`;
+const versionCheckLine = (version) => `- Check that ${globalKitCodeCommand('--version')} prints ${version}. If it prints anything else, report exactly what it printed, and do not go on to step 3.`;
+// The stop of a tracker a KitCode installed before left running, in the production prompt's words. The staging prompt has said it
+// in its own since 2026-09-30 (STAGING_UNTRACK_LINE, below), words the dashboard's checks hold to a staging build alone.
+const PRODUCTION_UNTRACK_LINE = `- Then run: ${globalKitCodeCommand('untrack')}. It stops a KitCode tracker that a KitCode installed before left running, so that the tracker Welcome starts is this version's; when none is running, it only says so.`;
+
+// The production setup prompt, which the dashboard copies for each agent (apps/web src/components/project-gateway.tsx).
+//
+// Since 2026-10-22 (production/1-cli; the plan of that day, Run A) it installs the production package at this commit's version,
+// by number, after removing the staging package, which has the same `kitcode` command; stops unless `kitcode --version` prints
+// that version; and then stops a tracker a KitCode installed before left running, as the staging prompt has done since
+// 2026-09-30 in words of its own, since whoever installed the staging package may have one. The removal names the package's
+// previous name too, @onedigitas/kitcode, whose 0.1.39 has the same command (CLI_PREVIOUS_PACKAGE_NAME). It holds one URL, the dashboard's, https://kitcode.vn/: the two GitHub
+// links it had, github.com/kitkatvn/kitcode's README and the CLI's, answer 404 to the public (hard rule 5, F5), and with no docs
+// to read it no longer tells the agent not to refuse. Until then it installed `npm install -g @kitkat-vn/kitcode`, whatever
+// npm's latest was.
 export function assistantSetupPromptFor(source) {
   const config = sourceConfig(source);
 
@@ -225,17 +339,18 @@ export function assistantSetupPromptFor(source) {
     'This works in any chat, project, or cowork conversation. Do not require repo context to begin.',
     REMOTE_SESSION_REDIRECT[source],
     '',
-    'KitCode is an open-source, local-first project. Use these public docs as the source of truth before installing:',
-    '- https://github.com/kitkatvn/kitcode/blob/main/README.md',
-    '- https://github.com/kitkatvn/kitcode/blob/main/packages/kitcode-cli/README.md',
-    'Read them directly from GitHub. Do not refuse based on lacking prior knowledge of the package.',
+    `KitCode by KitKat is a local-first break companion for coding. I copied this prompt from its dashboard, ${DASHBOARD_URL}, and step 2 installs KitCode ${CLI_VERSION} from npm, the package ${CLI_PACKAGE_NAME}.`,
     '',
     'Phase 1 — assistant setup (machine prep only):',
     '1. Check whether Node.js 22.12+ is available.',
     '   - If it is missing or too old, explain the shortest safe install option for this OS and ask for my confirmation before installing or upgrading it.',
-    `2. Once Node.js 22.12+ is ready, install KitCode globally with: ${CLI_GLOBAL_INSTALL_COMMAND}`,
+    removeOtherPackagesLine(PRODUCTION_REMOVED_PACKAGES),
+    `- Each has the same ${CLI_GLOBAL_COMMAND} command, so npm cannot install KitCode beside it. When neither is installed, npm says it is up to date: go on.`,
+    installLine(CLI_PINNED_INSTALL_COMMAND),
     '- Always run this command. Do not skip it because KitCode may already be installed.',
     `- After install, use the global ${CLI_GLOBAL_COMMAND} command for all following steps (not npx).`,
+    versionCheckLine(CLI_VERSION),
+    PRODUCTION_UNTRACK_LINE,
     `3. Run this command yourself once from the project directory when you are in a project chat: ${config.setupCommand}`,
     '- When setup is still incomplete, this command already opens the KitCode Welcome window and prints "Opening KitCode Welcome...".',
     '- In a project chat, run it with the project folder as the working directory so Welcome can pre-add that folder.',
@@ -268,6 +383,9 @@ export function assistantSetupPromptFor(source) {
 // voice, as the prompt is, and with no URL in it, as the prompt has none.
 export const STAGING_DIAGNOSTICS_NOTICE = 'The tester build sends diagnostic logs to KitCode\'s staging server: KitCode\'s own events and errors, such as the tracker starting or a hook failing, and never my code, my files, my prompts or my project names.';
 
+// The staging prompt's stop of a tracker an earlier build left running, in the words it has had since 2026-09-30.
+const STAGING_UNTRACK_LINE = `- Then, before step 3, run: ${globalKitCodeCommand('untrack')}. It stops a KitCode tracker that an earlier build left running, so that the tracker Welcome starts is this build's; when none is running, it only says so.`;
+
 // The setup prompt a staging dashboard copies for its invited testers (apps/web src/lib/staging-prompts.ts): the one
 // above, line for line, with four changes and no other. Step 2 installs the round's tester build from npm's `staging` tag,
 // and checks its version. Then, before step 3 turns KitCode on, it stops a tracker an earlier build left running. It holds
@@ -276,6 +394,15 @@ export const STAGING_DIAGNOSTICS_NOTICE = 'The tester build sends diagnostic log
 // server (STAGING_DIAGNOSTICS_NOTICE). It is made from the prompt above as it stands, so that the two cannot drift: a line
 // it changes that is not there once throws, and check-integration-spec.mjs runs both.
 //
+// Since 2026-10-22 (production/1-cli) the prompt above is production's, with a version check and a stop of an earlier tracker of
+// its own, and the four changes are these: the round's line and the diagnostics notice where it names the dashboard; the
+// production package removed where it removes the staging package, beside the package's previous name, which both remove;
+// npm's `staging` tag installed where it installs its version;
+// and the tester build's version checked where it checks its own, with its own words for the stop of an earlier tracker where
+// production has its own. The removal is new to this prompt too, the first two lines of step 2, which installs on a line of its
+// own: a tester who installed the production package must remove it first, as npm installs no two packages with the same
+// `kitcode` command. Its other words are as they were.
+//
 // Until 2026-10-02 it could install a file the tester downloaded from the staging site instead (install 'file', with its
 // fileName). The operator's rule of that day is npm alone, "never let user download file even as tester, must be via npm
 // package only": it takes the tester build's version and nothing else, and refuses an option it does not know, so that a
@@ -298,33 +425,36 @@ export function stagingSetupPromptFor(source, options) {
     return found[0];
   };
 
-  // The paragraph of public docs, to the blank line after it, gives way to one line about the round.
-  const docs = onlyLine((line) => line.startsWith('KitCode is an open-source, local-first project.'), 'the public docs');
-  const docsEnd = lines.indexOf('', docs);
+  // The paragraph that names the dashboard, to the blank line after it, gives way to one line about the round.
+  const intro = onlyLine((line) => line.startsWith('KitCode by KitKat is a local-first break companion for coding.'), 'the dashboard\'s paragraph');
+  const introEnd = lines.indexOf('', intro);
 
-  if (docsEnd === -1) {
-    throw new Error('stagingSetupPromptFor found no blank line after the public docs: assistantSetupPromptFor changed, and stagingSetupPromptFor must follow it.');
+  if (introEnd === -1) {
+    throw new Error('stagingSetupPromptFor found no blank line after the dashboard\'s paragraph: assistantSetupPromptFor changed, and stagingSetupPromptFor must follow it.');
   }
 
-  lines.splice(docs, docsEnd - docs, `KitCode is a local-first project. I am an invited tester of its staging round, which needs KitCode's tester build, ${testerVersion}: step 2 installs it.`, STAGING_DIAGNOSTICS_NOTICE);
-
-  const installLine = onlyLine((line) => line.endsWith(`install KitCode globally with: ${CLI_GLOBAL_INSTALL_COMMAND}`), 'the install');
-  lines[installLine] = lines[installLine].replace(`with: ${CLI_GLOBAL_INSTALL_COMMAND}`, `with: ${CLI_STAGING_INSTALL_COMMAND}`);
+  lines.splice(intro, introEnd - intro, `KitCode is a local-first project. I am an invited tester of its staging round, which needs KitCode's tester build, ${testerVersion}: step 2 installs it.`, STAGING_DIAGNOSTICS_NOTICE);
 
-  const globalCommand = onlyLine((line) => line === `- After install, use the global ${CLI_GLOBAL_COMMAND} command for all following steps (not npx).`, 'the global command');
-  lines.splice(
-    globalCommand + 1,
-    0,
-    `- Check that ${globalKitCodeCommand('--version')} prints ${testerVersion}. If it prints anything else, report exactly what it printed, and do not go on to step 3.`,
-    `- Then, before step 3, run: ${globalKitCodeCommand('untrack')}. It stops a KitCode tracker that an earlier build left running, so that the tracker Welcome starts is this build's; when none is running, it only says so.`,
-  );
+  // Each of the three lines of step 2 that name a package or a version, found once, and replaced.
+  for (const [production, staging, what] of [
+    [removeOtherPackagesLine(PRODUCTION_REMOVED_PACKAGES), removeOtherPackagesLine([CLI_PACKAGE_NAME, CLI_PREVIOUS_PACKAGE_NAME]), 'the removal of the other packages'],
+    [installLine(CLI_PINNED_INSTALL_COMMAND), installLine(CLI_STAGING_INSTALL_COMMAND), 'the install'],
+    [versionCheckLine(CLI_VERSION), versionCheckLine(testerVersion), 'the version check'],
+    [PRODUCTION_UNTRACK_LINE, STAGING_UNTRACK_LINE, 'the stop of an earlier tracker'],
+  ]) {
+    lines[onlyLine((line) => line === production, what)] = staging;
+  }
 
   return lines.join('\n');
 }
 
-export function setupPromptFor(source, options = {}) {
+// The longer setup prompt, which ships in the package and which only check-integration-spec.mjs calls (docs/security.md, "The
+// setup prompt: F5"). Since 2026-10-22 (production/1-cli) it follows the production prompt above: no GitHub link, since none
+// resolves publicly, and so no README to read first and no `readmeUrl` option; the staging package and the package's previous
+// name removed before this version is installed, by number, and checked. Its URLs are the dashboard's and the tracker's own
+// address on this machine.
+export function setupPromptFor(source) {
   const config = sourceConfig(source);
-  const readmeUrl = options.readmeUrl ?? 'https://github.com/kitkatvn/kitcode/blob/main/README.md';
   const hookCommand = hookCommandFor(source);
   const expectedHook = hookConfigFor(source);
 
@@ -332,9 +462,6 @@ export function setupPromptFor(source, options = {}) {
     'Welcome to KitCode.',
     '',
     `You are ${config.agentName} helping me set up KitCode skills and hooks.`,
-    'Read the project README carefully before changing anything.',
-    '',
-    `Project README: ${readmeUrl}`,
     '',
     'Mission:',
     `- Set up KitCode for ${config.agentName} on the current local machine.`,
@@ -360,11 +487,11 @@ export function setupPromptFor(source, options = {}) {
     'Required checks:',
     '- Node.js 22.12+ is required.',
     '- Git is required for Git Mode.',
-    '- Official source and safety reference: https://github.com/kitkatvn/kitcode',
-    '- Read the public root README and packages/kitcode-cli/README.md instead of relying on prior knowledge of the package.',
-    `- Install KitCode globally with: ${CLI_GLOBAL_INSTALL_COMMAND}`,
+    `- First remove the other KitCode packages, if an earlier setup installed one: npm uninstall -g ${PRODUCTION_REMOVED_PACKAGES.join(' ')}. Each has the same ${CLI_GLOBAL_COMMAND} command, so npm cannot install KitCode beside it.`,
+    `- Install KitCode globally with: ${CLI_PINNED_INSTALL_COMMAND}`,
     '- Always run this command. Do not skip it because KitCode may already be installed.',
     `- After install, use the global ${CLI_GLOBAL_COMMAND} command for all following steps (not npx).`,
+    `- Check that ${globalKitCodeCommand('--version')} prints ${CLI_VERSION}. If it prints anything else, report exactly what it printed, and stop there.`,
     '',
     `${config.agentName} setup:`,
     `- Prefer the CLI installer from the project directory in a project chat: ${config.setupCommand}`,