docs: this repo is public, so say what things are, not who decided them

Comments and served API descriptions here had grown references that only make
sense to someone with our internal notes: relative paths that escape this
tree, filenames and titles of documents nobody outside can open, quoted prose
from them, and the name of a component that has no public surface — once in an
OpenAPI description, which is published output rather than source.

None of it was load-bearing. Every case restates as what the code actually
requires, and every rewrite came out shorter: "in the words the host agent
reports" for a component name, "republished as addresses are discovered" for a
quoted phrase, "a size tier sets vCPU, RAM and the output geometry" for a
sentence that had been carrying a path.

Internal reasoning is now cited exactly one way, ref(d-NNNN) in a source
comment, with the rule that the sentence must still stand if the marker is
deleted. CLAUDE.md leads with it, because the previous version of this mistake
was made by people who knew the repo was public and it still took ten
occurrences to notice, so "be careful" is not a mechanism.

Commit messages get the stricter rule and carry no references at all: a
comment can be fixed by the next commit and a published message cannot be
fixed at all. Git hooks now enforce both halves.

The check caught a real one while being written: the CLAUDE.md table spelled
out the paths it was prohibiting, which discloses them to exactly the reader
it protects against.

138 tests, 0 fail.

packages/core/src/session/index.ts

@@ -136,9 +136,9 @@ export namespace Session {
 	/**
 	 * Publish the current ticket.
 	 *
-	 * Overwrites, deliberately: the vsock contract describes the ticket as *"a
-	 * stream, not one value"*, so a later ticket for the same session is a
-	 * better address for the same thing and not a second session.
+	 * Overwrites, deliberately: a ticket is republished as addresses are
+	 * discovered, so a later one for the same session is a better address for
+	 * the same thing and not a second session.
 	 */
 	export const setTicket = fn(Info.pick({ id: true, ticket: true }), async (input) => {
 		return Database.use(async (tx) => {

packages/core/src/session/session.sql.ts

@@ -10,7 +10,8 @@ import { LinkedAccountTable } from '../user/linked-account.sql.js';
  *
  * `requested` is written by `POST /session` before anything has been placed,
  * which is what makes the row the job: the control plane picks a machine and
- * `neslet` takes it from here. `live` is the only state that costs money.
+ * the agent on it takes over from there. `live` is the only state that costs
+ * money.
  */
 export const SessionState = pgEnum('session_state', [
 	'requested',
@@ -23,14 +24,12 @@ export const SessionState = pgEnum('session_state', [
 /**
  * One live run of one box, and the thing that gets billed.
  *
- * Separate from `box` for two reasons
- * ([0048](../../../../.nestri/decisions/0048-email-is-the-root-identity-and-a-box-is-a-row.md)):
- * a box is a durable thing somebody owns while a session is what costs money
- * and what [`limits.md`](../../../../.nestri/contracts/limits.md) burns
- * session-hours against — and because the connect ticket **changes after bind
- * as addresses are discovered.** The vsock contract calls it *"a stream, not
- * one value"*, so `ticket` is a column that gets rewritten in place while the
- * session is starting, and a client polls it rather than receiving it once.
+ * Separate from `box` for two reasons. A box is a durable thing somebody owns,
+ * while a session is what costs money and what quota is measured in
+ * session-hours against. And the connect ticket **changes after bind as
+ * addresses are discovered** — it is republished rather than issued once, so
+ * `ticket` is a column rewritten in place while the session starts and a
+ * client polls it instead of receiving a final value. ref(d-0048)
  */
 export const SessionTable = pgTable(
 	'session',
@@ -43,9 +42,9 @@ export const SessionTable = pgTable(
 		gameId: ulid('game_id')
 			.notNull()
 			.references(() => GameTable.id, { onDelete: 'restrict' }),
-		// Which Steam account this run is playing as. A user may have up to four
-		// linked, and *which one* is the question the "who's playing?" screen
-		// asks — so it belongs on the session and not on the box.
+		// Which Steam account this run is playing as. A user may link several,
+		// and *which one* is the question the "who's playing?" screen asks — so
+		// it belongs on the session and not on the box.
 		//
 		// `restrict`, because unlinking a Steam account must not erase the
 		// billing history of what it played.
@@ -67,8 +66,8 @@ export const SessionTable = pgTable(
 	(t) => [
 		index('session_box_idx').on(t.boxId),
 		index('session_state_idx').on(t.state),
-		// Metering reads "sessions in this window"; per 0048 this table is what
-		// billing sums, so the time index is not speculative.
+		// Metering reads "sessions in this window", and this table is what
+		// billing sums, so the time index is not speculative. ref(d-0048)
 		index('session_started_idx').on(t.timeStarted)
 	]
 );

packages/core/src/session/session.test.ts

@@ -87,8 +87,8 @@ describe('Session', () => {
 		expect((await Session.setTicket({ id: session.id, ticket: 'ticket-one' }))?.ticket).toBe(
 			'ticket-one'
 		);
-		// The vsock contract calls the ticket "a stream, not one value" — a second
-		// ticket is a better address for the same session, not a new session.
+		// A ticket is republished as addresses are discovered — a second one is a
+		// better address for the same session, not a new session.
 		expect((await Session.setTicket({ id: session.id, ticket: 'ticket-two' }))?.ticket).toBe(
 			'ticket-two'
 		);