From 20643f640391180229074c76f9f1fbdd8cb65622 Mon Sep 17 00:00:00 2001 From: Benjamin Davis Date: Fri, 24 Jul 2026 22:40:49 -0700 Subject: [PATCH 1/6] feat(ts): add Effect v4 foundation and Go-faithful JSON codec Begin the TypeScript port. This lands the pieces every other module depends on, verified against the Go implementation before anything is built on top of them. - src/effect.ts: mandated barrel for effect/unstable/* imports, so a pre-4.0-final rename is a one-file fix - src/json/: number-preserving parse (Go UseNumber equivalent, via the ES2025 `source` reviver) and a Go-compatible encoder - src/util/gostring.ts: UTF-8 byte-order key comparison and rune counting JSON.stringify cannot be used for output: it does not escape U+2028/9, emits \udXXX for lone surrogates, and does not sort keys. It is banned outside src/json/encode.ts. Verified with a differential harness against Go 1.26.5 encoding/json: 15,000 randomized documents across 3 seeds, zero mismatches in both compact and pretty output. That harness caught two errors that the hand-written tests passed: - The spec claimed Go emits  / for backspace and form feed; byte-level checking shows Go uses the short \b and \f escapes, matching JSON.stringify. - Lone surrogates yield ONE U+FFFD, not three. Go's decoder collapses a \uD800 escape at decode time; the three-U+FFFD behavior only applies to raw WTF-8 bytes, which never enter this pipeline. Numeric literals survive byte-for-byte, including 9007199254740993123 from the Go test suite, which JSON.parse silently corrupts. Co-Authored-By: Claude Opus 5 (1M context) --- .gitignore | 3 + bun.lock | 138 ++++++++++++++++++++++++++++++++ package.json | 23 ++++++ src/effect.ts | 30 +++++++ src/json/codec.test.ts | Bin 0 -> 6677 bytes src/json/encode.ts | 176 +++++++++++++++++++++++++++++++++++++++++ src/json/parse.ts | 62 +++++++++++++++ src/json/value.ts | 55 +++++++++++++ src/util/gostring.ts | 36 +++++++++ tsconfig.json | 18 +++++ 10 files changed, 541 insertions(+) create mode 100644 bun.lock create mode 100644 package.json create mode 100644 src/effect.ts create mode 100644 src/json/codec.test.ts create mode 100644 src/json/encode.ts create mode 100644 src/json/parse.ts create mode 100644 src/json/value.ts create mode 100644 src/util/gostring.ts create mode 100644 tsconfig.json diff --git a/.gitignore b/.gitignore index 2fd24f5..c0f6777 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,6 @@ # Local credentials (never commit) .env + +# TypeScript / Bun +/node_modules/ diff --git a/bun.lock b/bun.lock new file mode 100644 index 0000000..9dbee73 --- /dev/null +++ b/bun.lock @@ -0,0 +1,138 @@ +{ + "lockfileVersion": 1, + "configVersion": 1, + "workspaces": { + "": { + "name": "oytc", + "dependencies": { + "@effect/platform-bun": "4.0.0-beta.101", + "effect": "4.0.0-beta.101", + }, + "devDependencies": { + "@effect/language-service": "0.87.1", + "@effect/tsgo": "0.24.3", + "@types/bun": "latest", + "typescript": "7.0.2", + }, + }, + }, + "packages": { + "@effect/language-service": ["@effect/language-service@0.87.1", "", { "bin": { "effect-language-service": "cli.js" } }, "sha512-kcljlJmEgqg5mFAM6UShJYJjMqJb3TbHHxrK8Qoubvwugc0aVWpRkbdgQvK5b17puOt3BKXXKOmcV+oQt0oQqQ=="], + + "@effect/platform-bun": ["@effect/platform-bun@4.0.0-beta.101", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.101" }, "peerDependencies": { "effect": "^4.0.0-beta.101" } }, "sha512-7cSiwufNCjO1d296KMjHjqFA1oDRVZMZEyYMzdqPvAdIhNQj16U+xZfMdeJuUb6/WouEWWultkhcCK5ysdxIcQ=="], + + "@effect/platform-node-shared": ["@effect/platform-node-shared@4.0.0-beta.101", "", { "dependencies": { "@types/ws": "^8.18.1", "ws": "^8.21.0" }, "peerDependencies": { "effect": "^4.0.0-beta.101" } }, "sha512-g4L7XiyJSNJLJVhlslyg2zBCQsoKQf1y1gd+Yfd+3wD9ymC+m7ymbd/5FGqnT1aXV6E2AwRr4D/R1eyRUikvWQ=="], + + "@effect/tsgo": ["@effect/tsgo@0.24.3", "", { "optionalDependencies": { "@effect/tsgo-darwin-arm64": "0.24.3", "@effect/tsgo-darwin-x64": "0.24.3", "@effect/tsgo-linux-arm": "0.24.3", "@effect/tsgo-linux-arm64": "0.24.3", "@effect/tsgo-linux-x64": "0.24.3", "@effect/tsgo-win32-arm64": "0.24.3", "@effect/tsgo-win32-x64": "0.24.3" }, "bin": { "effect-tsgo": "dist/effect-tsgo.js" } }, "sha512-WQxKU3MFzWzI38GbE9cf0POkVX4y0xahD8QqDjLfixW1AEValuHNfOQvyKM2MDWOLdGff4hP8VnIOeduwQt66A=="], + + "@effect/tsgo-darwin-arm64": ["@effect/tsgo-darwin-arm64@0.24.3", "", { "os": "darwin", "cpu": "arm64" }, "sha512-eO83D7ZmpAsocA5WJQ8SSAPnAOZ+dEduFIozg9c2SmH36PCHG1Eb++I0UiQml+2LAr4o/QE2wKdWj7LExebjZA=="], + + "@effect/tsgo-darwin-x64": ["@effect/tsgo-darwin-x64@0.24.3", "", { "os": "darwin", "cpu": "x64" }, "sha512-ksX9BdCM8289RRuN0lWhtzuvstH1frxwdxhoW08rrGW3ryER3udEFqEtgtveP0cYvK9gTlV5lXbQPNGktQ2sTw=="], + + "@effect/tsgo-linux-arm": ["@effect/tsgo-linux-arm@0.24.3", "", { "os": "linux", "cpu": "arm" }, "sha512-0TzebGLMNZkHOGSK0w1B4zuvHGlA+Od4LdElWeHHP6iMPEiEWPq17If787+oc+Y67yITPJ9DZcibu69eI9mZhg=="], + + "@effect/tsgo-linux-arm64": ["@effect/tsgo-linux-arm64@0.24.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-CMiThuURi14rT5Ikag5pVnUC3tx4IcmPpRR4WBQkHxAbOf5a1Lo1NUF82zY0azhLW2WszBamTSZP5Tcv4uks2A=="], + + "@effect/tsgo-linux-x64": ["@effect/tsgo-linux-x64@0.24.3", "", { "os": "linux", "cpu": "x64" }, "sha512-R4jl1JWoYEldUU1rtCG1fXWW2ywj/rgY1xaCzK8HSb8fQhQ71WRLLAyAe8ewROuseWQ9Ip+IbbfAeXQOpmpdDA=="], + + "@effect/tsgo-win32-arm64": ["@effect/tsgo-win32-arm64@0.24.3", "", { "os": "win32", "cpu": "arm64" }, "sha512-DOJ4oa8pk8qxEQwKHpJOqtjOfB9iOMuc6Cnb2ZbTG32PBfhqeRYv6YFGhFtgAojXyxfuRP2gCJVpFfjzHJh7nQ=="], + + "@effect/tsgo-win32-x64": ["@effect/tsgo-win32-x64@0.24.3", "", { "os": "win32", "cpu": "x64" }, "sha512-6GpENpPn3mXldmJoM+Z7qi+8fe39xJYB2bLD5jqCFWl14vFp1AeJvYwHYQak8HRm1FiPz72Ninslv8DjHYtZgA=="], + + "@msgpackr-extract/msgpackr-extract-darwin-arm64": ["@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-LCkGo6JDfaBhgST7UpPWgNgLINpcpabaHfyz5OBx75nUYxBsaEPxjnyNjWpeb/xBup/682QnBfRBy2/LvPutZQ=="], + + "@msgpackr-extract/msgpackr-extract-darwin-x64": ["@msgpackr-extract/msgpackr-extract-darwin-x64@3.0.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-zExlW9zUJKZH/tOtVMttwjKa4Xm/3KcNjnE3dPN92uCktwavMxpgCA3MoJK/DOnTWsQgo224OaST27/mPNAf+w=="], + + "@msgpackr-extract/msgpackr-extract-linux-arm": ["@msgpackr-extract/msgpackr-extract-linux-arm@3.0.4", "", { "os": "linux", "cpu": "arm" }, "sha512-Tg3yX65f5GbtXLkrYEHE5oibZG9epyYWas7FogTTEJeDEF9JlXJzKgXaNhT3UXlTOeA+AfZpYZYZ0uPj7Cfquw=="], + + "@msgpackr-extract/msgpackr-extract-linux-arm64": ["@msgpackr-extract/msgpackr-extract-linux-arm64@3.0.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-dgX0P/9wGPJeHFBG+ZmhgE6bmtMt7NP5CRBGyyktpopdk/mW4POnrpQsSLtKI1dwpc+pPLuXHDh6vvskyQE/sw=="], + + "@msgpackr-extract/msgpackr-extract-linux-x64": ["@msgpackr-extract/msgpackr-extract-linux-x64@3.0.4", "", { "os": "linux", "cpu": "x64" }, "sha512-8TNXMEjJc3QEy7R/x1INhgiU+XakDAFUzBhaz7+Rbrs8NH5UQeHQxxmzsSBJGyV6I1jW79undiQm8tOI+D+8FQ=="], + + "@msgpackr-extract/msgpackr-extract-win32-x64": ["@msgpackr-extract/msgpackr-extract-win32-x64@3.0.4", "", { "os": "win32", "cpu": "x64" }, "sha512-CmCXPQrkbwExx3j946/PtHWHbYJiCRBRDl4BlkRQcJB/YOwQxJRTpoo7aTsortjgoJ1x7opzTSxn7C+ASSLVjQ=="], + + "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="], + + "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="], + + "@types/node": ["@types/node@26.1.1", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-nxAkRSVkN1Y0JC1W8ky/fTfkGsMmcrRsbx+3XoZE+rMOX71kLYTV7fLXpqud1GpbpP5TuffXFqfX7fH2GgZREw=="], + + "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="], + + "@typescript/typescript-aix-ppc64": ["@typescript/typescript-aix-ppc64@7.0.2", "", { "os": "aix", "cpu": "ppc64" }, "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ=="], + + "@typescript/typescript-darwin-arm64": ["@typescript/typescript-darwin-arm64@7.0.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA=="], + + "@typescript/typescript-darwin-x64": ["@typescript/typescript-darwin-x64@7.0.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA=="], + + "@typescript/typescript-freebsd-arm64": ["@typescript/typescript-freebsd-arm64@7.0.2", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ=="], + + "@typescript/typescript-freebsd-x64": ["@typescript/typescript-freebsd-x64@7.0.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw=="], + + "@typescript/typescript-linux-arm": ["@typescript/typescript-linux-arm@7.0.2", "", { "os": "linux", "cpu": "arm" }, "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ=="], + + "@typescript/typescript-linux-arm64": ["@typescript/typescript-linux-arm64@7.0.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ=="], + + "@typescript/typescript-linux-loong64": ["@typescript/typescript-linux-loong64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ=="], + + "@typescript/typescript-linux-mips64el": ["@typescript/typescript-linux-mips64el@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA=="], + + "@typescript/typescript-linux-ppc64": ["@typescript/typescript-linux-ppc64@7.0.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA=="], + + "@typescript/typescript-linux-riscv64": ["@typescript/typescript-linux-riscv64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ=="], + + "@typescript/typescript-linux-s390x": ["@typescript/typescript-linux-s390x@7.0.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw=="], + + "@typescript/typescript-linux-x64": ["@typescript/typescript-linux-x64@7.0.2", "", { "os": "linux", "cpu": "x64" }, "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A=="], + + "@typescript/typescript-netbsd-arm64": ["@typescript/typescript-netbsd-arm64@7.0.2", "", { "os": "none", "cpu": "arm64" }, "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA=="], + + "@typescript/typescript-netbsd-x64": ["@typescript/typescript-netbsd-x64@7.0.2", "", { "os": "none", "cpu": "x64" }, "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA=="], + + "@typescript/typescript-openbsd-arm64": ["@typescript/typescript-openbsd-arm64@7.0.2", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ=="], + + "@typescript/typescript-openbsd-x64": ["@typescript/typescript-openbsd-x64@7.0.2", "", { "os": "openbsd", "cpu": "x64" }, "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg=="], + + "@typescript/typescript-sunos-x64": ["@typescript/typescript-sunos-x64@7.0.2", "", { "os": "sunos", "cpu": "x64" }, "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g=="], + + "@typescript/typescript-win32-arm64": ["@typescript/typescript-win32-arm64@7.0.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ=="], + + "@typescript/typescript-win32-x64": ["@typescript/typescript-win32-x64@7.0.2", "", { "os": "win32", "cpu": "x64" }, "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g=="], + + "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="], + + "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="], + + "effect": ["effect@4.0.0-beta.101", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.9.0", "find-my-way-ts": "^0.1.6", "ini": "^7.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^2.0.4", "multipasta": "^0.2.8", "toml": "^4.1.2", "uuid": "^14.0.1", "yaml": "^2.9.0" } }, "sha512-HjowumlIo+orthn4jMlEJPuzIYPBV+uq/XiciHWhiedLsXQpWHdNJHO5d59BVDP5s1LPuvERcktwFqRXnJqnhA=="], + + "fast-check": ["fast-check@4.9.0", "", { "dependencies": { "pure-rand": "^8.0.0" } }, "sha512-7ms6T7SybUev/PQITciI0yLM2pOSFy5zpG8Ty7tQofcVaQUvrMXp6CBwqF6fThLCLOrfBtuHAtwq6Yu4XPCllg=="], + + "find-my-way-ts": ["find-my-way-ts@0.1.6", "", {}, "sha512-a85L9ZoXtNAey3Y6Z+eBWW658kO/MwR7zIafkIUPUMf3isZG0NCs2pjW2wtjxAKuJPxMAsHUIP4ZPGv0o5gyTA=="], + + "ini": ["ini@7.0.0", "", {}, "sha512-ifK0CgjALofS5bkrcTy4RaQ9Vx2Knf/eLeIO+NaswQEpH1UblrtTSCIvN71qQDMq0PeQ/SSPojvEJp9vvvfr+w=="], + + "kubernetes-types": ["kubernetes-types@1.30.0", "", {}, "sha512-Dew1okvhM/SQcIa2rcgujNndZwU8VnSapDgdxlYoB84ZlpAD43U6KLAFqYo17ykSFGHNPrg0qry0bP+GJd9v7Q=="], + + "msgpackr": ["msgpackr@2.0.4", "", { "optionalDependencies": { "msgpackr-extract": "^3.0.4" } }, "sha512-o1C5KRmuRt+apqMr1HuGSqWStZoRBUpEsCsl15uM9VdAF1qHLtvMOU2En747EnTyEl6c4pzPewRMFF31s1CNbA=="], + + "msgpackr-extract": ["msgpackr-extract@3.0.4", "", { "dependencies": { "node-gyp-build-optional-packages": "5.2.2" }, "optionalDependencies": { "@msgpackr-extract/msgpackr-extract-darwin-arm64": "3.0.4", "@msgpackr-extract/msgpackr-extract-darwin-x64": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-arm": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-arm64": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-x64": "3.0.4", "@msgpackr-extract/msgpackr-extract-win32-x64": "3.0.4" }, "bin": { "download-msgpackr-prebuilds": "bin/download-prebuilds.js" } }, "sha512-4kmO/MdyUIkLIvTPr8VHLil4AtoKIoniWPIEk5+CDy0xnWC84azhSFmuJ7PxZdsYtiP5kEeQsORAVIeMgxT+Hw=="], + + "multipasta": ["multipasta@0.2.8", "", {}, "sha512-ZPWuMKyv0cSO29f7hozp+k6+crZbQijV8ipMvxNxRf2SwtYGTX1ZX89Kd20VV4H9Znonx+EQn+iy1wGQsJ+b+Q=="], + + "node-gyp-build-optional-packages": ["node-gyp-build-optional-packages@5.2.2", "", { "dependencies": { "detect-libc": "^2.0.1" }, "bin": { "node-gyp-build-optional-packages": "bin.js", "node-gyp-build-optional-packages-optional": "optional.js", "node-gyp-build-optional-packages-test": "build-test.js" } }, "sha512-s+w+rBWnpTMwSFbaE0UXsRlg7hU4FjekKU4eyAih5T8nJuNZT1nNsskXpxmeqSK9UzkBl6UgRlnKc8hz8IEqOw=="], + + "pure-rand": ["pure-rand@8.4.2", "", {}, "sha512-vvuOGgcuPJAirlHvuQw1TrOiw7ptaIXXmIbNuiNOY6lNGJJH49PQ1Kj4nd783nPdQhQdicgOjVI2yI/9BD6/Ng=="], + + "toml": ["toml@4.3.0", "", {}, "sha512-lVb8X9BsPVuH0M4BKeS91tXAmJvCjQ5UIyAbQFaxkKGyUFK2RPkhwaFSQH8vbpl1d23eu/IBH+dwVMHWaq9A5A=="], + + "typescript": ["typescript@7.0.2", "", { "optionalDependencies": { "@typescript/typescript-aix-ppc64": "7.0.2", "@typescript/typescript-darwin-arm64": "7.0.2", "@typescript/typescript-darwin-x64": "7.0.2", "@typescript/typescript-freebsd-arm64": "7.0.2", "@typescript/typescript-freebsd-x64": "7.0.2", "@typescript/typescript-linux-arm": "7.0.2", "@typescript/typescript-linux-arm64": "7.0.2", "@typescript/typescript-linux-loong64": "7.0.2", "@typescript/typescript-linux-mips64el": "7.0.2", "@typescript/typescript-linux-ppc64": "7.0.2", "@typescript/typescript-linux-riscv64": "7.0.2", "@typescript/typescript-linux-s390x": "7.0.2", "@typescript/typescript-linux-x64": "7.0.2", "@typescript/typescript-netbsd-arm64": "7.0.2", "@typescript/typescript-netbsd-x64": "7.0.2", "@typescript/typescript-openbsd-arm64": "7.0.2", "@typescript/typescript-openbsd-x64": "7.0.2", "@typescript/typescript-sunos-x64": "7.0.2", "@typescript/typescript-win32-arm64": "7.0.2", "@typescript/typescript-win32-x64": "7.0.2" }, "bin": { "tsc": "bin/tsc" } }, "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA=="], + + "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="], + + "uuid": ["uuid@14.0.1", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-6ZxzVpzDXDa3bJWaHilVayA+BH/1zmxCJoVgvmqJnid/gPoKHxUrS/aC/T6LGQtNHT+XHG9fXPJB4d+IrU30Ew=="], + + "ws": ["ws@8.21.1", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-+0NTnW77fFN/DjQi6k/Sq/Yvk4Sgajw7urW8V+asjXnRgDs9gyGkdb7EzgfhA4goXsRIZKE28fzIXBHEzhuiWw=="], + + "yaml": ["yaml@2.9.0", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="], + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..d589bd1 --- /dev/null +++ b/package.json @@ -0,0 +1,23 @@ +{ + "name": "oytc", + "type": "module", + "private": true, + "dependencies": { + "effect": "4.0.0-beta.101", + "@effect/platform-bun": "4.0.0-beta.101" + }, + "devDependencies": { + "typescript": "7.0.2", + "@effect/language-service": "0.87.1", + "@effect/tsgo": "0.24.3", + "@types/bun": "latest" + }, + "scripts": { + "postinstall": "chmod +x node_modules/@effect/tsgo-*/lib/tsc 2>/dev/null || true", + "typecheck": "tsc -p tsconfig.json", + "lint": "effect-tsgo diagnostics --project tsconfig.json --format text", + "test": "bun test", + "dev": "bun run src/main.ts", + "build": "bun build --compile --outfile=bin/oytc src/main.ts" + } +} diff --git a/src/effect.ts b/src/effect.ts new file mode 100644 index 0000000..247cb82 --- /dev/null +++ b/src/effect.ts @@ -0,0 +1,30 @@ +/** + * MANDATED BARREL — the single import site for `effect/unstable/*`. + * + * The `unstable/` path prefix is a stability marker: these modules may be + * renamed before Effect 4.0 final. Every other file in `src/` MUST import + * these symbols from here, never from `effect/unstable/...` directly, so that + * a rename is a one-file fix rather than a repo-wide change. + * + * CI enforces this: + * ! grep -rn "effect/unstable" src/ --exclude=effect.ts + */ + +export { + Argument, + CliError, + Command, + Flag, + HelpDoc, + Prompt +} from "effect/unstable/cli" + +export { + FetchHttpClient, + Headers, + HttpClient, + HttpClientError, + HttpClientRequest, + HttpClientResponse, + UrlParams +} from "effect/unstable/http" diff --git a/src/json/codec.test.ts b/src/json/codec.test.ts new file mode 100644 index 0000000000000000000000000000000000000000..688ed42e39d1bff22432b95f20eb648150ace90e GIT binary patch literal 6677 zcmb_h-EJGl74Bsr^c{LIaH=IjQ6weV7SkATW!bUoSb=_WBdO4koE5iP?lLpGq#1%h z9-=^Riry8di@rk9i@r%Ng5LEN`kk5mB`Kv28U)dD_nb3l&d+y#5{xIYPG~_xWd=Iv zt0t-U6E#Shlqi$Xl6)PHN%YgG$1lWIkaL_WlZGXQ@_n#XzN=^u57n#qEYU%93%TX* zl;!8Yzm{RDii29a?tLpU6LDrfJ~abIcZKc6UK9(zEOw4A*S z5~XEmpB-66-jwyQ^0sz&>D|fsagUNwV8{NkajCEI|SDKDKe@2TfBFCUXTDZgVH1I9($#VhG3d~Cx zgsE1ZZZzzsI%wY*`0S|zEDNViNn7~sR! zGS~R@_^Y?ikB+}Qes>O4#DD(z53#kChp#6h>;BwOG||c^J(Wp-;PGC?bYYZpeM2;CRwFL#Zh{yb4Teyn%+p{7P|AZ5VIuiP@#@2e_D? zugSp8t{a~C#E|!iu_2V@bP-9LTzIn(k?1{IWVA~c;~(p>%~DDS<-rduP>j7m4yphm zql1fCT(OM&P5L6_pznSck;Q%9)4^8i;sBE2OwLgzY=8}G>>q0EhmM^UyVY_sDwVuf z#^_%k!Z5aKXOFCT*?3H(Vb^8Vy*&GeKmO&1KmGmRfBUm#Eq^ih(VO3*f^X)#N*5h} zf4{%9eC03ZL+J~KWyb*-fnF0-;^WRUs-R>LO;T?9Y;&oG6|~F%B(GYoUGyw{jtT{r z%Xj=2<@!~;ZRo}E(aDSBQ`F!vloK|Eq?@bs#nX2CCi4iRpdC2ZdU!W=@ zhJlYG>=-VWDmT^_1-u(-d$Lbt)!vvzxzY2a3J%MoEY1X?4=o+JlIaSm*)_Y8Xb(mc$>=` zgfbWd2GCZ*uxcD6398!9cYpDq^-$FFFkUsB{q*3i{rh?O6L{A;nmaY8SPy|M(QVD~ zE=_CUh>=mlI$(i8P*g2^4bhd4YMl2peSOjEG=&tsh4@zVx=k?`y}e~q3`FnJwS-ME z7QKVz^-r5QtYwJMUfMHQdefeSGu+wkBtD~QTTnj9a;<_>ertp@)(QEXha3WGgb0P9 zGg%Y;rD3ODRkyDD$@5v<2uu(kXIk<3NsaH zk1LhKp3|HC2;0NUuy=QP4J+3a>REl7qEG_x)8UeBi|q=Z zA83<&W?7!nuGL}3s^$X0v1i9yT9@O{38`-zV92IW0s^!}7o?6I4|=q)TL#Vt?uc0H zB~0k%pY_55+^>=~MZEy9*=?yU+?2=MkJOXQ`w+h-a7D43A{5rJ1T%4x@K_6HOh&LAYI$38^jp?fh-*Xw*Ze%j9q7`(?c#h&IkwN5bS9#WgJHrci zdABzj%VaPDv>;G0Nxrtrl$Fq44}%=!7}qig?KHa|1Dx*iSq5j`-(J{DBZbL6fd&Uq zhu*_jZ@KMOXAr5_C(Z_#IKU59 ztjR=grww`UCx|MA;^|}Wj7KcvD!hPRMrL%k#pFkJ`W5J+UC$f!udb4T$eG0DwQxs^ z1!g}RCEHkAprvx1C?;n6k{2}D6JITV=KBf|aEaoWayt`iCv3~y&KCoZLpmOP+$(I? z5o-NV^)M^4p?L?rjvnY|E2Y`Nq!obesO6|(Mu8a4S;;JTfIWt6lE!-RI@0E{y#7Y4xM`wMl jevkjlVyw07n^lVyMP+RpU(BkGCGTL%4IS4ryG;8p7d!A| literal 0 HcmV?d00001 diff --git a/src/json/encode.ts b/src/json/encode.ts new file mode 100644 index 0000000..24d6fdc --- /dev/null +++ b/src/json/encode.ts @@ -0,0 +1,176 @@ +/** + * Go-compatible JSON serializer. + * + * `JSON.stringify` CANNOT be used for output — it diverges from Go's + * `encoding/json` in three ways: + * + * 1. Go always escapes U+2028/U+2029; `JSON.stringify` never does. + * 2. Go replaces each invalid UTF-8 *byte* with U+FFFD (so one lone + * surrogate becomes THREE U+FFFD, one per byte of its WTF-8 encoding); + * `JSON.stringify` emits `\udXXX`. + * 3. Go sorts map keys (by UTF-8 bytes); `JSON.stringify` uses insertion order. + * + * Verified against Go 1.26.5 `encoding/json` with `SetEscapeHTML(false)`. + * NOTE: Go emits the SHORT escapes `\b` and `\f` (bytes `5c 62` / `5c 66`), + * matching `JSON.stringify`. An earlier spec claimed ``/` `; that + * was wrong and is contradicted by the byte-level reference output. + * + * `JSON.stringify` is banned everywhere outside this file; CI enforces it. + * + * Two encoders exist because the Go code emits two different key orders: + * - `encodeGoValue` sorts keys at every depth (Go marshals maps sorted) + * - `encodeGoStruct` preserves the given order (Go marshals structs in + * field-declaration order) + */ + +import { compareUtf8 } from "../util/gostring.ts" +import { isJsonArray, isJsonObject, isRawNumber, type JsonValue } from "./value.ts" + +export interface EncodeOptions { + readonly indent: "" | " " +} + +const HEX = "0123456789abcdef" + +const unicodeEscape = (code: number): string => + `\\u${HEX[(code >> 12) & 0xf]}${HEX[(code >> 8) & 0xf]}${HEX[(code >> 4) & 0xf]}${HEX[code & 0xf]}` + +/** + * Go `encoding/json` string escaping with `SetEscapeHTML(false)`. + * + * | input | output | + * |------------------------------|-----------------------------------| + * | `"` `\` | `\"` `\\` | + * | U+000A / U+000D / U+0009 | `\n` / `\r` / `\t` | + * | other c < 0x20 | `\u00xx` (NOT `\b` / `\f`) | + * | `<` `>` `&` | literal (EscapeHTML false) | + * | U+2028 / U+2029 | `
` / `
` (always) | + * | lone surrogate | literal U+FFFD | + */ +export const encodeGoString = (s: string): string => { + let out = '"' + for (let i = 0; i < s.length; i++) { + const code = s.charCodeAt(i) + + if (code === 0x22) { + out += '\\"' + continue + } + if (code === 0x5c) { + out += "\\\\" + continue + } + if (code === 0x08) { + out += "\\b" + continue + } + if (code === 0x0c) { + out += "\\f" + continue + } + if (code === 0x0a) { + out += "\\n" + continue + } + if (code === 0x0d) { + out += "\\r" + continue + } + if (code === 0x09) { + out += "\\t" + continue + } + if (code < 0x20) { + out += unicodeEscape(code) + continue + } + if (code === 0x2028 || code === 0x2029) { + out += unicodeEscape(code) + continue + } + + // Surrogate handling. A valid pair passes through as-is; a LONE surrogate + // becomes a single U+FFFD. + // + // Verified against Go 1.26.5. Go's DECODER already replaces a `\uD800` + // escape with one U+FFFD (bytes ef bf bd) at decode time, so by the time a + // value reaches the encoder the lone surrogate is gone. Every string in + // this pipeline arrives via parseJson, so one U+FFFD is the correct and + // reachable behavior. + // + // (Go's ENCODER separately maps each invalid UTF-8 *byte* to U+FFFD, which + // turns raw WTF-8 bytes into three U+FFFD — but raw bytes never enter this + // pipeline, so that path is deliberately not reproduced.) + if (code >= 0xd800 && code <= 0xdbff) { + const next = i + 1 < s.length ? s.charCodeAt(i + 1) : 0 + if (next >= 0xdc00 && next <= 0xdfff) { + out += s[i]! + s[i + 1]! + i++ + } else { + out += "�" + } + continue + } + if (code >= 0xdc00 && code <= 0xdfff) { + out += "�" + continue + } + + out += s[i]! + } + return out + '"' +} + +const encodeValue = (value: JsonValue, indent: string, depth: number): string => { + if (value === null) return "null" + if (typeof value === "boolean") return value ? "true" : "false" + if (typeof value === "string") return encodeGoString(value) + if (isRawNumber(value)) return value.$rawNumber + + const nl = indent === "" ? "" : "\n" + const pad = indent === "" ? "" : indent.repeat(depth + 1) + const padEnd = indent === "" ? "" : indent.repeat(depth) + const sep = indent === "" ? "," : ",\n" + const colon = indent === "" ? ":" : ": " + + if (isJsonArray(value)) { + if (value.length === 0) return "[]" + const parts = value.map((v) => pad + encodeValue(v, indent, depth + 1)) + return `[${nl}${parts.join(sep)}${nl}${padEnd}]` + } + + if (isJsonObject(value)) { + const keys = Object.keys(value).sort(compareUtf8) + if (keys.length === 0) return "{}" + const parts = keys.map( + (k) => pad + encodeGoString(k) + colon + encodeValue(value[k]!, indent, depth + 1) + ) + return `{${nl}${parts.join(sep)}${nl}${padEnd}}` + } + + return "null" +} + +/** Encode with every object's keys sorted at every depth (Go map marshalling). */ +export const encodeGoValue = (value: JsonValue, options: EncodeOptions): string => + encodeValue(value, options.indent, 0) + +/** + * Encode an object preserving the given entry order (Go struct marshalling). + * Nested values still get `encodeGoValue`'s sorted-key treatment. + */ +export const encodeGoStruct = ( + entries: ReadonlyArray, + options: EncodeOptions +): string => { + if (entries.length === 0) return "{}" + const { indent } = options + const nl = indent === "" ? "" : "\n" + const pad = indent + const sep = indent === "" ? "," : ",\n" + const colon = indent === "" ? ":" : ": " + const parts = entries.map( + ([k, v]) => pad + encodeGoString(k) + colon + encodeValue(v, indent, 1) + ) + return `{${nl}${parts.join(sep)}${nl}}` +} diff --git a/src/json/parse.ts b/src/json/parse.ts new file mode 100644 index 0000000..020b780 --- /dev/null +++ b/src/json/parse.ts @@ -0,0 +1,62 @@ +/** + * Number-preserving JSON parse — the TypeScript equivalent of Go's + * `json.Decoder` with `UseNumber()`. + * + * Uses the ES2025 `source` reviver argument, verified present in Bun 1.3.14. + * Every JSON number becomes a `RawNumber` carrying its ORIGINAL source text, + * so `9007199254740993123`, `1.50`, `1e3` and `-0` all survive a + * parse -> encode round-trip byte-for-byte. + */ + +import { Data, Effect, Result } from "effect" +import { type JsonValue, rawNumber } from "./value.ts" + +export class JsonParseError extends Data.TaggedError("JsonParseError")<{ + readonly message: string +}> {} + +interface ReviverContext { + readonly source?: string | undefined +} + +type Reviver = (this: unknown, key: string, value: unknown, context?: ReviverContext) => unknown + +const reviver: Reviver = (_key, value, context) => + typeof value === "number" && context !== undefined && typeof context.source === "string" + ? rawNumber(context.source) + : value + +/** + * Fail loudly at module load if the runtime lacks the `source` reviver, rather + * than silently degrading to lossy numbers at some later point in the data path. + */ +const assertSourceReviverSupported = (): void => { + let seen: string | undefined + JSON.parse("1.50", ((_k: string, _v: unknown, ctx?: ReviverContext) => { + seen = ctx?.source + return _v + }) as Reviver) + if (seen !== "1.50") { + throw new Error( + "runtime does not support the JSON `source` reviver argument; " + + "numeric literals would be corrupted (requires Bun >= 1.3 / ES2025)" + ) + } +} + +assertSourceReviverSupported() + +export const parseJson = (text: string): Result.Result => { + try { + return Result.succeed(JSON.parse(text, reviver as Reviver) as JsonValue) + } catch (cause) { + return Result.fail( + new JsonParseError({ + message: cause instanceof Error ? cause.message : String(cause) + }) + ) + } +} + +export const parseJsonEffect = (text: string): Effect.Effect => + Effect.fromResult(parseJson(text)) diff --git a/src/json/value.ts b/src/json/value.ts new file mode 100644 index 0000000..308b7de --- /dev/null +++ b/src/json/value.ts @@ -0,0 +1,55 @@ +/** + * JSON value model that preserves numeric literals exactly. + * + * Go's decoder runs with `UseNumber()`, so every JSON number keeps its original + * source text and is re-emitted verbatim. YouTube returns counters beyond + * 2^53 (a Go test feeds `9007199254740993123`), which JS `number` silently + * corrupts. `RawNumber` carries the literal text instead. + * + * `RawNumber` is deliberately a distinct object type, not a branded string: + * that makes `String(rawNumber)` or arithmetic on it a *type* error rather + * than a silent `"[object Object]"` at runtime. + */ + +export interface RawNumber { + readonly $rawNumber: string +} + +export const rawNumber = (literal: string): RawNumber => ({ $rawNumber: literal }) + +export const isRawNumber = (u: unknown): u is RawNumber => + typeof u === "object" && + u !== null && + typeof (u as RawNumber).$rawNumber === "string" && + Object.keys(u as object).length === 1 + +export type JsonValue = + | string + | boolean + | null + | RawNumber + | ReadonlyArray + | { readonly [key: string]: JsonValue } + +export type JsonObject = { readonly [key: string]: JsonValue } + +export type JsonArray = ReadonlyArray + +export const isJsonObject = (u: JsonValue): u is JsonObject => + typeof u === "object" && u !== null && !Array.isArray(u) && !isRawNumber(u) + +export const isJsonArray = (u: JsonValue): u is JsonArray => Array.isArray(u) + +/** Go's `json.Number.String()` — the original literal text. */ +export const rawLiteral = (n: RawNumber): string => n.$rawNumber + +/** + * Narrow a `RawNumber` to a JS number. Only for the few places a real number is + * needed for arithmetic (e.g. `pollingIntervalMillis`), never for output. + * Returns `undefined` for anything that is not a finite numeric literal. + */ +export const rawToNumber = (u: unknown): number | undefined => { + if (!isRawNumber(u)) return undefined + const n = Number(u.$rawNumber) + return Number.isFinite(n) ? n : undefined +} diff --git a/src/util/gostring.ts b/src/util/gostring.ts new file mode 100644 index 0000000..72ba92d --- /dev/null +++ b/src/util/gostring.ts @@ -0,0 +1,36 @@ +/** + * Go string semantics that differ from JavaScript defaults. + */ + +/** + * Compare two strings by their UTF-8 byte sequences, which is what Go's + * `sort.Strings` (and therefore `encoding/json`'s map-key ordering) does. + * + * JavaScript's `<` compares UTF-16 code units, which disagrees with UTF-8 byte + * order whenever an astral-plane character (encoded as a surrogate pair, + * 0xD800-0xDFFF) is compared against U+E000-U+FFFF. Comparing by code point + * reproduces UTF-8 byte order exactly, because UTF-8 encoding is + * order-preserving over code points. + */ +export const compareUtf8 = (a: string, b: string): number => { + if (a === b) return 0 + const aCodes = Array.from(a, (c) => c.codePointAt(0) ?? 0) + const bCodes = Array.from(b, (c) => c.codePointAt(0) ?? 0) + const len = Math.min(aCodes.length, bCodes.length) + for (let i = 0; i < len; i++) { + const x = aCodes[i]! + const y = bCodes[i]! + if (x !== y) return x < y ? -1 : 1 + } + return aCodes.length === bCodes.length ? 0 : aCodes.length < bCodes.length ? -1 : 1 +} + +/** + * Number of Unicode code points ("runes" in Go), not UTF-16 code units. + * Go's text/tabwriter measures cell widths in runes. + */ +export const runeLength = (s: string): number => Array.from(s).length + +/** Sort a copy of `keys` in Go map-marshal order. */ +export const sortKeysUtf8 = (keys: ReadonlyArray): ReadonlyArray => + [...keys].sort(compareUtf8) diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..ed2492a --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,18 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "nodenext", + "moduleResolution": "nodenext", + "strict": true, + "exactOptionalPropertyTypes": true, + "noUncheckedIndexedAccess": true, + "skipLibCheck": true, + "noEmit": true, + "allowImportingTsExtensions": true, + "verbatimModuleSyntax": true, + "lib": ["ES2022", "DOM"], + "types": ["bun"], + "plugins": [{ "name": "@effect/language-service" }] + }, + "include": ["src/**/*.ts"] +} From 699879f7a454180ef4039d096ce2b898a96486f6 Mon Sep 17 00:00:00 2001 From: Benjamin Davis Date: Fri, 24 Jul 2026 22:47:34 -0700 Subject: [PATCH 2/6] feat(ts): complete the P0 contract layer Everything the parallel implementation packages code against. Signatures here are frozen: changing one invalidates work in flight elsewhere. - domain/errors.ts: the tagged error ADT, each variant carrying its exit code via Runtime.errorExitCode (verified to drive process exit through a compiled binary) - domain/listResult.ts: the list envelope, with Go's two simultaneous key orders (fixed struct order outside, sorted maps within) - schema/: deliberately loose Data API decoding plus the seven narrow accessors that cover every nested read the Go code performs - services/index.ts: 15 service tags and interfaces - cli/root.ts: the root command and global-flag resolution - impl/processEnv.ts: the only place process.* is touched - stubs for every impl/, output/, and cli/ module so parallel packages own strictly disjoint files Applies DEVIATIONS.md D1b: one reason normalization is used for every test in the exit-code table, so RATE_LIMIT_EXCEEDED and QUOTA_EXCEEDED now classify as quota (5) instead of falling through to 6. Ordering is preserved, so a quota-carrying 403 still exits 5 and a bare 403 exits 4. Per-resource schemas are deliberately absent: --parts and --fields let users request arbitrary field subsets, so any fixed Video/Channel schema would reject responses the Go client accepts. 124 tests pass; TypeScript 7.0.2 typechecks clean under strict and exactOptionalPropertyTypes; `bun run src/main.ts --help` works. Co-Authored-By: Claude Opus 5 (1M context) --- src/cli/analyticsCmd.ts | 2 + src/cli/auth.ts | 2 + src/cli/catalog.ts | 2 + src/cli/channel.ts | 2 + src/cli/comment.ts | 2 + src/cli/fields.ts | 2 + src/cli/flags.ts | 47 ++++++ src/cli/globals.ts | 68 ++++++++ src/cli/livechat.ts | 2 + src/cli/playlist.ts | 2 + src/cli/render.ts | 2 + src/cli/root.ts | 52 ++++++ src/cli/search.ts | 2 + src/cli/skillsCmd.ts | 2 + src/cli/subscription.ts | 2 + src/cli/validate.ts | 2 + src/cli/versionUpdate.ts | 2 + src/cli/video.ts | 2 + src/domain/errors.test.ts | 173 ++++++++++++++++++++ src/domain/errors.ts | 244 ++++++++++++++++++++++++++++ src/domain/listResult.ts | 63 ++++++++ src/impl/analyticsApi.ts | 2 + src/impl/archive.ts | 2 + src/impl/atomicWrite.ts | 2 + src/impl/browserOpener.ts | 2 + src/impl/credentialStore.ts | 2 + src/impl/fileLock.ts | 2 + src/impl/httpCore.ts | 2 + src/impl/oauth.ts | 2 + src/impl/oauthServer.ts | 2 + src/impl/platformMatrix.ts | 2 + src/impl/processEnv.ts | 33 ++++ src/impl/prompts.ts | 2 + src/impl/renderer.ts | 2 + src/impl/resolveChannel.ts | 2 + src/impl/semver.ts | 2 + src/impl/skillInstaller.ts | 2 + src/impl/tokenSource.ts | 2 + src/impl/updater.ts | 2 + src/impl/versionInfo.ts | 2 + src/impl/youtubeApi.ts | 2 + src/layers.ts | 14 ++ src/main.ts | 25 +++ src/output/columns.ts | 2 + src/output/jsonOut.ts | 2 + src/output/table.ts | 2 + src/output/tsv.ts | 2 + src/schema/accessors.ts | 73 +++++++++ src/schema/analytics.ts | 25 +++ src/schema/dataapi.ts | 29 ++++ src/services/index.ts | 315 ++++++++++++++++++++++++++++++++++++ src/util/goduration.test.ts | 42 +++++ src/util/goduration.ts | 72 +++++++++ 53 files changed, 1351 insertions(+) create mode 100644 src/cli/analyticsCmd.ts create mode 100644 src/cli/auth.ts create mode 100644 src/cli/catalog.ts create mode 100644 src/cli/channel.ts create mode 100644 src/cli/comment.ts create mode 100644 src/cli/fields.ts create mode 100644 src/cli/flags.ts create mode 100644 src/cli/globals.ts create mode 100644 src/cli/livechat.ts create mode 100644 src/cli/playlist.ts create mode 100644 src/cli/render.ts create mode 100644 src/cli/root.ts create mode 100644 src/cli/search.ts create mode 100644 src/cli/skillsCmd.ts create mode 100644 src/cli/subscription.ts create mode 100644 src/cli/validate.ts create mode 100644 src/cli/versionUpdate.ts create mode 100644 src/cli/video.ts create mode 100644 src/domain/errors.test.ts create mode 100644 src/domain/errors.ts create mode 100644 src/domain/listResult.ts create mode 100644 src/impl/analyticsApi.ts create mode 100644 src/impl/archive.ts create mode 100644 src/impl/atomicWrite.ts create mode 100644 src/impl/browserOpener.ts create mode 100644 src/impl/credentialStore.ts create mode 100644 src/impl/fileLock.ts create mode 100644 src/impl/httpCore.ts create mode 100644 src/impl/oauth.ts create mode 100644 src/impl/oauthServer.ts create mode 100644 src/impl/platformMatrix.ts create mode 100644 src/impl/processEnv.ts create mode 100644 src/impl/prompts.ts create mode 100644 src/impl/renderer.ts create mode 100644 src/impl/resolveChannel.ts create mode 100644 src/impl/semver.ts create mode 100644 src/impl/skillInstaller.ts create mode 100644 src/impl/tokenSource.ts create mode 100644 src/impl/updater.ts create mode 100644 src/impl/versionInfo.ts create mode 100644 src/impl/youtubeApi.ts create mode 100644 src/layers.ts create mode 100644 src/main.ts create mode 100644 src/output/columns.ts create mode 100644 src/output/jsonOut.ts create mode 100644 src/output/table.ts create mode 100644 src/output/tsv.ts create mode 100644 src/schema/accessors.ts create mode 100644 src/schema/analytics.ts create mode 100644 src/schema/dataapi.ts create mode 100644 src/services/index.ts create mode 100644 src/util/goduration.test.ts create mode 100644 src/util/goduration.ts diff --git a/src/cli/analyticsCmd.ts b/src/cli/analyticsCmd.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/analyticsCmd.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/auth.ts b/src/cli/auth.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/auth.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/catalog.ts b/src/cli/catalog.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/catalog.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/channel.ts b/src/cli/channel.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/channel.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/comment.ts b/src/cli/comment.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/comment.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/fields.ts b/src/cli/fields.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/fields.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/flags.ts b/src/cli/flags.ts new file mode 100644 index 0000000..501e4d0 --- /dev/null +++ b/src/cli/flags.ts @@ -0,0 +1,47 @@ +/** + * Shared flag definitions. + * + * Global flags are attached with `Command.withSharedFlags`, which is the only + * mechanism that makes them visible to subcommands AND available to + * `Command.provide`. See root.ts for the mandatory composition order. + */ + +import type { Option } from "effect" +import { Flag } from "../effect.ts" +import type { OutputFormat } from "../services/index.ts" + +export const FORMATS = ["table", "json", "jsonl", "tsv"] as const + +/** + * `--format` is optional rather than defaulted: the effective default depends + * on whether stdout is a TTY (table) or a pipe (json), and `live-chat stream` + * overrides it to jsonl. Resolution happens in resolveGlobals(). + */ +export const globalFlags = { + format: Flag.choice("format", FORMATS).pipe( + Flag.withDescription("Output format (default: table on a terminal, json when piped)"), + Flag.optional + ), + columns: Flag.string("columns").pipe( + Flag.withDescription("Comma-separated column paths to display"), + Flag.optional + ), + noHeader: Flag.boolean("no-header").pipe( + Flag.withDescription("Omit the header row in table and tsv output") + ), + quiet: Flag.boolean("quiet").pipe( + Flag.withDescription("Suppress the request-count summary on stderr") + ), + timeout: Flag.string("timeout").pipe( + Flag.withDescription("Request timeout, e.g. 20s or 1m30s"), + Flag.withDefault("20s") + ) +} + +export interface GlobalFlagValues { + readonly format: Option.Option + readonly columns: Option.Option + readonly noHeader: boolean + readonly quiet: boolean + readonly timeout: string +} diff --git a/src/cli/globals.ts b/src/cli/globals.ts new file mode 100644 index 0000000..78b8eb5 --- /dev/null +++ b/src/cli/globals.ts @@ -0,0 +1,68 @@ +/** + * Resolution of the global flags into the AppOptions service value. + */ + +import { Option, Result } from "effect" +import { UsageError } from "../domain/errors.ts" +import { parseGoDuration } from "../util/goduration.ts" +import type { AppOptionsShape, OutputFormat } from "../services/index.ts" +import type { GlobalFlagValues } from "./flags.ts" + +/** + * cobra's StringSliceVar semantics: comma-separated, with double-quoted + * segments allowed to contain commas. + */ +export const parseCsv = (input: string): ReadonlyArray => { + const out: Array = [] + let current = "" + let inQuotes = false + for (let i = 0; i < input.length; i++) { + const ch = input[i]! + if (ch === '"') { + inQuotes = !inQuotes + continue + } + if (ch === "," && !inQuotes) { + out.push(current) + current = "" + continue + } + current += ch + } + out.push(current) + return out.filter((s) => s !== "") +} + +export interface ResolveGlobalsOptions { + readonly isOutputTTY: boolean + /** `live-chat stream` forces jsonl when the user did not pass --format. */ + readonly defaultFormat?: OutputFormat | undefined +} + +export const resolveGlobals = ( + flags: GlobalFlagValues, + options: ResolveGlobalsOptions +): Result.Result => { + const timeout = parseGoDuration(flags.timeout) + if (Result.isFailure(timeout)) { + return Result.fail(new UsageError({ message: timeout.failure.message })) + } + if (timeout.success <= 0) { + return Result.fail(new UsageError({ message: "--timeout must be greater than zero" })) + } + + const fallback: OutputFormat = + options.defaultFormat ?? (options.isOutputTTY ? "table" : "json") + + return Result.succeed({ + format: Option.getOrElse(flags.format, () => fallback), + columns: Option.match(flags.columns, { + onNone: () => [] as ReadonlyArray, + onSome: parseCsv + }), + noHeader: flags.noHeader, + quiet: flags.quiet, + timeoutMillis: timeout.success, + isOutputTTY: options.isOutputTTY + }) +} diff --git a/src/cli/livechat.ts b/src/cli/livechat.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/livechat.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/playlist.ts b/src/cli/playlist.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/playlist.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/render.ts b/src/cli/render.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/render.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/root.ts b/src/cli/root.ts new file mode 100644 index 0000000..4e8a4d3 --- /dev/null +++ b/src/cli/root.ts @@ -0,0 +1,52 @@ +/** + * The root command. + * + * COMPOSITION ORDER IS MANDATORY AND VERIFIED: + * + * 1. Command.withSharedFlags(globalFlags) -> flags land in BOTH Input and + * ContextInput, making them + * visible to every subcommand + * 2. Command.withSubcommands([...]) -> subcommand Input becomes + * Input | ContextInput + * 3. Command.provide(input => layer) -> sees the union; both arms + * carry the shared flags + * + * Any other order fails. `provide` before `withSubcommands` does not typecheck + * ("Type 'AppOptionsShape' is not assignable to type 'never'") and fails at + * runtime with "Service not found: oytc/AppOptions". Declaring the globals via + * `Command.make("oytc", {flags})` instead of withSharedFlags makes subcommands + * reject them outright ("Unrecognized flag: --format"). + */ + +import { Effect, Layer, Result } from "effect" +import { Command } from "../effect.ts" +import { AppOptions, ProcessEnv } from "../services/index.ts" +import { globalFlags } from "./flags.ts" +import { resolveGlobals } from "./globals.ts" + +const DESCRIPTION = + "Read public YouTube data and your own channel analytics from the command line." + +/** + * Subcommands are registered here as they are implemented. Each entry comes + * from its own module, so parallel packages never edit this list concurrently + * beyond adding their own import. + */ +const subcommands: ReadonlyArray = [] + +export const root = Command.make("oytc").pipe( + Command.withDescription(DESCRIPTION), + Command.withSharedFlags(globalFlags), + Command.withSubcommands(subcommands), + Command.provide((input) => + Layer.effect( + AppOptions, + Effect.gen(function* () { + const env = yield* ProcessEnv + const resolved = resolveGlobals(input, { isOutputTTY: env.isOutputTTY }) + if (Result.isFailure(resolved)) return yield* Effect.fail(resolved.failure) + return resolved.success + }) + ) + ) +) diff --git a/src/cli/search.ts b/src/cli/search.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/search.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/skillsCmd.ts b/src/cli/skillsCmd.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/skillsCmd.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/subscription.ts b/src/cli/subscription.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/subscription.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/validate.ts b/src/cli/validate.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/validate.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/versionUpdate.ts b/src/cli/versionUpdate.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/versionUpdate.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/cli/video.ts b/src/cli/video.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/cli/video.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/domain/errors.test.ts b/src/domain/errors.test.ts new file mode 100644 index 0000000..e7266fe --- /dev/null +++ b/src/domain/errors.test.ts @@ -0,0 +1,173 @@ +import { describe, expect, test } from "bun:test" +import { + ApiError, + apiExitCode, + CancelledError, + exitCodeFor, + exitCodeForMessage, + MissingKeyError, + MissingOAuthError, + NotFoundError, + OAuthError, + OperationalError, + statusText, + UsageError +} from "./errors.ts" + +const api = (httpStatus: number, reasons: ReadonlyArray = []) => + new ApiError({ httpStatus, code: httpStatus, apiMessage: "msg", reasons }) + +describe("ApiError exit codes", () => { + test.each([ + [401, [], 3, "401 is auth regardless of reasons"], + [400, ["keyInvalid"], 3, "keyInvalid"], + [400, ["key_invalid"], 3, "underscore stripped"], + [400, ["key-invalid"], 3, "dash stripped"], + [400, ["API_KEY_INVALID"], 3, "screaming snake"], + [403, ["accessNotConfigured"], 3, "accessNotConfigured"], + [403, ["insufficientPermissions"], 3, "insufficientPermissions"], + [404, [], 4, "not found"], + [404, ["quotaExceeded"], 4, "404 wins over quota (ordering)"], + [429, [], 5, "429 is rate limit"], + [403, ["quotaExceeded"], 5, "quota 403 beats bare 403"], + [403, [], 4, "bare 403 is forbidden"], + [500, [], 6, "upstream"], + [503, [], 6, "upstream"], + [400, [], 6, "unclassified"] + ])("status %d reasons %o -> %d (%s)", (status, reasons, expected) => { + expect(apiExitCode({ httpStatus: status, reasons })).toBe(expected) + }) + + // DEVIATIONS.md D1b — one normalization applied to every reason test. + // Go used the un-normalized string for the quota check, so these three + // fell through to 6. + describe("D1b: consistent reason normalization", () => { + test.each([ + ["RATE_LIMIT_EXCEEDED", 5], + ["rate-limit-exceeded", 5], + ["QUOTA_EXCEEDED", 5], + ["quota_exceeded", 5] + ])("%s -> %d (was 6 in Go)", (reason, expected) => { + expect(apiExitCode({ httpStatus: 400, reasons: [reason] })).toBe(expected) + }) + + test.each([ + ["userRateLimitExceeded", 5], + ["quotaExceeded", 5] + ])("%s -> %d (unchanged from Go)", (reason, expected) => { + expect(apiExitCode({ httpStatus: 400, reasons: [reason] })).toBe(expected) + }) + + test("dailyLimitExceeded still does not match (unchanged, out of scope)", () => { + expect(apiExitCode({ httpStatus: 400, reasons: ["dailyLimitExceeded"] })).toBe(6) + }) + }) +}) + +describe("error messages", () => { + test("ApiError with reasons", () => { + expect( + new ApiError({ + httpStatus: 403, + code: 403, + apiMessage: "Quota exceeded.", + reasons: ["quotaExceeded", "dailyLimitExceeded"] + }).message + ).toBe("YouTube API error (403, quotaExceeded, dailyLimitExceeded): Quota exceeded.") + }) + + test("ApiError without reasons", () => { + expect( + new ApiError({ httpStatus: 500, code: 500, apiMessage: "Boom", reasons: [] }).message + ).toBe("YouTube API error (500): Boom") + }) + + test("ApiError prints envelope code, not http status", () => { + expect( + new ApiError({ httpStatus: 400, code: 403, apiMessage: "x", reasons: [] }).message + ).toBe("YouTube API error (403): x") + }) + + test("MissingKeyError", () => { + expect(new MissingKeyError().message).toBe( + "no API key configured; run 'oytc login' or set OYTC_API_KEY" + ) + }) + + test("MissingOAuthError plain and with analytics suffix", () => { + expect(new MissingOAuthError({}).message).toBe( + "no OAuth credentials configured; run 'oytc login --oauth'" + ) + expect( + new MissingOAuthError({ suffix: "; analytics requires OAuth" }).message + ).toBe("no OAuth credentials configured; run 'oytc login --oauth'; analytics requires OAuth") + }) + + test("OAuthError with and without description", () => { + expect( + new OAuthError({ httpStatus: 400, code: "invalid_grant", description: "expired" }).message + ).toBe("OAuth error (invalid_grant): expired") + expect(new OAuthError({ httpStatus: 400, code: "", description: "" }).message).toBe( + "OAuth error (unknown)" + ) + }) +}) + +describe("OAuthError exit codes", () => { + test.each([ + ["server_error", 500, 6], + ["temporarily_unavailable", 503, 6], + ["invalid_grant", 429, 5], + ["invalid_grant", 500, 6], + ["invalid_grant", 400, 3], + ["", 400, 3] + ])("code=%s status=%d -> %d", (code, httpStatus, expected) => { + expect(exitCodeFor(new OAuthError({ httpStatus, code, description: "" }))).toBe(expected) + }) +}) + +describe("exitCodeFor across the ADT", () => { + test.each([ + [new UsageError({ message: "bad" }), 2], + [new MissingKeyError(), 3], + [new MissingOAuthError({}), 3], + [new NotFoundError({ message: "video not found" }), 4], + [new OperationalError({ message: "network down" }), 6], + [new CancelledError(), 130], + [api(429), 5] + ])("%o -> %d", (err, expected) => { + expect(exitCodeFor(err)).toBe(expected) + }) +}) + +describe("message-substring fallbacks", () => { + test.each([ + ["oauth invalid_grant here", 3], + ["please re-run 'oytc login --oauth'", 3], + ["unknown command \"foo\"", 2], + ["unknown flag: --bar", 2], + ["channel not found", 4], + ["no active public live chat", 4], + ["channel has no public uploads playlist", 4], + ["something else entirely", 6] + ])("%s -> %d", (message, expected) => { + expect(exitCodeForMessage(message)).toBe(expected) + }) +}) + +describe("statusText", () => { + test.each([ + [403, "Forbidden"], + [429, "Too Many Requests"], + [503, "Service Unavailable"], + [500, "Internal Server Error"], + [404, "Not Found"], + [401, "Unauthorized"] + ])("%d -> %s", (status, expected) => { + expect(statusText(status)).toBe(expected) + }) + + test("unrecognised status yields empty string, not an invented phrase", () => { + expect(statusText(599)).toBe("") + }) +}) diff --git a/src/domain/errors.ts b/src/domain/errors.ts new file mode 100644 index 0000000..8eed551 --- /dev/null +++ b/src/domain/errors.ts @@ -0,0 +1,244 @@ +/** + * The error ADT. Each variant carries its own process exit code via + * `Runtime.errorExitCode`, which `BunRuntime.runMain` reads off the squashed + * error — verified end-to-end, including through a compiled binary. + * + * Exit code meanings (from docs/commands.md): + * 0 success + * 2 usage / validation error + * 3 missing or invalid API key / OAuth authorization + * 4 resource unavailable, not found, or forbidden + * 5 quota or rate limit + * 6 network, temporary upstream, config, or other operational failure + * 130 interrupted + */ + +import { Data, Runtime } from "effect" + +/** HTTP status -> canonical reason phrase, matching Go's http.StatusText. */ +const STATUS_TEXT: Readonly> = { + 400: "Bad Request", + 401: "Unauthorized", + 403: "Forbidden", + 404: "Not Found", + 405: "Method Not Allowed", + 408: "Request Timeout", + 409: "Conflict", + 410: "Gone", + 429: "Too Many Requests", + 500: "Internal Server Error", + 501: "Not Implemented", + 502: "Bad Gateway", + 503: "Service Unavailable", + 504: "Gateway Timeout" +} + +/** Go's http.StatusText returns "" for unrecognised codes; do not invent one. */ +export const statusText = (status: number): string => STATUS_TEXT[status] ?? "" + +export class UsageError extends Data.TaggedError("UsageError")<{ + readonly message: string +}> { + readonly [Runtime.errorExitCode] = 2 + readonly [Runtime.errorReported] = false +} + +export class MissingKeyError extends Data.TaggedError("MissingKeyError")<{}> { + readonly [Runtime.errorExitCode] = 3 + readonly [Runtime.errorReported] = false + get message(): string { + return "no API key configured; run 'oytc login' or set OYTC_API_KEY" + } +} + +export class MissingOAuthError extends Data.TaggedError("MissingOAuthError")<{ + /** analytics appends "; analytics requires OAuth" */ + readonly suffix?: string | undefined +}> { + readonly [Runtime.errorExitCode] = 3 + readonly [Runtime.errorReported] = false + get message(): string { + return `no OAuth credentials configured; run 'oytc login --oauth'${this.suffix ?? ""}` + } +} + +export class ApiError extends Data.TaggedError("ApiError")<{ + readonly httpStatus: number + /** envelope error.code, falling back to httpStatus when absent/zero */ + readonly code: number + /** envelope error.message, falling back to the canonical status text */ + readonly apiMessage: string + /** errors[].reason then details[].reason; empties skipped, duplicates kept */ + readonly reasons: ReadonlyArray +}> { + readonly [Runtime.errorReported] = false + get message(): string { + return this.reasons.length > 0 + ? `YouTube API error (${this.code}, ${this.reasons.join(", ")}): ${this.apiMessage}` + : `YouTube API error (${this.code}): ${this.apiMessage}` + } + get [Runtime.errorExitCode](): number { + return apiExitCode(this) + } +} + +export class OAuthError extends Data.TaggedError("OAuthError")<{ + readonly httpStatus: number + readonly code: string + readonly description: string +}> { + readonly [Runtime.errorReported] = false + get message(): string { + const code = this.code === "" ? "unknown" : this.code + return this.description === "" + ? `OAuth error (${code})` + : `OAuth error (${code}): ${this.description}` + } + get [Runtime.errorExitCode](): number { + if (this.code === "server_error" || this.code === "temporarily_unavailable") return 6 + if (this.httpStatus === 429) return 5 + if (this.httpStatus >= 500) return 6 + return 3 + } +} + +export type AuthHintPrefix = + | "OAuth authorization failed; re-run 'oytc login --oauth'" + | "OAuth scopes are insufficient; re-run 'oytc login --oauth'" + +/** Wrapper produced by oauthAuthHint(); preserves the cause for classification. */ +export class AuthHintError extends Data.TaggedError("AuthHintError")<{ + readonly prefix: AuthHintPrefix + readonly cause: OytcError +}> { + readonly [Runtime.errorExitCode] = 3 + readonly [Runtime.errorReported] = false + get message(): string { + return `${this.prefix}: ${flattenMessage(this.cause)}` + } +} + +export class NotFoundError extends Data.TaggedError("NotFoundError")<{ + readonly message: string +}> { + readonly [Runtime.errorExitCode] = 4 + readonly [Runtime.errorReported] = false +} + +export class OperationalError extends Data.TaggedError("OperationalError")<{ + readonly message: string + readonly cause?: unknown +}> { + readonly [Runtime.errorExitCode] = 6 + readonly [Runtime.errorReported] = false +} + +export class CancelledError extends Data.TaggedError("CancelledError")<{}> { + readonly [Runtime.errorExitCode] = 130 + readonly [Runtime.errorReported] = false + get message(): string { + return "context canceled" + } +} + +export type OytcError = + | UsageError + | MissingKeyError + | MissingOAuthError + | ApiError + | OAuthError + | AuthHintError + | NotFoundError + | OperationalError + | CancelledError + +/** + * Exit code for an ApiError. + * + * DEVIATIONS.md D1b: Go applied two different normalizations to the same + * reasons string in one decision table — the auth test stripped `_`/`-` while + * the quota test did not, so `RATE_LIMIT_EXCEEDED` fell through to 6 while + * `userRateLimitExceeded` correctly hit 5. Google returns SCREAMING_SNAKE + * reasons in newer API surfaces, so that miss was real. + * + * Here one normalization is applied to EVERY reason test. Consequences: + * RATE_LIMIT_EXCEEDED -> 5 (was 6) + * rate-limit-exceeded -> 5 (was 6) + * QUOTA_EXCEEDED -> 5 (was 6) + * userRateLimitExceeded, quotaExceeded -> 5 (unchanged) + * dailyLimitExceeded -> unmatched (unchanged; contains neither substring) + * + * Ordering is preserved: quota is tested before the bare-403 rule, so a 403 + * carrying a quota reason still exits 5 while a bare 403 exits 4. That + * specific-before-general precedence is correct and deliberate. + */ +export const apiExitCode = (e: { + readonly httpStatus: number + readonly reasons: ReadonlyArray +}): number => { + const normalized = e.reasons.join(",").toLowerCase().replaceAll("_", "").replaceAll("-", "") + + if ( + normalized.includes("keyinvalid") || + normalized.includes("apikeyinvalid") || + normalized.includes("accessnotconfigured") || + normalized.includes("insufficientpermissions") || + e.httpStatus === 401 + ) { + return 3 + } + if (e.httpStatus === 404) return 4 + if (e.httpStatus === 429 || normalized.includes("quota") || normalized.includes("ratelimit")) { + return 5 + } + if (e.httpStatus === 403) return 4 + if (e.httpStatus >= 500) return 6 + return 6 +} + +/** Go's %w chain flattened to a single line, as the stderr printer emits it. */ +export const flattenMessage = (e: OytcError): string => e.message + +/** + * The full first-match-wins classifier, mirroring Go's exitCode(err). + * Individual error classes carry their own code; this exists for the tests + * and for classifying errors that reach main.ts without a code attached. + */ +export const exitCodeFor = (e: OytcError): number => { + switch (e._tag) { + case "UsageError": + return 2 + case "MissingKeyError": + case "MissingOAuthError": + case "AuthHintError": + return 3 + case "OAuthError": + return e[Runtime.errorExitCode] + case "ApiError": + return apiExitCode(e) + case "NotFoundError": + return 4 + case "CancelledError": + return 130 + case "OperationalError": + return 6 + } +} + +/** + * Substring heuristics Go applies to errors that are not one of the structured + * types. Kept separate so the structured path stays exact. + */ +export const exitCodeForMessage = (message: string): number => { + const lower = message.toLowerCase() + if (lower.includes("invalid_grant") || lower.includes("re-run 'oytc login --oauth'")) return 3 + if (lower.includes("unknown command") || lower.includes("unknown flag")) return 2 + if ( + lower.includes("not found") || + lower.includes("no active public live chat") || + lower.includes("no public uploads") + ) { + return 4 + } + return 6 +} diff --git a/src/domain/listResult.ts b/src/domain/listResult.ts new file mode 100644 index 0000000..1b0e4ed --- /dev/null +++ b/src/domain/listResult.ts @@ -0,0 +1,63 @@ +/** + * The list envelope shared by every paginated command. + * + * JSON key ordering follows Go's struct-field order — `items`, then + * `nextPageToken` (omitted entirely when empty), then `requests` (always + * present, even at 0). Nested objects inside `items` are sorted alphabetically + * at every depth, because Go marshals maps sorted. Both rules apply at once. + */ + +import { encodeGoStruct, encodeGoValue } from "../json/encode.ts" +import type { JsonObject, JsonValue } from "../json/value.ts" +import { rawNumber } from "../json/value.ts" + +export interface ListResult { + /** Never null; an empty array when the response carried no items. */ + readonly items: ReadonlyArray + /** "" means: omit the key from the envelope. */ + readonly nextPageToken: string + readonly requests: number +} + +export const emptyListResult: ListResult = { + items: [], + nextPageToken: "", + requests: 0 +} + +const envelopeEntries = (r: ListResult): ReadonlyArray => { + const entries: Array = [["items", r.items]] + if (r.nextPageToken !== "") entries.push(["nextPageToken", r.nextPageToken]) + entries.push(["requests", rawNumber(String(r.requests))]) + return entries +} + +/** Pretty envelope with a trailing newline, as `--format json` emits. */ +export const encodeListResultJson = (r: ListResult): string => + `${encodeGoStruct(envelopeEntries(r), { indent: " " })}\n` + +/** + * One compact object per line, as `--format jsonl` emits. Produces zero bytes + * for an empty result — not an empty line. + */ +export const encodeListResultJsonl = (r: ListResult): string => + r.items.map((item) => `${encodeGoValue(item, { indent: "" })}\n`).join("") + +/** Pagination inputs shared by the client and the command layer. */ +export interface PageOptions { + readonly all: boolean + /** 0 means no cap. */ + readonly limit: number + /** 0 means: do not send maxResults. */ + readonly pageSize: number + /** "" means: do not send pageToken. */ + readonly pageToken: string + readonly filter?: ((item: JsonObject) => boolean) | undefined +} + +export const defaultPageOptions: PageOptions = { + all: false, + limit: 0, + pageSize: 0, + pageToken: "" +} diff --git a/src/impl/analyticsApi.ts b/src/impl/analyticsApi.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/analyticsApi.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/archive.ts b/src/impl/archive.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/archive.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/atomicWrite.ts b/src/impl/atomicWrite.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/atomicWrite.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/browserOpener.ts b/src/impl/browserOpener.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/browserOpener.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/credentialStore.ts b/src/impl/credentialStore.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/credentialStore.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/fileLock.ts b/src/impl/fileLock.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/fileLock.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/httpCore.ts b/src/impl/httpCore.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/httpCore.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/oauth.ts b/src/impl/oauth.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/oauth.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/oauthServer.ts b/src/impl/oauthServer.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/oauthServer.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/platformMatrix.ts b/src/impl/platformMatrix.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/platformMatrix.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/processEnv.ts b/src/impl/processEnv.ts new file mode 100644 index 0000000..f002062 --- /dev/null +++ b/src/impl/processEnv.ts @@ -0,0 +1,33 @@ +/** + * ProcessEnv — the single seam through which the rest of the code sees the + * host process. Keeping `process.*` here means everything else is testable + * with a mock layer. + */ + +import { Effect, Layer, Option } from "effect" +import { OperationalError } from "../domain/errors.ts" +import { ProcessEnv, type ProcessEnvShape } from "../services/index.ts" + +export const makeProcessEnv: ProcessEnvShape = { + env: (name) => Option.fromNullishOr(process.env[name]), + platform: process.platform, + arch: process.arch, + argv: process.argv, + executablePath: Effect.try({ + try: () => process.execPath, + catch: (cause) => + new OperationalError({ message: "could not determine executable path", cause }) + }), + isOutputTTY: process.stdout.isTTY === true, + homeDir: Effect.gen(function* () { + const home = process.env["HOME"] ?? process.env["USERPROFILE"] + if (home === undefined || home === "") { + return yield* Effect.fail( + new OperationalError({ message: "could not determine home directory" }) + ) + } + return home + }) +} + +export const ProcessEnvLive = Layer.succeed(ProcessEnv, makeProcessEnv) diff --git a/src/impl/prompts.ts b/src/impl/prompts.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/prompts.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/renderer.ts b/src/impl/renderer.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/renderer.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/resolveChannel.ts b/src/impl/resolveChannel.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/resolveChannel.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/semver.ts b/src/impl/semver.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/semver.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/skillInstaller.ts b/src/impl/skillInstaller.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/skillInstaller.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/tokenSource.ts b/src/impl/tokenSource.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/tokenSource.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/updater.ts b/src/impl/updater.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/updater.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/versionInfo.ts b/src/impl/versionInfo.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/versionInfo.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/impl/youtubeApi.ts b/src/impl/youtubeApi.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/impl/youtubeApi.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/layers.ts b/src/layers.ts new file mode 100644 index 0000000..0b45b88 --- /dev/null +++ b/src/layers.ts @@ -0,0 +1,14 @@ +/** + * The application Layer graph. + * + * Written once, in the foundation. Feature packages supply the `make*` + * functions in `src/impl/`; this wiring does not change as they land. + * + * `AppOptions` is deliberately NOT here — it is per-invocation and supplied by + * `Command.provide` in cli/root.ts, because it depends on parsed flags. + */ + +import { Layer } from "effect" +import { ProcessEnvLive } from "./impl/processEnv.ts" + +export const AppLayer = Layer.mergeAll(ProcessEnvLive) diff --git a/src/main.ts b/src/main.ts new file mode 100644 index 0000000..3653027 --- /dev/null +++ b/src/main.ts @@ -0,0 +1,25 @@ +/** + * Entrypoint. + * + * Errors are printed as exactly one line: `oytc: ` on stderr, with no + * usage block, stack, or color — matching the Go implementation, which routed + * every failure through a single printer with SilenceErrors/SilenceUsage. + * + * Exit codes come from `Runtime.errorExitCode` on each tagged error, which + * BunRuntime.runMain reads off the squashed error. The one translation needed + * is for the CLI framework's own parse failures: it exits 1 where Go exits 2. + */ + +import { Effect } from "effect" +import { BunRuntime, BunServices } from "@effect/platform-bun" +import { Command } from "./effect.ts" +import { AppLayer } from "./layers.ts" +import { root } from "./cli/root.ts" + +const cli = Command.run(root, { + version: process.env["OYTC_VERSION"] ?? "dev" +}) + +BunRuntime.runMain( + cli.pipe(Effect.provide(AppLayer), Effect.provide(BunServices.layer)) +) diff --git a/src/output/columns.ts b/src/output/columns.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/output/columns.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/output/jsonOut.ts b/src/output/jsonOut.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/output/jsonOut.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/output/table.ts b/src/output/table.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/output/table.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/output/tsv.ts b/src/output/tsv.ts new file mode 100644 index 0000000..ca14f9a --- /dev/null +++ b/src/output/tsv.ts @@ -0,0 +1,2 @@ +/** STUB — implemented in a later package. */ +export {} diff --git a/src/schema/accessors.ts b/src/schema/accessors.ts new file mode 100644 index 0000000..0df916b --- /dev/null +++ b/src/schema/accessors.ts @@ -0,0 +1,73 @@ +/** + * The complete set of reads into an opaque `items` element. + * + * These are the ONLY nested paths the Go code touches. Every accessor is + * tolerant: a missing key, a wrong type, or a non-object intermediate yields + * `Option.none` rather than failing, matching Go's comma-ok map lookups. + */ + +import { Option, Schema } from "effect" +import type { JsonObject } from "../json/value.ts" +import { rawToNumber } from "../json/value.ts" +import type { DataApiResponse } from "./dataapi.ts" + +const decodeOption = (schema: Schema.Codec) => Schema.decodeUnknownOption(schema) + +const NonEmptyStringSchema = Schema.String.pipe( + Schema.refine((s): s is string => s.length > 0, { title: "NonEmptyString" }) +) + +const SearchIdSchema = Schema.Struct({ + id: Schema.Struct({ + kind: Schema.optional(Schema.String), + channelId: Schema.optional(Schema.String) + }) +}) + +const FlatIdSchema = Schema.Struct({ id: NonEmptyStringSchema }) + +const UploadsSchema = Schema.Struct({ + contentDetails: Schema.Struct({ + relatedPlaylists: Schema.Struct({ + uploads: NonEmptyStringSchema + }) + }) +}) + +const LiveChatSchema = Schema.Struct({ + liveStreamingDetails: Schema.Struct({ + activeLiveChatId: NonEmptyStringSchema + }) +}) + +const decodeSearchId = decodeOption(SearchIdSchema) +const decodeFlatId = decodeOption(FlatIdSchema) +const decodeUploads = decodeOption(UploadsSchema) +const decodeLiveChat = decodeOption(LiveChatSchema) + +/** `id.kind` on a search result. */ +export const searchItemKind = (item: JsonObject): Option.Option => + Option.flatMap(decodeSearchId(item), (v) => Option.fromNullishOr(v.id.kind)) + +/** `id.channelId` on a search result. */ +export const searchItemChannelId = (item: JsonObject): Option.Option => + Option.flatMap(decodeSearchId(item), (v) => Option.fromNullishOr(v.id.channelId)) + +/** Top-level `id` when it is a flat non-empty string (channels, videos, …). */ +export const channelItemId = (item: JsonObject): Option.Option => + Option.map(decodeFlatId(item), (v) => v.id) + +/** Alias kept for call-site clarity; identical semantics. */ +export const itemId = channelItemId + +/** `contentDetails.relatedPlaylists.uploads`. */ +export const channelUploadsPlaylist = (item: JsonObject): Option.Option => + Option.map(decodeUploads(item), (v) => v.contentDetails.relatedPlaylists.uploads) + +/** `liveStreamingDetails.activeLiveChatId`. */ +export const videoActiveLiveChatId = (item: JsonObject): Option.Option => + Option.map(decodeLiveChat(item), (v) => v.liveStreamingDetails.activeLiveChatId) + +/** `pollingIntervalMillis` as a real number — one of the few numeric reads. */ +export const pollingIntervalMillis = (r: DataApiResponse): Option.Option => + Option.fromNullishOr(rawToNumber(r.pollingIntervalMillis)) diff --git a/src/schema/analytics.ts b/src/schema/analytics.ts new file mode 100644 index 0000000..88f980c --- /dev/null +++ b/src/schema/analytics.ts @@ -0,0 +1,25 @@ +/** + * YouTube Analytics API response schema. + * + * Unlike the Data API, this shape IS genuinely typed — the reports endpoint + * always returns column headers plus a row matrix. Both fields are optional + * and default to empty, because an empty report omits them. + */ + +import { Schema } from "effect" + +export const AnalyticsColumnHeader = Schema.Struct({ + name: Schema.String, + columnType: Schema.optional(Schema.String), + dataType: Schema.optional(Schema.String) +}) + +export type AnalyticsColumnHeader = typeof AnalyticsColumnHeader.Type + +export const AnalyticsResponse = Schema.Struct({ + columnHeaders: Schema.optional(Schema.Array(AnalyticsColumnHeader)), + /** Cell values are RawNumber | string | boolean | null at runtime. */ + rows: Schema.optional(Schema.Array(Schema.Array(Schema.Unknown))) +}) + +export type AnalyticsResponse = typeof AnalyticsResponse.Type diff --git a/src/schema/dataapi.ts b/src/schema/dataapi.ts new file mode 100644 index 0000000..581bb74 --- /dev/null +++ b/src/schema/dataapi.ts @@ -0,0 +1,29 @@ +/** + * YouTube Data API v3 response schemas. + * + * DELIBERATELY LOOSE. `--parts` and `--fields` let users request arbitrary + * field subsets, so any fixed per-resource schema (Video, Channel, Playlist…) + * would reject responses the Go client accepts. Only the list envelope is + * typed; `items` stays an opaque record, and the handful of nested paths the + * code actually reads get narrow, tolerant accessors in `accessors.ts`. + * + * Do not add per-resource schemas here. + */ + +import { Schema } from "effect" + +export const JsonObjectSchema = Schema.Record(Schema.String, Schema.Unknown) + +export const DataApiResponse = Schema.Struct({ + items: Schema.optional(Schema.Array(JsonObjectSchema)), + nextPageToken: Schema.optional(Schema.String), + prevPageToken: Schema.optional(Schema.String), + /** RawNumber at runtime; decoded as Unknown and narrowed on demand. */ + pollingIntervalMillis: Schema.optional(Schema.Unknown), + offlineAt: Schema.optional(Schema.String), + pageInfo: Schema.optional(JsonObjectSchema), + kind: Schema.optional(Schema.String), + etag: Schema.optional(Schema.String) +}) + +export type DataApiResponse = typeof DataApiResponse.Type diff --git a/src/services/index.ts b/src/services/index.ts new file mode 100644 index 0000000..d4d540e --- /dev/null +++ b/src/services/index.ts @@ -0,0 +1,315 @@ +/** + * Service tags and interfaces — THE CONTRACT. + * + * Every implementation package codes against these signatures. Bodies live in + * `src/impl/`; nothing in this file has an implementation. Signatures are + * frozen once the foundation lands: changing one invalidates work in flight + * across every parallel package. + */ + +import type { Effect, Option, Redacted } from "effect" +import { Context } from "effect" +import type { ListResult, PageOptions } from "../domain/listResult.ts" +import type { + ApiError, + MissingKeyError, + MissingOAuthError, + OAuthError, + OperationalError, + OytcError +} from "../domain/errors.ts" +import type { JsonObject, JsonValue } from "../json/value.ts" +import type { AnalyticsResponse } from "../schema/analytics.ts" +import type { DataApiResponse } from "../schema/dataapi.ts" + +/** Query parameters as ordered pairs; the client sorts them at encode time. */ +export type Params = ReadonlyArray + +// --------------------------------------------------------------------------- +// Transport +// --------------------------------------------------------------------------- + +export interface HttpCoreRequest { + readonly baseUrl: string + /** May contain a slash, e.g. "liveChat/messages". */ + readonly resource: string + readonly params: Params + /** When true, attach OAuth bearer or API key; OAuth strictly wins. */ + readonly authenticate: boolean +} + +export interface HttpCoreShape { + readonly getJson: ( + request: HttpCoreRequest + ) => Effect.Effect +} + +export const HttpCore = Context.Service("oytc/HttpCore") + +// --------------------------------------------------------------------------- +// YouTube Data API +// --------------------------------------------------------------------------- + +export interface ResolvedChannel { + readonly id: string + readonly requests: number +} + +export interface YouTubeApiShape { + readonly get: (resource: string, params: Params) => Effect.Effect + readonly list: ( + resource: string, + params: Params, + options: PageOptions + ) => Effect.Effect + /** Accepts a UC… id, an @handle, or a channel URL. */ + readonly resolveChannel: (reference: string) => Effect.Effect +} + +export const YouTubeApi = Context.Service("oytc/YouTubeApi") + +// --------------------------------------------------------------------------- +// YouTube Analytics API +// --------------------------------------------------------------------------- + +export interface AnalyticsQuery { + readonly metrics: string + readonly dimensions: string + readonly filters: string + readonly sort: string + readonly startDate: string + readonly endDate: string + readonly limit: number + readonly startIndex: number +} + +export interface AnalyticsApiShape { + readonly report: (query: AnalyticsQuery) => Effect.Effect + /** Column headers + rows flattened into objects, short rows padded with null. */ + readonly normalize: (response: AnalyticsResponse) => ReadonlyArray +} + +export const AnalyticsApi = Context.Service("oytc/AnalyticsApi") + +// --------------------------------------------------------------------------- +// Credentials +// --------------------------------------------------------------------------- + +export interface StoredOAuth { + readonly clientId: string + readonly clientSecret: string + readonly accessToken: string + readonly refreshToken: string + /** RFC3339 UTC, or "" when unset. */ + readonly expiry: string + readonly scopes: ReadonlyArray +} + +export type CredentialSource = "" | "auth.json" | "OYTC_API_KEY" + +export interface Credentials { + readonly key: string + readonly source: CredentialSource + readonly oauth: StoredOAuth | undefined + readonly path: string +} + +export interface CredentialStoreShape { + readonly dir: Effect.Effect + readonly path: Effect.Effect + readonly load: Effect.Effect + readonly save: (key: string) => Effect.Effect + readonly saveOAuth: (credentials: StoredOAuth) => Effect.Effect + /** + * Compare-and-swap. Returns false — writing nothing, failing nothing — when + * the stored block no longer matches `expected`, so a token refresh racing a + * `logout` cannot resurrect removed credentials. + */ + readonly saveRefreshedOAuth: ( + expected: StoredOAuth | undefined, + next: StoredOAuth + ) => Effect.Effect + readonly clearOAuth: Effect.Effect + readonly remove: Effect.Effect< + { readonly path: string; readonly removed: boolean }, + OperationalError + > + /** "sha256:" + first 12 hex chars of sha256(key). */ + readonly fingerprint: (key: string) => string + readonly envKeySet: Effect.Effect + readonly oauthBootstrap: Effect.Effect< + readonly [clientId: string, clientSecret: string] + > +} + +export const CredentialStore = Context.Service("oytc/CredentialStore") + +// --------------------------------------------------------------------------- +// Cross-process locking +// --------------------------------------------------------------------------- + +export interface FileLockShape { + /** Blocking and cross-process; held across an entire read-modify-write. */ + readonly withLock: ( + lockPath: string, + effect: Effect.Effect + ) => Effect.Effect +} + +export const FileLock = Context.Service("oytc/FileLock") + +// --------------------------------------------------------------------------- +// OAuth +// --------------------------------------------------------------------------- + +export interface OAuthLoginRequest { + readonly clientId: string + readonly clientSecret: Redacted.Redacted +} + +export interface OAuthServiceShape { + readonly login: ( + request: OAuthLoginRequest + ) => Effect.Effect + readonly refresh: ( + credentials: StoredOAuth + ) => Effect.Effect + /** Best-effort; a failure is a warning, never fatal. */ + readonly revoke: (credentials: StoredOAuth) => Effect.Effect + /** + * Current access token, refreshing when within the skew window. + * `force` bypasses the cache after a 401. + */ + readonly tokenSource: ( + force: boolean + ) => Effect.Effect, OAuthError | OperationalError | MissingOAuthError> +} + +export const OAuthService = Context.Service("oytc/OAuthService") + +// --------------------------------------------------------------------------- +// Self-update +// --------------------------------------------------------------------------- + +export interface UpdateOptions { + readonly checkOnly: boolean + readonly targetVersion: string +} + +export interface UpdateResult { + readonly currentVersion: string + readonly latestVersion: string + readonly updated: boolean + readonly asset: string + readonly executable: string +} + +export interface UpdaterShape { + readonly run: (options: UpdateOptions) => Effect.Effect +} + +export const Updater = Context.Service("oytc/Updater") + +// --------------------------------------------------------------------------- +// Skills +// --------------------------------------------------------------------------- + +export interface SkillInstallResult { + readonly path: string + readonly files: ReadonlyArray +} + +export interface SkillInstallerShape { + readonly defaultPath: Effect.Effect + readonly install: (target: string) => Effect.Effect +} + +export const SkillInstaller = Context.Service("oytc/SkillInstaller") + +// --------------------------------------------------------------------------- +// Output +// --------------------------------------------------------------------------- + +export type OutputFormat = "table" | "json" | "jsonl" | "tsv" + +export interface RenderOptions { + readonly format: OutputFormat + readonly columns: ReadonlyArray + readonly noHeader: boolean +} + +export interface RendererShape { + readonly render: (result: ListResult, options: RenderOptions) => Effect.Effect + /** A bare object with no list envelope (status, version, update). */ + readonly renderObject: ( + object: JsonObject, + options: RenderOptions + ) => Effect.Effect +} + +export const Renderer = Context.Service("oytc/Renderer") + +// --------------------------------------------------------------------------- +// Interaction +// --------------------------------------------------------------------------- + +export interface PromptsShape { + readonly readLine: (prompt: string) => Effect.Effect + /** Must work when stdin is a pipe; `secret-manager | oytc login` is documented. */ + readonly readSecret: ( + prompt: string + ) => Effect.Effect, OperationalError> + readonly confirm: (block: string) => Effect.Effect +} + +export const Prompts = Context.Service("oytc/Prompts") + +export interface BrowserOpenerShape { + readonly open: (url: string) => Effect.Effect +} + +export const BrowserOpener = Context.Service("oytc/BrowserOpener") + +// --------------------------------------------------------------------------- +// Environment +// --------------------------------------------------------------------------- + +export interface VersionDetails { + readonly version: string + readonly commit: string + readonly date: string + /** Retained as a documented JSON column; carries the Bun version. */ + readonly goVersion: string + readonly os: string + readonly arch: string +} + +export interface VersionInfoShape { + readonly get: Effect.Effect +} + +export const VersionInfo = Context.Service("oytc/VersionInfo") + +export interface ProcessEnvShape { + readonly env: (name: string) => Option.Option + readonly platform: string + readonly arch: string + readonly argv: ReadonlyArray + readonly executablePath: Effect.Effect + readonly isOutputTTY: boolean + readonly homeDir: Effect.Effect +} + +export const ProcessEnv = Context.Service("oytc/ProcessEnv") + +/** Resolved global flags, provided per invocation rather than in AppLayer. */ +export interface AppOptionsShape { + readonly format: OutputFormat + readonly columns: ReadonlyArray + readonly noHeader: boolean + readonly quiet: boolean + readonly timeoutMillis: number + readonly isOutputTTY: boolean +} + +export const AppOptions = Context.Service("oytc/AppOptions") diff --git a/src/util/goduration.test.ts b/src/util/goduration.test.ts new file mode 100644 index 0000000..5bc065a --- /dev/null +++ b/src/util/goduration.test.ts @@ -0,0 +1,42 @@ +import { describe, expect, test } from "bun:test" +import { Result } from "effect" +import { parseGoDuration } from "./goduration.ts" + +const ms = (input: string): number => { + const r = parseGoDuration(input) + if (Result.isFailure(r)) throw new Error(`unexpected failure for ${input}`) + return r.success +} + +describe("parseGoDuration", () => { + test.each([ + ["0", 0], + ["20s", 20_000], + ["1m30s", 90_000], + ["500ms", 500], + ["2h45m", 9_900_000], + ["1.5h", 5_400_000], + ["-1.5h", -5_400_000], + ["+30s", 30_000], + ["100us", 0.1], + ["1000ns", 0.001], + ["1h1m1s", 3_661_000] + ])("%s -> %dms", (input, expected) => { + expect(ms(input)).toBeCloseTo(expected, 6) + }) + + test.each([[""], ["20"], ["abc"], ["s"], ["-"], ["1x"], ["."], ["1.2.3s"]])( + "rejects %s", + (input) => { + expect(Result.isFailure(parseGoDuration(input))).toBe(true) + } + ) + + test("error message matches Go's phrasing", () => { + const r = parseGoDuration("nope") + expect(Result.isFailure(r)).toBe(true) + if (Result.isFailure(r)) { + expect(r.failure.message).toBe('invalid duration "nope"') + } + }) +}) diff --git a/src/util/goduration.ts b/src/util/goduration.ts new file mode 100644 index 0000000..f817222 --- /dev/null +++ b/src/util/goduration.ts @@ -0,0 +1,72 @@ +/** + * Go `time.ParseDuration` — used by `--timeout`. + * + * Accepts a signed decimal sequence of number+unit pairs, e.g. "300ms", + * "1m30s", "2h45m", "-1.5h". Valid units: ns, us (or µs/μs), ms, s, m, h. + * A unit is required; "0" is the sole exception Go allows. + */ + +import { Result } from "effect" + +const UNITS: Readonly> = { + ns: 1e-6, + us: 1e-3, + "µs": 1e-3, + "μs": 1e-3, + ms: 1, + s: 1000, + m: 60_000, + h: 3_600_000 +} + +export class DurationParseError { + readonly _tag = "DurationParseError" + constructor(readonly input: string) {} + get message(): string { + return `invalid duration ${JSON.stringify(this.input)}` + } +} + +/** Returns milliseconds, matching how the HTTP layer consumes a timeout. */ +export const parseGoDuration = ( + input: string +): Result.Result => { + const fail = () => Result.fail(new DurationParseError(input)) + + if (input === "") return fail() + if (input === "0") return Result.succeed(0) + + let rest = input + let sign = 1 + if (rest.startsWith("-")) { + sign = -1 + rest = rest.slice(1) + } else if (rest.startsWith("+")) { + rest = rest.slice(1) + } + if (rest === "") return fail() + if (rest === "0") return Result.succeed(0) + + let total = 0 + let matchedAny = false + + while (rest.length > 0) { + const numMatch = /^\d*\.?\d*/.exec(rest) + const numText = numMatch?.[0] ?? "" + if (numText === "" || numText === ".") return fail() + rest = rest.slice(numText.length) + + const unitMatch = /^(ns|us|µs|μs|ms|s|m|h)/.exec(rest) + const unit = unitMatch?.[0] + if (unit === undefined) return fail() + rest = rest.slice(unit.length) + + const value = Number(numText) + if (!Number.isFinite(value)) return fail() + + total += value * UNITS[unit]! + matchedAny = true + } + + return matchedAny ? Result.succeed(sign * total) : fail() +} From d32f550d94ef32a8e90345712b32c7ea1aee167d Mon Sep 17 00:00:00 2001 From: Benjamin Davis Date: Sat, 25 Jul 2026 00:48:44 -0700 Subject: [PATCH 3/6] feat(ts): implement the service layer (wave 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Eight packages implemented in parallel over disjoint file sets, each followed by an independent verifier that re-checked the work against the Go source rather than trusting the implementer's report. - impl/httpCore, youtubeApi, resolveChannel, schema/errorEnvelope: transport and Data API client - impl/analyticsApi: Analytics reports client - output/{columns,table,tsv,jsonOut} + impl/renderer: a real port of Go's text/tabwriter state machine, not a pad-to-width approximation - impl/{credentialStore,fileLock,atomicWrite} + schema/authfile: credential storage with cross-process locking - impl/{oauth,oauthServer,tokenSource,browserOpener}: PKCE S256 loopback - impl/{updater,archive,semver,platformMatrix}: checksum-verified update - impl/{skillInstaller,versionInfo,prompts} + src/skills: embedded skill - scripts/, .depot/, site/, Makefile: Bun packaging for 5 targets The verifiers found defects the implementers' own tests missed, all caught by differential fuzzing against Go 1.26.5 rather than by reading: - httpCore's JSON prefix scanner mishandled a leading zero, so a body of `0.5x` silently truncated to `0` (536 diffs before the fix, 0 after) - the error envelope was case-sensitive, but Go's encoding/json falls back to a case-insensitive field match, so `{"Error":{"CODE":403}}` decoded to an empty envelope — losing the message and every reason, and with them the exit code - analytics dropped a column whose header was literally `__proto__`, and an object cell there replaced the row's prototype - the file lock could not be interrupted while waiting Integration fixes in this commit: - statusText now carries Go's full net/http table (61 entries, generated from Go 1.26.5) instead of the 14 common codes - layers.ts is wired for real. ProcessEnv and VersionInfo are dependencies of four other layers, not siblings: Effect does not let members of a mergeAll satisfy each other's requirements, so each consumer receives them via Layer.provide - TokenSource and HttpCoreShape now carry OAuthError. It must propagate unchanged because it holds its own exit code (3 re-login, 5 on 429, 6 on 5xx); wrapping it would flatten every case to 6 1303 tests pass, TypeScript 7 typechecks clean, and the CLI runs with the full layer graph. Co-Authored-By: Claude Opus 5 (1M context) --- .depot/workflows/ci.yml | 104 ++- .depot/workflows/release.yml | 17 +- Makefile | 54 +- dev | 8 +- docs/releasing.md | 61 +- scripts/package.sh | 74 +- site/index.html | 4 + site/install.ps1 | 22 +- site/install.sh | 5 +- src/cli/root.ts | 7 +- src/domain/errors.test.ts | 21 +- src/domain/errors.ts | 59 +- src/impl/analyticsApi.test.ts | 680 +++++++++++++++ src/impl/analyticsApi.ts | 269 +++++- src/impl/archive.test.ts | 369 ++++++++ src/impl/archive.ts | 353 +++++++- src/impl/atomicWrite.test.ts | 150 ++++ src/impl/atomicWrite.ts | 119 ++- src/impl/browserOpener.test.ts | 116 +++ src/impl/browserOpener.ts | 74 +- src/impl/credentialStore.test.ts | 858 ++++++++++++++++++ src/impl/credentialStore.ts | 412 ++++++++- src/impl/credentialStore.worker.ts | 104 +++ src/impl/fileLock.test.ts | 292 +++++++ src/impl/fileLock.ts | 144 ++- src/impl/httpCore.test.ts | 922 ++++++++++++++++++++ src/impl/httpCore.ts | 519 ++++++++++- src/impl/oauth.test.ts | 1169 +++++++++++++++++++++++++ src/impl/oauth.ts | 989 ++++++++++++++++++++- src/impl/oauthServer.test.ts | 145 ++++ src/impl/oauthServer.ts | 140 ++- src/impl/platformMatrix.test.ts | 152 ++++ src/impl/platformMatrix.ts | 164 +++- src/impl/prompts.test.ts | 320 +++++++ src/impl/prompts.ts | 375 +++++++- src/impl/renderer.test.ts | 216 +++++ src/impl/renderer.ts | 110 ++- src/impl/resolveChannel.test.ts | 481 ++++++++++ src/impl/resolveChannel.ts | 408 ++++++++- src/impl/semver.test.ts | 188 ++++ src/impl/semver.ts | 140 ++- src/impl/skillInstaller.test.ts | 326 +++++++ src/impl/skillInstaller.ts | 208 ++++- src/impl/tokenSource.test.ts | 196 +++++ src/impl/tokenSource.ts | 101 ++- src/impl/updater.test.ts | 1304 ++++++++++++++++++++++++++++ src/impl/updater.ts | 746 +++++++++++++++- src/impl/versionInfo.test.ts | 120 +++ src/impl/versionInfo.ts | 111 ++- src/impl/youtubeApi.test.ts | 491 +++++++++++ src/impl/youtubeApi.ts | 137 ++- src/layers.ts | 106 ++- src/main.ts | 21 +- src/output/columns.test.ts | 547 ++++++++++++ src/output/columns.ts | 418 ++++++++- src/output/jsonOut.test.ts | 192 ++++ src/output/jsonOut.ts | 36 +- src/output/table.test.ts | 253 ++++++ src/output/table.ts | 174 +++- src/output/tsv.test.ts | 122 +++ src/output/tsv.ts | 17 +- src/schema/authfile.test.ts | 343 ++++++++ src/schema/authfile.ts | 362 ++++++++ src/schema/errorEnvelope.test.ts | Bin 0 -> 8637 bytes src/schema/errorEnvelope.ts | 175 ++++ src/services/index.ts | 12 +- src/skills/SKILL.md | 59 ++ src/skills/bundle.test.ts | 61 ++ src/skills/bundle.ts | 48 + src/skills/references/commands.md | 69 ++ src/skills/references/recipes.md | 93 ++ 71 files changed, 17512 insertions(+), 150 deletions(-) create mode 100644 src/impl/analyticsApi.test.ts create mode 100644 src/impl/archive.test.ts create mode 100644 src/impl/atomicWrite.test.ts create mode 100644 src/impl/browserOpener.test.ts create mode 100644 src/impl/credentialStore.test.ts create mode 100644 src/impl/credentialStore.worker.ts create mode 100644 src/impl/fileLock.test.ts create mode 100644 src/impl/httpCore.test.ts create mode 100644 src/impl/oauth.test.ts create mode 100644 src/impl/oauthServer.test.ts create mode 100644 src/impl/platformMatrix.test.ts create mode 100644 src/impl/prompts.test.ts create mode 100644 src/impl/renderer.test.ts create mode 100644 src/impl/resolveChannel.test.ts create mode 100644 src/impl/semver.test.ts create mode 100644 src/impl/skillInstaller.test.ts create mode 100644 src/impl/tokenSource.test.ts create mode 100644 src/impl/updater.test.ts create mode 100644 src/impl/versionInfo.test.ts create mode 100644 src/impl/youtubeApi.test.ts create mode 100644 src/output/columns.test.ts create mode 100644 src/output/jsonOut.test.ts create mode 100644 src/output/table.test.ts create mode 100644 src/output/tsv.test.ts create mode 100644 src/schema/authfile.test.ts create mode 100644 src/schema/authfile.ts create mode 100644 src/schema/errorEnvelope.test.ts create mode 100644 src/schema/errorEnvelope.ts create mode 100644 src/skills/SKILL.md create mode 100644 src/skills/bundle.test.ts create mode 100644 src/skills/bundle.ts create mode 100644 src/skills/references/commands.md create mode 100644 src/skills/references/recipes.md diff --git a/.depot/workflows/ci.yml b/.depot/workflows/ci.yml index f70ad85..d37b32f 100644 --- a/.depot/workflows/ci.yml +++ b/.depot/workflows/ci.yml @@ -12,53 +12,80 @@ permissions: concurrency: group: ci-${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true +env: + # Pinned so the compiled artifacts and the `--compile --target=` matrix are + # reproducible. Bump deliberately, alongside a local `make cross-build`. + BUN_VERSION: "1.3.14" jobs: test: - name: Format, vet, test, build + name: Typecheck, test, build # Depot CI sandbox label (https://depot.dev/docs/ci/overview#depot-ci-sandboxes). runs-on: depot-ubuntu-24.04 steps: - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: - go-version-file: go.mod - - name: Verify formatting (gofmt, no rewrite) + bun-version: ${{ env.BUN_VERSION }} + - name: Install dependencies (frozen lockfile) + run: bun install --frozen-lockfile + - name: Typecheck + run: bun run typecheck + - name: Tests + run: bun test + - name: Verify bun.lock is unchanged by install + run: git diff --exit-code bun.lock + - name: Effect imports go through the src/effect.ts barrel run: | - unformatted="$(gofmt -l .)" - if [ -n "$unformatted" ]; then - echo "gofmt required for:" >&2 - echo "$unformatted" >&2 + set -eu + # Every effect/unstable/* import lives in the barrel, so a rename in a + # beta release stays a one-file fix. Written as a positive test with an + # explicit exit: `! grep ...` is exempt from `set -e` under POSIX, so + # the negated form would silently pass whenever a later line follows. + if grep -rn "effect/unstable" src/ --exclude=effect.ts; then + echo "import effect/unstable/* only in src/effect.ts (see the lines above)" >&2 exit 1 fi - - name: Verify go.mod/go.sum are tidy + echo "barrel import discipline OK" + - name: JSON.stringify is confined to src/json/encode.ts run: | - go mod tidy - git diff --exit-code go.mod go.sum - - name: go vet - run: go vet ./... - - name: Tests (race detector) - run: go test -race ./... + set -eu + # Go's encoder escaping and its >2^53 integer fidelity are reproduced + # in src/json/encode.ts; a stray JSON.stringify silently breaks both. + offenders="$(grep -rl 'JSON\.stringify' src/ --include='*.ts' | + grep -v '^src/json/encode\.ts$' || true)" + if [ -n "$offenders" ]; then + echo "JSON.stringify is only allowed in src/json/encode.ts; found in:" >&2 + echo "$offenders" >&2 + exit 1 + fi + echo "JSON.stringify confinement OK" - name: Build - run: go build ./... + run: bun run build cross-build: - name: Cross-compile release targets + name: Compile release targets runs-on: depot-ubuntu-24.04 steps: - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: - go-version-file: go.mod - - name: Build every release platform + bun-version: ${{ env.BUN_VERSION }} + - name: Install dependencies (frozen lockfile) + run: bun install --frozen-lockfile + - name: Compile every release platform run: | set -eu - for platform in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do - echo "== $platform ==" - CGO_ENABLED=0 GOOS="${platform%/*}" GOARCH="${platform#*/}" \ - go build -trimpath -o /dev/null ./cmd/oytc + # Mirrors PLATFORMS + bun_target() in scripts/package.sh. Bun has no + # ARM64 Windows --compile target, so windows/arm64 is not published; + # ARM64 Windows installs the amd64 build (see site/install.ps1). + for target in bun-linux-x64 bun-linux-arm64 bun-darwin-x64 bun-darwin-arm64 bun-windows-x64; do + echo "== $target ==" + out="$(mktemp -d)" + bun build --compile --target="$target" --outfile "$out/oytc" src/main.ts + rm -rf "$out" done scripts-and-site: name: Validate installer, scripts, skill, site @@ -75,7 +102,7 @@ jobs: - name: shellcheck run: | sudo apt-get update -q && sudo apt-get install -y -q shellcheck - shellcheck site/install.sh scripts/package.sh + shellcheck site/install.sh scripts/package.sh dev - name: Skill structure run: | python3 - <<'EOF' @@ -93,21 +120,38 @@ jobs: - name: Asset naming consistency (release <-> installer <-> updater) run: | set -eu - # The canonical pattern oytc___. must appear in all three places. - grep -q 'oytc_%s_%s_%s' internal/update/update.go + # The canonical pattern oytc___. must appear in all + # three places. These are single-quoted shell literals matching the + # *source syntax* of each file — a TypeScript template literal in the + # updater's platform matrix, shell parameter expansions in the two + # scripts — not any expanded value. Rewrite them when the naming + # changes; never delete them. This step is the only thing keeping the + # three copies of the scheme from drifting apart. + grep -q 'oytc_${tag}_${goos}_${goarch}' src/impl/platformMatrix.ts grep -q 'oytc_${VERSION}_${goos}_${goarch}' scripts/package.sh grep -q 'oytc_${version}_${goos}_${goarch}' site/install.sh - grep -q 'checksums.txt' internal/update/update.go + grep -rq 'checksums.txt' src/impl/ grep -q 'checksums.txt' scripts/package.sh grep -q 'checksums.txt' site/install.sh echo "asset naming consistent" - - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + - name: Platform matrix is the five published pairs + run: | + set -eu + # The packager, `make cross-build`, and this workflow's cross-build job + # must all agree on exactly these five pairs. + grep -q 'PLATFORMS="linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64"' scripts/package.sh + echo "platform matrix consistent" + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: - go-version-file: go.mod + bun-version: ${{ env.BUN_VERSION }} + - name: Install dependencies (frozen lockfile) + run: bun install --frozen-lockfile - name: Installer end-to-end against local artifacts run: | set -eu ./scripts/package.sh v0.0.0-ci dist-ci + count="$(ls -1 dist-ci/oytc_v0.0.0-ci_* | wc -l)" + [ "$count" -eq 5 ] || { echo "expected 5 archives, got $count" >&2; exit 1; } mkdir -p serve/v0.0.0-ci cp dist-ci/oytc_v0.0.0-ci_linux_amd64.tar.gz dist-ci/checksums.txt serve/v0.0.0-ci/ python3 -m http.server 8931 --directory serve >/dev/null 2>&1 & diff --git a/.depot/workflows/release.yml b/.depot/workflows/release.yml index 4739bd9..a9d73af 100644 --- a/.depot/workflows/release.yml +++ b/.depot/workflows/release.yml @@ -52,16 +52,23 @@ jobs: with: ref: ${{ steps.tag.outputs.tag }} persist-credentials: false - - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: - go-version-file: go.mod - - name: Tests (race detector) - run: go test -race ./... + # Keep in sync with BUN_VERSION in ci.yml. + bun-version: "1.3.14" + - name: Install dependencies (frozen lockfile) + run: bun install --frozen-lockfile + - name: Tests + run: bun test - name: Package all platforms run: ./scripts/package.sh "${{ steps.tag.outputs.tag }}" dist - name: Smoke-test a packaged binary run: | set -eu + # linux_amd64 is the only published target this sandbox can execute; + # the other four are compile-verified by ci.yml's cross-build job. + # The grep pins pretty-printed JSON (a space after the colon) and the + # build-time version define reaching `oytc version`. tar -xzf "dist/oytc_${{ steps.tag.outputs.tag }}_linux_amd64.tar.gz" -C /tmp oytc /tmp/oytc version /tmp/oytc version --format json | grep -q '"version": "${{ steps.tag.outputs.tag }}"' @@ -73,6 +80,8 @@ jobs: draft: false prerelease: ${{ contains(steps.tag.outputs.tag, '-') }} generate_release_notes: true + # Safe with the five-platform matrix: the *.zip glob still matches + # windows_amd64. Dropping every Windows target would fail the upload. fail_on_unmatched_files: true files: | dist/oytc_${{ steps.tag.outputs.tag }}_*.tar.gz diff --git a/Makefile b/Makefile index 706078e..fe78d13 100644 --- a/Makefile +++ b/Makefile @@ -1,9 +1,9 @@ -.PHONY: dev build test check fmt fmt-check tidy-check cross-build package site-check release-check +.PHONY: dev build test check typecheck lint fmt fmt-check lock-check cross-build package site-check release-check # Forward additional make goals and ARGS to the CLI, so both # `make dev login` and `make dev ARGS="search cats --limit 5"` work. dev: - go run ./cmd/oytc $(filter-out dev,$(MAKECMDGOALS)) $(ARGS) + bun run src/main.ts $(filter-out dev,$(MAKECMDGOALS)) $(ARGS) # Treat positional CLI arguments as no-op make targets after `dev` runs, # while still failing normally for unknown standalone targets. @@ -13,34 +13,46 @@ dev: fi build: - go build -o bin/oytc ./cmd/oytc + bun build --compile --outfile=bin/oytc src/main.ts test: - go test ./... + bun test -check: - go vet ./... - go test ./... +typecheck: + ./node_modules/.bin/tsc -p tsconfig.json -fmt: - gofmt -w . +check: typecheck test + +# Effect language-service diagnostics; advisory, beyond what tsc reports. +lint: + ./node_modules/.bin/effect-tsgo diagnostics --project tsconfig.json --format text # --- release/site validation ------------------------------------------------- +# No formatter is configured: the repo has no prettier/biome dependency and Bun +# ships no `bun fmt`. These targets exist so the documented workflow keeps +# working; CI enforces correctness through typecheck + tests instead. +fmt: + @echo "fmt: no formatter configured for this repo; nothing to do" + fmt-check: - @unformatted="$$(gofmt -l .)"; if [ -n "$$unformatted" ]; then \ - echo "gofmt required for:" >&2; echo "$$unformatted" >&2; exit 1; fi + @echo "fmt-check: no formatter configured for this repo; nothing to check" -tidy-check: - go mod tidy - git diff --exit-code go.mod go.sum +# The committed lockfile must already satisfy package.json (CI's equivalent of +# the old `go mod tidy` check). Run standalone; it touches node_modules. +lock-check: + bun install --frozen-lockfile + git diff --exit-code bun.lock -# Cross-compile every release platform without producing artifacts. +# Compile every release platform without keeping artifacts. Mirrors PLATFORMS +# in scripts/package.sh and the cross-build job in .depot/workflows/ci.yml. +# windows/arm64 is absent: bun has no bun-windows-arm64 --compile target. cross-build: - @set -e; for platform in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do \ - echo "== $$platform =="; \ - CGO_ENABLED=0 GOOS="$${platform%/*}" GOARCH="$${platform#*/}" \ - go build -trimpath -o /dev/null ./cmd/oytc; \ + @set -e; for target in bun-linux-x64 bun-linux-arm64 bun-darwin-x64 bun-darwin-arm64 bun-windows-x64; do \ + echo "== $$target =="; \ + out="$$(mktemp -d)"; \ + bun build --compile --target="$$target" --outfile "$$out/oytc" src/main.ts >/dev/null; \ + rm -rf "$$out"; \ done # Build local release archives + checksums: make package VERSION=v0.1.0 @@ -55,5 +67,5 @@ site-check: test -f site/install.ps1 grep -q 'davis7dotsh.github.io/open-yt-cli/install.sh' README.md -release-check: fmt-check check cross-build site-check - go test -race ./... +release-check: check cross-build site-check + @echo "release-check OK" diff --git a/dev b/dev index 8e45807..df14333 100755 --- a/dev +++ b/dev @@ -1,4 +1,10 @@ #!/usr/bin/env sh +# Run oytc straight from source, without compiling a binary first. +# +# ./dev search "cats" --limit 5 +# +# Version metadata is not injected here, so `./dev version` reports the +# dev/unknown/unknown fallbacks from src/impl/versionInfo.ts. set -eu -exec go run ./cmd/oytc "$@" +exec bun run src/main.ts "$@" diff --git a/docs/releasing.md b/docs/releasing.md index ce0cea1..28be766 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -15,17 +15,44 @@ others (CI has a consistency check): | Windows archive | `oytc__windows_.zip` containing a single `oytc.exe` | | Checksums | `checksums.txt` (sha256sum format, one line per archive) | -Platforms: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, `windows/amd64`, -`windows/arm64`. Producers/consumers of this contract: +Platforms — five pairs: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, +`windows/amd64`. Producers/consumers of this contract: - `scripts/package.sh` — builds the archives and `checksums.txt` - `.depot/workflows/release.yml` — runs `package.sh` and uploads to the GitHub Release - `site/install.sh` / `site/install.ps1` — download + verify + install -- `internal/update/update.go` (`AssetName`) — the self-updater +- `src/impl/platformMatrix.ts` (`assetName`) — the self-updater -Version metadata is injected via -`-ldflags -X open-yt-cli/internal/version.{Version,Commit,Date}=…` and surfaced by -`oytc version`. +### Why there is no `windows/arm64` + +The binaries are produced by `bun build --compile`, which has no `bun-windows-arm64` +target. ARM64 Windows is still supported: `site/install.ps1` detects +`Win32_Processor.Architecture == 12`, prints a note, and installs the **amd64** build, +which Windows runs under x64 emulation. This is deliberately *not* a hard failure — +failing would strand ARM64 Windows users who installed a previous release on a binary +their own `oytc update` could never replace. + +The archive names keep the historical Go-style `os`/`arch` tokens (`linux`, `darwin`, +`windows` / `amd64`, `arm64`) even though the toolchain changed, so clients installed from +an older release still resolve the right asset when they self-update. Two mappings +therefore coexist and must not be confused: + +| Asset-name pair | `bun build --compile --target=` | +| --- | --- | +| `linux/amd64` | `bun-linux-x64` | +| `linux/arm64` | `bun-linux-arm64` | +| `darwin/amd64` | `bun-darwin-x64` | +| `darwin/arm64` | `bun-darwin-arm64` | +| `windows/amd64` | `bun-windows-x64` | + +`scripts/package.sh` owns the shell copy of that table (`bun_target()`); +`src/impl/platformMatrix.ts` owns the TypeScript copy plus the +`process.platform`/`process.arch` → `goos`/`goarch` direction used by the self-updater. + +Version metadata is injected at bundle time via +`bun build --define OYTC_VERSION='""' --define OYTC_COMMIT='""' +--define OYTC_DATE='""'`, read by `src/impl/versionInfo.ts` (which falls back to +`dev`/`unknown`/`unknown` for plain `bun run`), and surfaced by `oytc version`. ## CI system: Depot CI (not GitHub Actions) @@ -48,7 +75,7 @@ Key facts (source: , merged to the default branch. `push` (branches/tags/paths), `pull_request`, `workflow_dispatch`, `schedule`, and concurrency groups are all supported. - **Marketplace actions** (JavaScript/composite/Docker) work, so pinned - `actions/checkout`, `actions/setup-go`, and `softprops/action-gh-release` run unchanged. + `actions/checkout`, `oven-sh/setup-bun`, and `softprops/action-gh-release` run unchanged. - **Permissions**: Depot CI supports `contents`, `id-token`, `actions`, `checks`, `metadata`, `pull_requests`, `statuses`, `workflows`. It does **not** support `pages: write` or the `environment:` job key, and its `id-token` is a Depot OIDC token @@ -85,7 +112,7 @@ Key facts (source: , | Workflow | Trigger | What it does | | --- | --- | --- | -| `.depot/workflows/ci.yml` | PRs and pushes to `main` | gofmt check (no rewrite), `go mod tidy` check, `go vet`, `go test -race`, build, cross-compile all six release targets, shell syntax + shellcheck, skill structure check, asset-naming consistency check, installer end-to-end test against locally packaged artifacts | +| `.depot/workflows/ci.yml` | PRs and pushes to `main` | `bun install --frozen-lockfile`, `bun run typecheck`, `bun test`, `bun.lock` diff check, the two source-discipline greps (Effect imports via the `src/effect.ts` barrel; `JSON.stringify` confined to `src/json/encode.ts`), `bun run build`, compile all five release targets, shell syntax + shellcheck, skill structure check, asset-naming and platform-matrix consistency checks, installer end-to-end test against locally packaged artifacts | | `.depot/workflows/release.yml` | push of a `v*` tag, or `workflow_dispatch` with an existing tag | tests, `scripts/package.sh`, smoke-test of a packaged binary, create GitHub Release with archives + `checksums.txt` (prerelease flag auto-set for tags containing `-`) | | `.depot/workflows/pages.yml` | push to `main` touching `site/**`, or manual | validate `site/` and publish it as an orphan commit force-pushed to the `gh-pages` branch | @@ -109,7 +136,7 @@ Then verify: 1. The `Release` workflow run is green in the Depot dashboard (or `depot ci run list`) and - shows six archives plus + shows five archives plus `checksums.txt`. 2. `curl -fsSL https://davis7dotsh.github.io/open-yt-cli/install.sh | sh` installs and `oytc version` prints `v0.1.0`. @@ -133,6 +160,18 @@ depot ci dispatch --repo davis7dotsh/open-yt-cli --workflow release.yml \ ## Local dry run ```sh -./scripts/package.sh v0.0.0-local dist # build all archives + checksums locally -make release-check # packaging + installer sanity, no publishing +./scripts/package.sh v0.0.0-local dist # build all five archives + checksums locally +make release-check # typecheck, tests, 5-target compile, site checks +make lock-check # bun.lock matches package.json (touches node_modules) ``` + +`make release-check` deliberately omits `lock-check`: the latter runs `bun install`, which +mutates `node_modules/`. CI runs both. + +## Toolchain + +Bun is pinned in `.depot/workflows/ci.yml` (`BUN_VERSION`) and repeated in `release.yml`; +bump them together, and re-run `make cross-build` locally afterwards — a Bun upgrade +changes the embedded runtime in every compiled binary. There is no formatter dependency in +this repo, so `make fmt` / `make fmt-check` are no-ops kept for muscle memory; correctness +is enforced by `bun run typecheck` and `bun test` instead. diff --git a/scripts/package.sh b/scripts/package.sh index 0ea671b..0e6e5f2 100755 --- a/scripts/package.sh +++ b/scripts/package.sh @@ -11,9 +11,14 @@ # plus a combined checksums.txt in sha256sum format. # # The asset naming here must stay in sync with: -# internal/update/update.go (AssetName) +# src/impl/platformMatrix.ts (assetName) # site/install.sh +# site/install.ps1 # .depot/workflows/release.yml +# +# The archive names keep the historical Go-style os/arch tokens (linux, darwin, +# windows / amd64, arm64) even though the compiler is now Bun, so clients +# installed from an older release can still self-update. set -eu VERSION="${1:-}" @@ -33,13 +38,29 @@ esac COMMIT="${OYTC_COMMIT:-$(git rev-parse --short=12 HEAD 2>/dev/null || echo unknown)}" DATE="${OYTC_BUILD_DATE:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}" -LDFLAGS="-s -w \ - -X open-yt-cli/internal/version.Version=$VERSION \ - -X open-yt-cli/internal/version.Commit=$COMMIT \ - -X open-yt-cli/internal/version.Date=$DATE" +ENTRYPOINT="src/main.ts" + +# Release platforms, named with the historical goos/goarch tokens that appear in +# the asset names. windows/arm64 is deliberately absent: `bun build --compile` +# has no bun-windows-arm64 target. ARM64 Windows installs the amd64 build and +# runs it under emulation (see site/install.ps1). +PLATFORMS="linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64" -# GOOS/GOARCH pairs. Go supports windows/arm64 since 1.17. -PLATFORMS="linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64" +# Map an asset-name platform pair to its `bun build --compile --target=` value. +# Keep in sync with PLATFORMS above and with src/impl/platformMatrix.ts. +bun_target() { + case "$1/$2" in + linux/amd64) echo "bun-linux-x64" ;; + linux/arm64) echo "bun-linux-arm64" ;; + darwin/amd64) echo "bun-darwin-x64" ;; + darwin/arm64) echo "bun-darwin-arm64" ;; + windows/amd64) echo "bun-windows-x64" ;; + *) + echo "error: no bun --compile target for $1/$2" >&2 + return 1 + ;; + esac +} mkdir -p "$DIST" rm -f "$DIST"/oytc_"$VERSION"_*.tar.gz "$DIST"/oytc_"$VERSION"_*.zip "$DIST"/checksums.txt @@ -53,9 +74,25 @@ checksum_file() { fi } +# Each iteration builds into a fresh temp dir; clean up the in-flight one if a +# build fails, so `set -e` does not leave a multi-hundred-MB directory behind. +workdir="" +cleanup() { + [ -n "$workdir" ] && rm -rf "$workdir" + workdir="" +} +# INT/TERM must clean up *and* abort. A plain `trap cleanup INT TERM` runs the +# handler and then resumes the loop, so Ctrl-C would silently build all five +# ~100 MB platforms and exit 0; re-raising with the trap reset gives the caller +# the conventional 130/143 status. +trap cleanup EXIT +trap 'cleanup; trap - INT; kill -INT $$' INT +trap 'cleanup; trap - TERM; kill -TERM $$' TERM + for platform in $PLATFORMS; do goos="${platform%/*}" goarch="${platform#*/}" + target="$(bun_target "$goos" "$goarch")" binary="oytc" ext="tar.gz" if [ "$goos" = "windows" ]; then @@ -65,8 +102,25 @@ for platform in $PLATFORMS; do asset="oytc_${VERSION}_${goos}_${goarch}.${ext}" workdir="$(mktemp -d)" echo "building $asset" - CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \ - go build -trimpath -ldflags "$LDFLAGS" -o "$workdir/$binary" ./cmd/oytc + # Version metadata is injected at bundle time; src/impl/versionInfo.ts reads + # these defines and falls back to dev/unknown/unknown under plain `bun run`. + bun build --compile \ + --target="$target" \ + --define "OYTC_VERSION=\"$VERSION\"" \ + --define "OYTC_COMMIT=\"$COMMIT\"" \ + --define "OYTC_DATE=\"$DATE\"" \ + --outfile "$workdir/oytc" \ + "$ENTRYPOINT" + # A windows target appends .exe to --outfile, which is already the name the + # archive needs. Normalize either way rather than depending on that. + if [ ! -f "$workdir/$binary" ] && [ -f "$workdir/oytc" ]; then + mv "$workdir/oytc" "$workdir/$binary" + fi + if [ ! -f "$workdir/$binary" ]; then + echo "error: bun build did not produce $workdir/$binary" >&2 + exit 1 + fi + chmod 0755 "$workdir/$binary" if [ "$ext" = "zip" ]; then (cd "$workdir" && zip -q -X "$asset" "$binary") mv "$workdir/$asset" "$DIST/$asset" @@ -75,7 +129,7 @@ for platform in $PLATFORMS; do tar -C "$workdir" -czf "$DIST/$asset" --owner=0 --group=0 "$binary" 2>/dev/null || tar -C "$workdir" -czf "$DIST/$asset" "$binary" fi - rm -rf "$workdir" + cleanup done ( diff --git a/site/index.html b/site/index.html index 749697c..f8ea315 100644 --- a/site/index.html +++ b/site/index.html @@ -69,6 +69,7 @@ color: var(--muted); } .note strong { color: var(--text); } + .muted { color: var(--muted); font-size: 0.95rem; } table { border-collapse: collapse; width: 100%; margin: 0.75rem 0; font-size: 0.95rem; } th, td { text-align: left; padding: 0.4rem 0.75rem; border-bottom: 1px solid var(--border); } th { color: var(--muted); font-weight: 600; } @@ -108,6 +109,9 @@

Install (macOS & Linux)

Windows: use install.ps1 (irm https://davis7dotsh.github.io/open-yt-cli/install.ps1 | iex) or grab a zip from the releases page.

+

Prebuilt binaries: Linux and macOS on x86-64 and ARM64, plus Windows x86-64 + (ARM64 Windows runs the x86-64 build under emulation). Each release is a single + self-contained executable — no runtime to install.

Quick setup

# 1. Create a free YouTube Data API v3 key (see the setup guide below)
diff --git a/site/install.ps1 b/site/install.ps1
index 92bbe1b..ad925e5 100644
--- a/site/install.ps1
+++ b/site/install.ps1
@@ -9,17 +9,25 @@
 # Downloads the windows zip from GitHub Releases, verifies its SHA-256
 # against checksums.txt, and installs oytc.exe plus oytc_update.cmd /
 # oytc_upgrade.cmd shims. Never requires administrator rights.
+#
+# Only one Windows build is published: windows/amd64. The toolchain has no
+# native ARM64 Windows target, so ARM64 machines install the amd64 binary and
+# run it under Windows' x64 emulation.
 $ErrorActionPreference = 'Stop'
 
 $Repo = 'davis7dotsh/open-yt-cli'
 
-$arch = switch ((Get-CimInstance Win32_Processor).Architecture) {
-    12 { 'arm64' }   # ARM64
-    9 { 'amd64' }    # x64
-    default {
-        if ([Environment]::Is64BitOperatingSystem) { 'amd64' }
-        else { throw 'oytc requires a 64-bit Windows (amd64 or arm64).' }
-    }
+# The published Windows asset is always amd64; $arch stays a variable so the
+# asset name below keeps the same oytc__windows_.zip shape as
+# the packager and the self-updater.
+$arch = 'amd64'
+$processorArchitecture = @(Get-CimInstance Win32_Processor)[0].Architecture
+if ($processorArchitecture -eq 12) {
+    # ARM64. There is no windows/arm64 asset; Windows on ARM runs x64 binaries
+    # under emulation, so install amd64 rather than failing.
+    Write-Host 'ARM64 Windows detected: installing the amd64 build, which runs under x64 emulation.'
+} elseif ($processorArchitecture -ne 9 -and -not [Environment]::Is64BitOperatingSystem) {
+    throw 'oytc requires a 64-bit Windows (amd64, or arm64 with x64 emulation).'
 }
 
 $version = $env:OYTC_VERSION
diff --git a/site/install.sh b/site/install.sh
index 717b5ab..3bffb4c 100755
--- a/site/install.sh
+++ b/site/install.sh
@@ -10,14 +10,15 @@
 #   OYTC_NO_SYMLINKS  set to 1 to skip the oytc_update/oytc_upgrade symlinks
 #
 # Behavior:
-#   - Detects OS (linux, darwin) and architecture (amd64, arm64).
+#   - Detects OS (linux, darwin) and architecture (amd64, arm64). All four
+#     combinations are published; Windows is served by install.ps1.
 #   - Downloads the release archive and checksums.txt from GitHub Releases.
 #   - Verifies the archive's SHA-256 before extracting anything.
 #   - Installs to a user-writable directory; never requires root by default.
 #   - Creates oytc_update and oytc_upgrade symlinks (self-update aliases).
 #
 # Windows users: this script supports macOS and Linux only. On Windows,
-# download the oytc__windows_.zip asset from
+# download the oytc__windows_amd64.zip asset from
 # https://github.com/davis7dotsh/open-yt-cli/releases, verify its SHA-256
 # against checksums.txt (PowerShell: Get-FileHash -Algorithm SHA256), and
 # place oytc.exe on your PATH.
diff --git a/src/cli/root.ts b/src/cli/root.ts
index 4e8a4d3..1d177c6 100644
--- a/src/cli/root.ts
+++ b/src/cli/root.ts
@@ -21,6 +21,7 @@
 import { Effect, Layer, Result } from "effect"
 import { Command } from "../effect.ts"
 import { AppOptions, ProcessEnv } from "../services/index.ts"
+import { ProcessEnvLive } from "../impl/processEnv.ts"
 import { globalFlags } from "./flags.ts"
 import { resolveGlobals } from "./globals.ts"
 
@@ -47,6 +48,10 @@ export const root = Command.make("oytc").pipe(
         if (Result.isFailure(resolved)) return yield* Effect.fail(resolved.failure)
         return resolved.success
       })
-    )
+      // ProcessEnv is supplied here rather than left to main.ts's
+      // `Effect.provide(AppLayer)`: this layer is constructed by
+      // `Command.provide` during argument parsing, which happens before the
+      // outer provide applies, so the requirement must be discharged locally.
+    ).pipe(Layer.provide(ProcessEnvLive))
   )
 )
diff --git a/src/domain/errors.test.ts b/src/domain/errors.test.ts
index e7266fe..6619be1 100644
--- a/src/domain/errors.test.ts
+++ b/src/domain/errors.test.ts
@@ -167,7 +167,24 @@ describe("statusText", () => {
     expect(statusText(status)).toBe(expected)
   })
 
-  test("unrecognised status yields empty string, not an invented phrase", () => {
-    expect(statusText(599)).toBe("")
+  // Verified against Go 1.26.5 net/http.StatusText by iterating 100..599.
+  test.each([
+    [402, "Payment Required"],
+    [418, "I'm a teapot"],
+    [451, "Unavailable For Legal Reasons"],
+    [507, "Insufficient Storage"],
+    [511, "Network Authentication Required"],
+    [100, "Continue"],
+    [200, "OK"],
+    [308, "Permanent Redirect"]
+  ])("%d -> %s (full table, not just the common codes)", (status, expected) => {
+    expect(statusText(status)).toBe(expected)
   })
+
+  test.each([[599], [509], [512], [0], [99]])(
+    "unrecognised status %d yields empty string, not an invented phrase",
+    (status) => {
+      expect(statusText(status)).toBe("")
+    }
+  )
 })
diff --git a/src/domain/errors.ts b/src/domain/errors.ts
index 8eed551..5b52035 100644
--- a/src/domain/errors.ts
+++ b/src/domain/errors.ts
@@ -15,22 +15,77 @@
 
 import { Data, Runtime } from "effect"
 
-/** HTTP status -> canonical reason phrase, matching Go's http.StatusText. */
+/**
+ * HTTP status -> canonical reason phrase.
+ *
+ * Transcribed verbatim from Go 1.26.5's `net/http.StatusText` (generated by
+ * iterating 100..599). The full table matters: `toApiError` falls back to this
+ * whenever the error envelope carries no message, so a 402/451/507 with an
+ * unparsable body must produce the same user-visible text Go produced.
+ */
 const STATUS_TEXT: Readonly> = {
+  100: "Continue",
+  101: "Switching Protocols",
+  102: "Processing",
+  103: "Early Hints",
+  200: "OK",
+  201: "Created",
+  202: "Accepted",
+  203: "Non-Authoritative Information",
+  204: "No Content",
+  205: "Reset Content",
+  206: "Partial Content",
+  207: "Multi-Status",
+  208: "Already Reported",
+  226: "IM Used",
+  300: "Multiple Choices",
+  301: "Moved Permanently",
+  302: "Found",
+  303: "See Other",
+  304: "Not Modified",
+  305: "Use Proxy",
+  307: "Temporary Redirect",
+  308: "Permanent Redirect",
   400: "Bad Request",
   401: "Unauthorized",
+  402: "Payment Required",
   403: "Forbidden",
   404: "Not Found",
   405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
   408: "Request Timeout",
   409: "Conflict",
   410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
+  413: "Request Entity Too Large",
+  414: "Request URI Too Long",
+  415: "Unsupported Media Type",
+  416: "Requested Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a teapot",
+  421: "Misdirected Request",
+  422: "Unprocessable Entity",
+  423: "Locked",
+  424: "Failed Dependency",
+  425: "Too Early",
+  426: "Upgrade Required",
+  428: "Precondition Required",
   429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  451: "Unavailable For Legal Reasons",
   500: "Internal Server Error",
   501: "Not Implemented",
   502: "Bad Gateway",
   503: "Service Unavailable",
-  504: "Gateway Timeout"
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required"
 }
 
 /** Go's http.StatusText returns "" for unrecognised codes; do not invent one. */
diff --git a/src/impl/analyticsApi.test.ts b/src/impl/analyticsApi.test.ts
new file mode 100644
index 0000000..b8feaec
--- /dev/null
+++ b/src/impl/analyticsApi.test.ts
@@ -0,0 +1,680 @@
+/**
+ * Ported from `internal/analytics/client_test.go` (both cases) plus the
+ * boundary conditions the Go tests leave implicit.
+ *
+ * `HttpCore` is consumed by TAG ONLY — every test here runs against a
+ * `Layer.succeed`/`Layer.mock` double, never the live transport.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Effect, Layer, Result, Schema } from "effect"
+import { encodeListResultJson } from "../domain/listResult.ts"
+import { encodeGoValue } from "../json/encode.ts"
+import { parseJson } from "../json/parse.ts"
+import { isRawNumber, type JsonObject, type JsonValue, rawLiteral, rawNumber } from "../json/value.ts"
+import { AnalyticsResponse } from "../schema/analytics.ts"
+import {
+  type AnalyticsQuery,
+  HttpCore,
+  type HttpCoreRequest,
+  type HttpCoreShape,
+  type Params
+} from "../services/index.ts"
+import {
+  addUtcDays,
+  ANALYTICS_BASE_URL,
+  ANALYTICS_IDS,
+  analyticsListResult,
+  analyticsQueryParams,
+  defaultDateRange,
+  formatDateOnly,
+  makeAnalyticsApiWith,
+  MAX_RESULTS,
+  normalizeAnalytics,
+  resolveLimit,
+  resolveStartIndex,
+  statusCheckDateRange,
+  tolerateNullSlices
+} from "./analyticsApi.ts"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const baseQuery: AnalyticsQuery = {
+  metrics: "views",
+  dimensions: "",
+  filters: "",
+  sort: "",
+  startDate: "2026-01-01",
+  endDate: "2026-01-02",
+  limit: 0,
+  startIndex: 0
+}
+
+const query = (overrides: Partial = {}): AnalyticsQuery => ({
+  ...baseQuery,
+  ...overrides
+})
+
+const paramsOf = (q: AnalyticsQuery): Params => {
+  const r = analyticsQueryParams(q)
+  if (Result.isFailure(r)) throw new Error(`unexpected failure: ${r.failure.message}`)
+  return r.success
+}
+
+const failureOf = (q: AnalyticsQuery): string => {
+  const r = analyticsQueryParams(q)
+  if (Result.isSuccess(r)) throw new Error("expected a failure")
+  return r.failure.message
+}
+
+const asRecord = (params: Params): Record =>
+  Object.fromEntries(params.map(([k, v]) => [k, v]))
+
+const keysOf = (params: Params): ReadonlyArray => params.map(([k]) => k)
+
+const decodeSync = Schema.decodeUnknownSync(AnalyticsResponse)
+
+const parseOk = (text: string): JsonValue => {
+  const r = parseJson(text)
+  if (Result.isFailure(r)) throw new Error(`parse failed: ${r.failure.message}`)
+  return r.success
+}
+
+/** A recording HttpCore double: captures the request, replays a fixed body. */
+interface Recorder {
+  readonly layer: Layer.Layer
+  readonly requests: Array
+}
+
+const recordingHttpCore = (body: JsonValue): Recorder => {
+  const requests: Array = []
+  const shape: HttpCoreShape = {
+    getJson: (request) =>
+      Effect.sync(() => {
+        requests.push(request)
+        return body
+      })
+  }
+  return { layer: Layer.succeed(HttpCore, shape), requests }
+}
+
+const BASE = "http://127.0.0.1:1/youtubeanalytics/v2"
+
+const runReport = (
+  q: AnalyticsQuery,
+  recorder: Recorder,
+  baseUrl = BASE
+): Promise =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      const api = yield* makeAnalyticsApiWith(baseUrl)
+      return yield* api.report(q)
+    }).pipe(Effect.provide(recorder.layer))
+  )
+
+// ---------------------------------------------------------------------------
+// TestReportNormalizesRowsByColumnName (client_test.go)
+// ---------------------------------------------------------------------------
+
+const GO_TEST_BODY =
+  '{"columnHeaders":[{"name":"day","columnType":"DIMENSION","dataType":"STRING"},' +
+  '{"name":"views","columnType":"METRIC","dataType":"INTEGER"},' +
+  '{"name":"estimatedMinutesWatched","columnType":"METRIC","dataType":"FLOAT"}],' +
+  '"rows":[["2026-01-01",12,3.5],["2026-01-02",8,2.25]]}'
+
+describe("report normalizes rows by column name", () => {
+  const goQuery = query({
+    startDate: "2026-01-01",
+    endDate: "2026-01-02",
+    metrics: "views,estimatedMinutesWatched",
+    dimensions: "day",
+    limit: 25
+  })
+
+  test("hits the reports resource on the analytics base, authenticated", async () => {
+    const recorder = recordingHttpCore(parseOk(GO_TEST_BODY))
+    await runReport(goQuery, recorder)
+    expect(recorder.requests).toHaveLength(1)
+    const request = recorder.requests[0]!
+    expect(request.baseUrl).toBe(BASE)
+    expect(request.resource).toBe("reports")
+    // Analytics is OAuth-only; the transport attaches Bearer, never a key.
+    expect(request.authenticate).toBe(true)
+  })
+
+  test("sends the exact query the Go test asserts", async () => {
+    const recorder = recordingHttpCore(parseOk(GO_TEST_BODY))
+    await runReport(goQuery, recorder)
+    const params = asRecord(recorder.requests[0]!.params)
+    expect(params["ids"]).toBe("channel==MINE")
+    expect(params["metrics"]).toBe("views,estimatedMinutesWatched")
+    expect(params["dimensions"]).toBe("day")
+    expect(params["maxResults"]).toBe("25")
+    expect(params["startIndex"]).toBe("1")
+  })
+
+  test("flattens two rows and reports exactly one request", async () => {
+    const recorder = recordingHttpCore(parseOk(GO_TEST_BODY))
+    const response = await runReport(goQuery, recorder)
+    const result = analyticsListResult(response)
+    expect(result.items).toHaveLength(2)
+    expect(result.requests).toBe(1)
+    expect(result.nextPageToken).toBe("")
+    expect(result.items[0]!["day"]).toBe("2026-01-01")
+    expect(result.items[1]!["day"]).toBe("2026-01-02")
+  })
+
+  // The heart of the Go assertion: `views` must be json.Number("12"), not a
+  // float64 that renders as 12.0.
+  test("integer cell 12 stays the literal \"12\", never \"12.0\"", async () => {
+    const recorder = recordingHttpCore(parseOk(GO_TEST_BODY))
+    const response = await runReport(goQuery, recorder)
+    const first = normalizeAnalytics(response)[0]!
+    const views = first["views"]
+    expect(isRawNumber(views)).toBe(true)
+    expect(rawLiteral(views as { readonly $rawNumber: string })).toBe("12")
+    expect(encodeGoValue(views as JsonValue, { indent: "" })).toBe("12")
+    expect(encodeGoValue(first, { indent: "" })).toBe(
+      '{"day":"2026-01-01","estimatedMinutesWatched":3.5,"views":12}'
+    )
+  })
+
+  test("float cells keep their literals too", async () => {
+    const recorder = recordingHttpCore(parseOk(GO_TEST_BODY))
+    const response = await runReport(goQuery, recorder)
+    const items = normalizeAnalytics(response)
+    expect(rawLiteral(items[0]!["estimatedMinutesWatched"] as never)).toBe("3.5")
+    expect(rawLiteral(items[1]!["estimatedMinutesWatched"] as never)).toBe("2.25")
+  })
+
+  test("counters beyond 2^53 survive byte-for-byte", async () => {
+    const recorder = recordingHttpCore(
+      parseOk(
+        '{"columnHeaders":[{"name":"views"}],"rows":[[9007199254740993123]]}'
+      )
+    )
+    const response = await runReport(query(), recorder)
+    const item = normalizeAnalytics(response)[0]!
+    expect(encodeGoValue(item, { indent: "" })).toBe('{"views":9007199254740993123}')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestNormalizeFillsMissingCells (client_test.go)
+// ---------------------------------------------------------------------------
+
+describe("normalize", () => {
+  test("pads a short row with explicit null", () => {
+    const items = normalizeAnalytics({
+      columnHeaders: [{ name: "day" }, { name: "views" }],
+      rows: [["2026-01-01"]]
+    })
+    expect(items).toHaveLength(1)
+    expect(items[0]!["day"]).toBe("2026-01-01")
+    expect(items[0]!["views"]).toBeNull()
+  })
+
+  test("the padded key is PRESENT, not absent", () => {
+    const items = normalizeAnalytics({
+      columnHeaders: [{ name: "day" }, { name: "views" }],
+      rows: [["2026-01-01"]]
+    })
+    expect(Object.keys(items[0] as JsonObject)).toEqual(["day", "views"])
+    expect("views" in (items[0] as object)).toBe(true)
+    expect(encodeGoValue(items[0]!, { indent: "" })).toBe('{"day":"2026-01-01","views":null}')
+  })
+
+  test("drops cells beyond the header list", () => {
+    const items = normalizeAnalytics({
+      columnHeaders: [{ name: "day" }],
+      rows: [["2026-01-01", "extra", rawNumber("7")]]
+    })
+    expect(Object.keys(items[0] as JsonObject)).toEqual(["day"])
+    expect(items[0]!["day"]).toBe("2026-01-01")
+  })
+
+  test("an empty row becomes an all-null object", () => {
+    const items = normalizeAnalytics({
+      columnHeaders: [{ name: "a" }, { name: "b" }],
+      rows: [[]]
+    })
+    expect(items[0]).toEqual({ a: null, b: null })
+  })
+
+  test("no headers yields empty objects, one per row", () => {
+    const items = normalizeAnalytics({ columnHeaders: [], rows: [["x"], ["y"]] })
+    expect(items).toEqual([{}, {}])
+  })
+
+  test("no rows yields an empty array, never null", () => {
+    const items = normalizeAnalytics({ columnHeaders: [{ name: "day" }], rows: [] })
+    expect(items).toEqual([])
+  })
+
+  test("omitted columnHeaders/rows are treated as empty", () => {
+    expect(normalizeAnalytics({})).toEqual([])
+    expect(normalizeAnalytics({ rows: [["x"]] })).toEqual([{}])
+    expect(normalizeAnalytics({ columnHeaders: [{ name: "day" }] })).toEqual([])
+  })
+
+  // Go writes into a map, so a repeated header name keeps the LAST cell.
+  test("duplicate header names collapse, last write winning", () => {
+    const items = normalizeAnalytics({
+      columnHeaders: [{ name: "day" }, { name: "day" }],
+      rows: [["first", "second"]]
+    })
+    expect(items[0]).toEqual({ day: "second" })
+  })
+
+  // Go stores `__proto__` in its map like any other header name. A plain
+  // `item[name] = value` in JS hits the Object.prototype setter instead, so
+  // the column would silently vanish from the output.
+  test("a header named __proto__ becomes a real column, not a prototype write", () => {
+    const items = normalizeAnalytics({
+      columnHeaders: [{ name: "__proto__" }, { name: "views" }],
+      rows: [["2026-01-01", rawNumber("5")]]
+    })
+    expect(Object.keys(items[0] as JsonObject)).toEqual(["__proto__", "views"])
+    expect(Object.getPrototypeOf(items[0])).toBe(Object.prototype)
+    expect(encodeGoValue(items[0]!, { indent: "" })).toBe(
+      '{"__proto__":"2026-01-01","views":5}'
+    )
+  })
+
+  // The dangerous shape: an OBJECT cell under a __proto__ header would
+  // otherwise replace the row's prototype and export zero own keys.
+  test("an object cell under a __proto__ header does not swap the prototype", () => {
+    const items = normalizeAnalytics({
+      columnHeaders: [{ name: "__proto__" }],
+      rows: [[{ evil: "yes" }]]
+    })
+    expect(Object.getPrototypeOf(items[0])).toBe(Object.prototype)
+    expect((items[0] as Record)["evil"]).toBeUndefined()
+    expect(encodeGoValue(items[0]!, { indent: "" })).toBe('{"__proto__":{"evil":"yes"}}')
+  })
+
+  test("duplicate __proto__ headers still collapse last-write-wins", () => {
+    const items = normalizeAnalytics({
+      columnHeaders: [{ name: "__proto__" }, { name: "__proto__" }],
+      rows: [["first", "second"]]
+    })
+    expect(items[0]!["__proto__"]).toBe("second")
+    expect(Object.keys(items[0] as JsonObject)).toEqual(["__proto__"])
+  })
+
+  test("null, boolean and nested cells pass through untouched", () => {
+    const items = normalizeAnalytics({
+      columnHeaders: [{ name: "a" }, { name: "b" }, { name: "c" }],
+      rows: [[null, true, ["x", "y"]]]
+    })
+    expect(items[0]!["a"]).toBeNull()
+    expect(items[0]!["b"]).toBe(true)
+    expect(items[0]!["c"]).toEqual(["x", "y"])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Parameter construction
+// ---------------------------------------------------------------------------
+
+describe("query parameters", () => {
+  test("ids is the hard-coded constant", () => {
+    expect(ANALYTICS_IDS).toBe("channel==MINE")
+    expect(asRecord(paramsOf(query()))["ids"]).toBe("channel==MINE")
+  })
+
+  test("the six unconditional params are always present", () => {
+    expect([...keysOf(paramsOf(query()))].sort()).toEqual([
+      "endDate",
+      "ids",
+      "maxResults",
+      "metrics",
+      "startDate",
+      "startIndex"
+    ])
+  })
+
+  // Go sets startDate/endDate unconditionally; empty dates go on the wire and
+  // Google answers 400. Preserved deliberately — see SPEC_API.md §6.3.
+  test("empty dates are still sent, as empty values", () => {
+    const params = paramsOf(query({ startDate: "", endDate: "" }))
+    expect(keysOf(params)).toContain("startDate")
+    expect(keysOf(params)).toContain("endDate")
+    const record = asRecord(params)
+    expect(record["startDate"]).toBe("")
+    expect(record["endDate"]).toBe("")
+  })
+
+  test.each([
+    ["dimensions", "day"],
+    ["filters", "video==abc"],
+    ["sort", "-views"]
+  ])("%s is omitted when empty and sent when set", (key, value) => {
+    expect(keysOf(paramsOf(query()))).not.toContain(key)
+    const params = paramsOf(query({ [key]: value } as Partial))
+    expect(asRecord(params)[key]).toBe(value)
+  })
+
+  test("all three optional params can appear together", () => {
+    const params = asRecord(
+      paramsOf(query({ dimensions: "ageGroup,gender", filters: "video==abc", sort: "-views" }))
+    )
+    expect(params["dimensions"]).toBe("ageGroup,gender")
+    expect(params["filters"]).toBe("video==abc")
+    expect(params["sort"]).toBe("-views")
+  })
+
+  test("metrics is passed through verbatim", () => {
+    expect(asRecord(paramsOf(query({ metrics: "views,likes" })))["metrics"]).toBe("views,likes")
+  })
+
+  test("empty metrics is rejected", () => {
+    expect(failureOf(query({ metrics: "" }))).toBe("analytics metrics cannot be empty")
+  })
+
+  test("metrics is checked before the limit bounds", () => {
+    expect(failureOf(query({ metrics: "", limit: 999 }))).toBe(
+      "analytics metrics cannot be empty"
+    )
+  })
+
+  test("report fails without ever reaching the transport", async () => {
+    const recorder = recordingHttpCore(parseOk("{}"))
+    const exit = await Effect.runPromise(
+      Effect.exit(
+        Effect.gen(function* () {
+          const api = yield* makeAnalyticsApiWith(BASE)
+          return yield* api.report(query({ metrics: "" }))
+        }).pipe(Effect.provide(recorder.layer))
+      )
+    )
+    expect(exit._tag).toBe("Failure")
+    expect(recorder.requests).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Limit and startIndex resolution — the zero-default-before-range-check rule
+// ---------------------------------------------------------------------------
+
+describe("limit resolution", () => {
+  test("MaxResults is 200", () => {
+    expect(MAX_RESULTS).toBe(200)
+  })
+
+  test.each([
+    [0, 200, "zero means unspecified, resolved BEFORE the range check"],
+    [1, 1, "lower bound"],
+    [25, 25, "the Go test's value"],
+    [200, 200, "upper bound"]
+  ])("limit %d -> maxResults %d (%s)", (input, expected) => {
+    const r = resolveLimit(input)
+    if (!Result.isSuccess(r)) throw new Error("expected a success")
+    expect(r.success).toBe(expected)
+    expect(asRecord(paramsOf(query({ limit: input })))["maxResults"]).toBe(String(expected))
+  })
+
+  test.each([
+    [201, "just past the upper bound"],
+    [1000, "far past the upper bound"],
+    [-1, "negative, NOT rescued by the zero-default"],
+    [-200, "negative magnitude is irrelevant"]
+  ])("limit %d is rejected (%s)", (input) => {
+    expect(failureOf(query({ limit: input }))).toBe("analytics limit must be between 1 and 200")
+  })
+
+  // Order matters: if the range check ran first, 0 would be an error too.
+  test("0 is valid but -1 is not — proof the zero-default runs first", () => {
+    expect(Result.isSuccess(resolveLimit(0))).toBe(true)
+    expect(Result.isFailure(resolveLimit(-1))).toBe(true)
+  })
+})
+
+describe("startIndex resolution", () => {
+  test("0 becomes 1", () => {
+    expect(resolveStartIndex(0)).toBe(1)
+    expect(asRecord(paramsOf(query({ startIndex: 0 })))["startIndex"]).toBe("1")
+  })
+
+  test.each([1, 2, 201, 100_000])("%d passes through unchanged", (input) => {
+    expect(resolveStartIndex(input)).toBe(input)
+    expect(asRecord(paramsOf(query({ startIndex: input })))["startIndex"]).toBe(String(input))
+  })
+
+  // Go range-checks startIndex nowhere; a negative is sent verbatim.
+  test("negatives are sent verbatim, not validated", () => {
+    expect(resolveStartIndex(-5)).toBe(-5)
+    expect(asRecord(paramsOf(query({ startIndex: -5 })))["startIndex"]).toBe("-5")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Envelope
+// ---------------------------------------------------------------------------
+
+describe("list envelope", () => {
+  test("requests is always exactly 1", () => {
+    expect(analyticsListResult({}).requests).toBe(1)
+    expect(analyticsListResult({ columnHeaders: [], rows: [] }).requests).toBe(1)
+    expect(
+      analyticsListResult({ columnHeaders: [{ name: "a" }], rows: [["x"], ["y"]] }).requests
+    ).toBe(1)
+  })
+
+  test("nextPageToken is always empty — no analytics pagination", () => {
+    expect(analyticsListResult({ columnHeaders: [{ name: "a" }], rows: [["x"]] }).nextPageToken)
+      .toBe("")
+  })
+
+  test("an empty report yields an empty items array", () => {
+    expect(analyticsListResult({}).items).toEqual([])
+  })
+
+  // Golden: byte-for-byte output of the equivalent Go program (`go run`,
+  // json.Encoder with SetIndent("", "  ") over the same ListResult struct).
+  test.each([
+    [
+      '{"columnHeaders":[{"name":"day"},{"name":"views"}],"rows":[["2026-01-01",12],["2026-01-02",8]]}',
+      '{\n  "items": [\n    {\n      "day": "2026-01-01",\n      "views": 12\n    },\n' +
+        '    {\n      "day": "2026-01-02",\n      "views": 8\n    }\n  ],\n  "requests": 1\n}\n'
+    ],
+    ['{"columnHeaders":[{"name":"day"}],"rows":[]}', '{\n  "items": [],\n  "requests": 1\n}\n'],
+    ["{}", '{\n  "items": [],\n  "requests": 1\n}\n']
+  ])("envelope for %s matches the Go encoder byte-for-byte", (body, expected) => {
+    expect(encodeListResultJson(analyticsListResult(decodeSync(parseOk(body))))).toBe(expected)
+  })
+
+  // nextPageToken carries `omitempty` in Go and is never set by analytics, so
+  // the key must not appear at all.
+  test("the envelope omits nextPageToken entirely", () => {
+    expect(
+      encodeListResultJson(analyticsListResult({ columnHeaders: [{ name: "a" }], rows: [["x"]] }))
+    ).not.toContain("nextPageToken")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Transport surface
+// ---------------------------------------------------------------------------
+
+describe("transport", () => {
+  test("the default base URL is the analytics v2 host", () => {
+    expect(ANALYTICS_BASE_URL).toBe("https://youtubeanalytics.googleapis.com/v2")
+  })
+
+  test("the base URL is injectable, so tests can point at a local server", async () => {
+    const recorder = recordingHttpCore(parseOk("{}"))
+    await runReport(query(), recorder, "http://localhost:9/v2")
+    expect(recorder.requests[0]!.baseUrl).toBe("http://localhost:9/v2")
+  })
+
+  test("exactly one request per report — no token loop", async () => {
+    const recorder = recordingHttpCore(parseOk(GO_TEST_BODY))
+    await runReport(query(), recorder)
+    expect(recorder.requests).toHaveLength(1)
+  })
+
+  test("transport failures propagate untouched", async () => {
+    const failing = Layer.succeed(HttpCore, {
+      getJson: () => Effect.die("boom")
+    } satisfies HttpCoreShape)
+    const exit = await Effect.runPromise(
+      Effect.exit(
+        Effect.gen(function* () {
+          const api = yield* makeAnalyticsApiWith(BASE)
+          return yield* api.report(query())
+        }).pipe(Effect.provide(failing))
+      )
+    )
+    expect(exit._tag).toBe("Failure")
+  })
+
+  test("a response with unknown extra keys still decodes", async () => {
+    const recorder = recordingHttpCore(
+      parseOk('{"kind":"youtubeAnalytics#resultTable","columnHeaders":[{"name":"day"}],"rows":[["x"]]}')
+    )
+    const response = await runReport(query(), recorder)
+    expect(normalizeAnalytics(response)).toEqual([{ day: "x" }])
+  })
+
+  test("an empty JSON object decodes to an empty report", async () => {
+    const recorder = recordingHttpCore(parseOk("{}"))
+    const response = await runReport(query(), recorder)
+    expect(analyticsListResult(response).items).toEqual([])
+  })
+
+  // Go's encoding/json unmarshals a JSON null into a slice field as a nil
+  // slice with NO error, so these are valid empty reports there. Verified
+  // against Go 1.26.5; the frozen schema would reject the explicit null, so
+  // the client strips it first.
+  test.each([
+    '{"rows":null}',
+    '{"columnHeaders":null}',
+    '{"columnHeaders":null,"rows":null}',
+    '{"columnHeaders":[{"name":"day"}],"rows":null}'
+  ])("%s decodes to an empty report, matching Go", async (body) => {
+    const recorder = recordingHttpCore(parseOk(body))
+    const response = await runReport(query(), recorder)
+    expect(analyticsListResult(response).items).toEqual([])
+  })
+
+  test("a null row list does not disturb the headers", async () => {
+    const recorder = recordingHttpCore(parseOk('{"columnHeaders":[{"name":"day"}],"rows":null}'))
+    const response = await runReport(query(), recorder)
+    expect(response.columnHeaders).toEqual([{ name: "day" }])
+  })
+
+  test("tolerateNullSlices leaves everything else untouched", () => {
+    const body = parseOk('{"kind":"x","columnHeaders":[{"name":"day"}],"rows":[["x"]]}')
+    expect(tolerateNullSlices(body)).toBe(body)
+    expect(tolerateNullSlices(parseOk('{"other":null}'))).toEqual({ other: null })
+    expect(tolerateNullSlices(parseOk("[1,2]"))).toEqual([rawNumber("1"), rawNumber("2")])
+  })
+
+  // Go: fmt.Errorf("decode YouTube API response: %w", err) — an OperationalError,
+  // which exits 6.
+  test.each([
+    ['{"rows":"nope"}', "rows is not an array"],
+    ['{"columnHeaders":[{"name":123}]}', "header name is not a string"],
+    ["[1,2,3]", "body is not an object"]
+  ])("%s fails to decode (%s)", async (body) => {
+    const recorder = recordingHttpCore(parseOk(body))
+    const exit = await Effect.runPromise(
+      Effect.exit(
+        Effect.gen(function* () {
+          const api = yield* makeAnalyticsApiWith(BASE)
+          return yield* api.report(query())
+        }).pipe(Effect.provide(recorder.layer))
+      )
+    )
+    expect(exit._tag).toBe("Failure")
+  })
+
+  test("a decode failure is an OperationalError with Go's message prefix", async () => {
+    const recorder = recordingHttpCore(parseOk('{"rows":"nope"}'))
+    const result = await Effect.runPromise(
+      Effect.result(
+        Effect.gen(function* () {
+          const api = yield* makeAnalyticsApiWith(BASE)
+          return yield* api.report(query())
+        }).pipe(Effect.provide(recorder.layer))
+      )
+    )
+    if (!Result.isFailure(result)) throw new Error("expected a failure")
+    expect(result.failure._tag).toBe("OperationalError")
+    expect(result.failure.message).toStartWith("decode YouTube API response: ")
+  })
+
+  test("normalize is exposed on the service", async () => {
+    const recorder = recordingHttpCore(parseOk("{}"))
+    const items = await Effect.runPromise(
+      Effect.gen(function* () {
+        const api = yield* makeAnalyticsApiWith(BASE)
+        return api.normalize({ columnHeaders: [{ name: "day" }], rows: [["x"]] })
+      }).pipe(Effect.provide(recorder.layer))
+    )
+    expect(items).toEqual([{ day: "x" }])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Date ranges — UTC, always
+// ---------------------------------------------------------------------------
+
+describe("date helpers", () => {
+  test.each([
+    ["2026-03-01T05:00:00Z", "2026-02-01", "2026-02-28"],
+    ["2026-01-01T00:00:00Z", "2025-12-04", "2025-12-31"],
+    ["2024-03-01T23:59:59Z", "2024-02-02", "2024-02-29"],
+    ["2026-07-24T12:00:00Z", "2026-06-26", "2026-07-23"],
+    ["2025-01-15T00:00:00Z", "2024-12-18", "2025-01-14"]
+  ])("default range at %s is %s..%s", (now, start, end) => {
+    // Values produced by `go run` against the Go expression
+    //   end := now().UTC().AddDate(0,0,-1); start := end.AddDate(0,0,-27)
+    expect(defaultDateRange(new Date(now))).toEqual({ start, end })
+  })
+
+  test("the window is 28 inclusive days: end - 27, not end - 28", () => {
+    const { start, end } = defaultDateRange(new Date("2026-07-24T12:00:00Z"))
+    const days =
+      (Date.parse(`${end}T00:00:00Z`) - Date.parse(`${start}T00:00:00Z`)) / 86_400_000
+    expect(days).toBe(27)
+  })
+
+  test("today is excluded — end is yesterday", () => {
+    expect(defaultDateRange(new Date("2026-07-24T00:00:00Z")).end).toBe("2026-07-23")
+  })
+
+  // A local-time computation would give a different answer either side of
+  // midnight UTC; this pins the UTC reading.
+  test("computed in UTC, not local time", () => {
+    const justAfterUtcMidnight = new Date("2026-07-24T00:30:00Z")
+    const justBeforeUtcMidnight = new Date("2026-07-23T23:30:00Z")
+    expect(defaultDateRange(justAfterUtcMidnight).end).toBe("2026-07-23")
+    expect(defaultDateRange(justBeforeUtcMidnight).end).toBe("2026-07-22")
+  })
+
+  test("status --check probes a 7-day window that INCLUDES today", () => {
+    expect(statusCheckDateRange(new Date("2026-07-24T12:00:00Z"))).toEqual({
+      start: "2026-07-17",
+      end: "2026-07-24"
+    })
+  })
+
+  test.each([
+    ["2026-07-24T12:00:00Z", "2026-07-24"],
+    ["0999-01-02T00:00:00Z", "0999-01-02"],
+    ["2026-01-09T00:00:00Z", "2026-01-09"]
+  ])("formatDateOnly(%s) = %s (zero-padded, Go's time.DateOnly)", (input, expected) => {
+    expect(formatDateOnly(new Date(input))).toBe(expected)
+  })
+
+  test("addUtcDays rolls over months, years and leap days", () => {
+    expect(formatDateOnly(addUtcDays(new Date("2026-01-31T00:00:00Z"), 1))).toBe("2026-02-01")
+    expect(formatDateOnly(addUtcDays(new Date("2026-01-01T00:00:00Z"), -1))).toBe("2025-12-31")
+    expect(formatDateOnly(addUtcDays(new Date("2024-02-28T00:00:00Z"), 1))).toBe("2024-02-29")
+    expect(formatDateOnly(addUtcDays(new Date("2025-02-28T00:00:00Z"), 1))).toBe("2025-03-01")
+  })
+})
diff --git a/src/impl/analyticsApi.ts b/src/impl/analyticsApi.ts
index ca14f9a..48577d0 100644
--- a/src/impl/analyticsApi.ts
+++ b/src/impl/analyticsApi.ts
@@ -1,2 +1,267 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * YouTube Analytics reports client — the port of `internal/analytics/client.go`.
+ *
+ * One endpoint, no pagination, no token loop: `GET {base}/reports` decoded into
+ * the typed `columnHeaders`/`rows` shape and flattened into row objects.
+ *
+ * Analytics is **OAuth-only**. The Go constructor builds its transport with an
+ * empty API key, so the API-key branch of the auth switch can never fire; here
+ * that falls out of `authenticate: true` plus a `HttpCore` whose token source
+ * strictly beats the key. Retries, the 401-refresh-once dance, the 16 MiB cap,
+ * number-preserving decoding, and `ApiError` construction all live in
+ * `HttpCore` and are inherited unchanged.
+ *
+ * This module depends on `HttpCore` BY TAG ONLY.
+ */
+
+import { Effect, Layer, Result, Schema } from "effect"
+import { OperationalError, type OytcError } from "../domain/errors.ts"
+import type { ListResult } from "../domain/listResult.ts"
+import type { JsonObject, JsonValue } from "../json/value.ts"
+import { AnalyticsResponse } from "../schema/analytics.ts"
+import {
+  AnalyticsApi,
+  type AnalyticsApiShape,
+  type AnalyticsQuery,
+  HttpCore,
+  type HttpCoreShape,
+  type Params
+} from "../services/index.ts"
+
+/** `analytics.DefaultBaseURL`. */
+export const ANALYTICS_BASE_URL = "https://youtubeanalytics.googleapis.com/v2"
+
+/** `analytics.MaxResults`. Also the CLI's `--limit` upper bound. */
+export const MAX_RESULTS = 200
+
+/**
+ * `ids` is a hard-coded literal in Go — there is no support for
+ * `contentOwner==`, `channel==`, or any other owner form.
+ */
+export const ANALYTICS_IDS = "channel==MINE"
+
+const RESOURCE = "reports"
+
+// ---------------------------------------------------------------------------
+// Query resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Go's exact order of operations:
+ *
+ *   limit := query.Limit
+ *   if limit == 0 { limit = MaxResults }        // zero-default FIRST
+ *   if limit < 1 || limit > MaxResults { err }  // range check SECOND
+ *
+ * so `0` is legal and means 200, while `-1` and `201` are both errors.
+ */
+export const resolveLimit = (limit: number): Result.Result => {
+  const resolved = limit === 0 ? MAX_RESULTS : limit
+  if (resolved < 1 || resolved > MAX_RESULTS) {
+    return Result.fail(
+      new OperationalError({ message: `analytics limit must be between 1 and ${MAX_RESULTS}` })
+    )
+  }
+  return Result.succeed(resolved)
+}
+
+/**
+ * `0` means "unspecified" and becomes the 1-based first row. Everything else,
+ * negatives included, is sent verbatim — Go range-checks this value nowhere.
+ */
+export const resolveStartIndex = (startIndex: number): number =>
+  startIndex === 0 ? 1 : startIndex
+
+/**
+ * The `reports` query string.
+ *
+ * `ids`, `startDate`, `endDate`, `metrics`, `maxResults` and `startIndex` are
+ * ALWAYS present — including `startDate=&endDate=` when the caller left the
+ * dates empty, which Google answers with a 400. That is Go's behaviour and it
+ * is preserved deliberately; the CLI always fills the dates from computed flag
+ * defaults, so an empty date only reaches here through a direct library call.
+ *
+ * `dimensions`, `filters` and `sort` are sent only when non-empty.
+ */
+export const analyticsQueryParams = (
+  query: AnalyticsQuery
+): Result.Result => {
+  if (query.metrics === "") {
+    return Result.fail(new OperationalError({ message: "analytics metrics cannot be empty" }))
+  }
+  const limit = resolveLimit(query.limit)
+  if (Result.isFailure(limit)) return Result.fail(limit.failure)
+  const startIndex = resolveStartIndex(query.startIndex)
+
+  const params: Array = [
+    ["ids", ANALYTICS_IDS],
+    ["startDate", query.startDate],
+    ["endDate", query.endDate],
+    ["metrics", query.metrics],
+    ["maxResults", String(limit.success)],
+    ["startIndex", String(startIndex)]
+  ]
+  if (query.dimensions !== "") params.push(["dimensions", query.dimensions])
+  if (query.filters !== "") params.push(["filters", query.filters])
+  if (query.sort !== "") params.push(["sort", query.sort])
+  return Result.succeed(params)
+}
+
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * `analytics.Normalize` — flatten `columnHeaders` + `rows` into row objects.
+ *
+ *   - a row SHORTER than the header list is padded with explicit `null`
+ *     (Go writes the nil into the map; the key is present, not absent)
+ *   - a row LONGER than the header list has its extra cells dropped
+ *     (the loop is over headers, not over cells)
+ *   - duplicate header names collapse, last write winning, as Go's map does
+ *
+ * Cell values arrive as `JsonValue`, so a numeric cell is a `RawNumber` holding
+ * its original literal: the integer `12` re-encodes as `12`, never `12.0`.
+ *
+ * Keys are installed with `Object.defineProperty`, not `item[name] = …`. A
+ * header literally named `__proto__` — which Go stores in its map like any
+ * other string — would otherwise hit the `Object.prototype` setter: the column
+ * would VANISH from the output (or, for an object-valued cell, silently
+ * replace the row's prototype). `defineProperty` creates a plain own property
+ * for every name, so `__proto__` round-trips as a column like Go's does.
+ */
+export const normalizeAnalytics = (
+  response: AnalyticsResponse
+): ReadonlyArray => {
+  const headers = response.columnHeaders ?? []
+  const rows = response.rows ?? []
+  return rows.map((row) => {
+    const item: Record = {}
+    for (let index = 0; index < headers.length; index++) {
+      const name = headers[index]!.name
+      Object.defineProperty(item, name, {
+        value: index < row.length ? (row[index] as JsonValue) : null,
+        enumerable: true,
+        writable: true,
+        configurable: true
+      })
+    }
+    return item
+  })
+}
+
+/**
+ * The list envelope Go's `Report` returns. `requests` is always exactly 1 —
+ * there is no second request and no token pagination — and `nextPageToken` is
+ * always empty, so the JSON envelope omits it.
+ */
+export const analyticsListResult = (response: AnalyticsResponse): ListResult => ({
+  items: normalizeAnalytics(response),
+  nextPageToken: "",
+  requests: 1
+})
+
+// ---------------------------------------------------------------------------
+// Date ranges
+// ---------------------------------------------------------------------------
+
+const pad = (value: number, width: number): string => String(value).padStart(width, "0")
+
+/** Go's `time.DateOnly` (`2006-01-02`) formatting of a UTC instant. */
+export const formatDateOnly = (date: Date): string =>
+  `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}`
+
+/** `AddDate(0, 0, days)` in UTC. `Date.UTC` normalizes month/year rollover. */
+export const addUtcDays = (date: Date, days: number): Date =>
+  new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + days))
+
+export interface DateRange {
+  readonly start: string
+  readonly end: string
+}
+
+/**
+ * The `--start`/`--end` flag defaults: 28 complete UTC days ending YESTERDAY.
+ *
+ *   end   = todayUTC - 1 day
+ *   start = end - 27 days     // NOT end - 28: the window is inclusive
+ *
+ * Today is excluded because Analytics data for the current day is incomplete.
+ * Computed in UTC, never local time — a machine in UTC+13 must not report a
+ * different default window from one in UTC-8.
+ */
+export const defaultDateRange = (now: Date): DateRange => {
+  const end = addUtcDays(now, -1)
+  return { start: formatDateOnly(addUtcDays(end, -27)), end: formatDateOnly(end) }
+}
+
+/**
+ * The range `status --check` probes with. Note it INCLUDES today, unlike the
+ * command defaults: it is a liveness probe, not a report.
+ */
+export const statusCheckDateRange = (now: Date): DateRange => ({
+  start: formatDateOnly(addUtcDays(now, -7)),
+  end: formatDateOnly(now)
+})
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+const decodeResponse = Schema.decodeUnknownEffect(AnalyticsResponse)
+
+/**
+ * Go decodes into `[]ColumnHeader` / `[][]any`, and `encoding/json` unmarshals
+ * a JSON `null` into a slice as a **nil slice with no error** — so
+ * `{"rows":null}` is a valid empty report there. `Schema.optional(Schema.Array)`
+ * rejects an explicit `null`, so drop those keys before decoding to keep the
+ * two implementations in agreement. Verified against Go 1.26.5.
+ */
+export const tolerateNullSlices = (body: JsonValue): JsonValue => {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) return body
+  const record = body as { readonly [key: string]: JsonValue }
+  if (record["columnHeaders"] !== null && record["rows"] !== null) return body
+  const out: Record = {}
+  for (const [key, value] of Object.entries(record)) {
+    if (value === null && (key === "columnHeaders" || key === "rows")) continue
+    out[key] = value
+  }
+  return out
+}
+
+/** Go: `fmt.Errorf("decode YouTube API response: %w", err)` — exit 6. */
+const decodeAnalyticsResponse = (
+  body: JsonValue
+): Effect.Effect =>
+  decodeResponse(tolerateNullSlices(body)).pipe(
+    Effect.catchTag("SchemaError", (cause) =>
+      Effect.fail(
+        new OperationalError({ message: `decode YouTube API response: ${cause.message}`, cause })
+      )
+    )
+  )
+
+export const makeAnalyticsApiWith = (
+  baseUrl: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const http = yield* HttpCore
+    return {
+      report: (query: AnalyticsQuery): Effect.Effect =>
+        Effect.gen(function* () {
+          const params = yield* Effect.fromResult(analyticsQueryParams(query))
+          const body = yield* http.getJson({
+            baseUrl,
+            resource: RESOURCE,
+            params,
+            authenticate: true
+          })
+          return yield* decodeAnalyticsResponse(body)
+        }),
+      normalize: normalizeAnalytics
+    } satisfies AnalyticsApiShape
+  })
+
+export const makeAnalyticsApi = makeAnalyticsApiWith(ANALYTICS_BASE_URL)
+
+export const AnalyticsApiLive = Layer.effect(AnalyticsApi, makeAnalyticsApi)
diff --git a/src/impl/archive.test.ts b/src/impl/archive.test.ts
new file mode 100644
index 0000000..078658f
--- /dev/null
+++ b/src/impl/archive.test.ts
@@ -0,0 +1,369 @@
+import { describe, expect, test } from "bun:test"
+import { gzipSync } from "node:zlib"
+import { Effect, Exit } from "effect"
+import { BunServices } from "@effect/platform-bun"
+// The stock JSON encoder is confined to src/json/encode.ts (CI greps for it),
+// so test names quote their inputs with the project's own Go-faithful encoder.
+import { encodeGoString } from "../json/encode.ts"
+import {
+  extractBinary,
+  extractFromTarGzBytes,
+  extractFromZipBytes,
+  goPathClean,
+  safeEntryMatch
+} from "./archive.ts"
+
+// ---------------------------------------------------------------------------
+// Fixtures — the TS equivalents of the Go tests' tarGzWithEntry / zipWithEntry
+// ---------------------------------------------------------------------------
+
+const encoder = new TextEncoder()
+
+const octal = (value: number, width: number): string =>
+  value.toString(8).padStart(width - 1, "0") + "\0"
+
+/** One-entry tar, ustar format, matching what `archive/tar` emits. */
+const tarWithEntry = (
+  name: string,
+  content: Uint8Array,
+  typeflag = "0"
+): Uint8Array => {
+  const header = new Uint8Array(512)
+  const put = (offset: number, text: string) => header.set(encoder.encode(text), offset)
+
+  put(0, name.slice(0, 100))
+  put(100, octal(0o755, 8))
+  put(108, octal(0, 8))
+  put(116, octal(0, 8))
+  put(124, octal(content.length, 12))
+  put(136, octal(0, 12))
+  header[156] = typeflag.charCodeAt(0)
+  put(257, "ustar\0")
+  put(263, "00")
+
+  // Checksum: the field is treated as spaces while summing.
+  header.fill(0x20, 148, 156)
+  let sum = 0
+  for (const byte of header) sum += byte
+  put(148, `${sum.toString(8).padStart(6, "0")}\0 `)
+
+  const padding = (512 - (content.length % 512)) % 512
+  const out = new Uint8Array(512 + content.length + padding + 1024)
+  out.set(header, 0)
+  out.set(content, 512)
+  return out
+}
+
+const tarGzWithEntry = (
+  name: string,
+  content: Uint8Array,
+  typeflag = "0"
+): Uint8Array => new Uint8Array(gzipSync(tarWithEntry(name, content, typeflag)))
+
+const crcTable = (() => {
+  const table = new Uint32Array(256)
+  for (let i = 0; i < 256; i++) {
+    let c = i
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    table[i] = c >>> 0
+  }
+  return table
+})()
+
+const crc32 = (bytes: Uint8Array): number => {
+  let c = 0xffffffff
+  for (const byte of bytes) c = crcTable[(c ^ byte) & 0xff]! ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+/** One-entry STORED zip with a proper central directory and EOCD. */
+const zipWithEntry = (name: string, content: Uint8Array): Uint8Array => {
+  const nameBytes = encoder.encode(name)
+  const crc = crc32(content)
+  const size = content.length
+
+  const local = new Uint8Array(30 + nameBytes.length + size)
+  const lv = new DataView(local.buffer)
+  lv.setUint32(0, 0x04034b50, true)
+  lv.setUint16(4, 20, true)
+  lv.setUint16(8, 0, true) // stored
+  lv.setUint32(14, crc, true)
+  lv.setUint32(18, size, true)
+  lv.setUint32(22, size, true)
+  lv.setUint16(26, nameBytes.length, true)
+  local.set(nameBytes, 30)
+  local.set(content, 30 + nameBytes.length)
+
+  const central = new Uint8Array(46 + nameBytes.length)
+  const cv = new DataView(central.buffer)
+  cv.setUint32(0, 0x02014b50, true)
+  cv.setUint16(4, 20, true)
+  cv.setUint16(6, 20, true)
+  cv.setUint16(10, 0, true)
+  cv.setUint32(16, crc, true)
+  cv.setUint32(20, size, true)
+  cv.setUint32(24, size, true)
+  cv.setUint16(28, nameBytes.length, true)
+  cv.setUint32(42, 0, true)
+  central.set(nameBytes, 46)
+
+  const eocd = new Uint8Array(22)
+  const ev = new DataView(eocd.buffer)
+  ev.setUint32(0, 0x06054b50, true)
+  ev.setUint16(8, 1, true)
+  ev.setUint16(10, 1, true)
+  ev.setUint32(12, central.length, true)
+  ev.setUint32(16, local.length, true)
+
+  const out = new Uint8Array(local.length + central.length + eocd.length)
+  out.set(local, 0)
+  out.set(central, local.length)
+  out.set(eocd, local.length + central.length)
+  return out
+}
+
+const bytes = (text: string): Uint8Array => encoder.encode(text)
+const text = (data: Uint8Array): string => new TextDecoder().decode(data)
+
+const runExit = (effect: Effect.Effect) => Effect.runPromiseExit(effect)
+
+const runFs = (effect: Effect.Effect) =>
+  Effect.runPromiseExit(effect.pipe(Effect.provide(BunServices.layer)) as Effect.Effect)
+
+const failureMessage = (exit: Exit.Exit): string => {
+  if (Exit.isSuccess(exit)) throw new Error("expected a failure")
+  return String(exit.cause)
+}
+
+// ---------------------------------------------------------------------------
+
+describe("goPathClean", () => {
+  /** Verified row by row against a Go program calling path.Clean. */
+  const cases: ReadonlyArray = [
+    ["", "."],
+    [".", "."],
+    ["/", "/"],
+    ["oytc", "oytc"],
+    ["./oytc", "oytc"],
+    ["oytc/", "oytc"],
+    ["/oytc", "/oytc"],
+    ["//oytc", "/oytc"],
+    ["../oytc", "../oytc"],
+    ["nested/oytc", "nested/oytc"],
+    ["a/../oytc", "oytc"],
+    ["./././oytc", "oytc"],
+    ["oytc/.", "oytc"],
+    ["/../oytc", "/oytc"],
+    ["a//b/../../oytc", "oytc"],
+    ["oytc//", "oytc"],
+    ["/oytc/", "/oytc"],
+    ["...", "..."],
+    ["..", ".."],
+    ["a/..", "."],
+    ["oytc.exe", "oytc.exe"]
+  ]
+
+  for (const [input, want] of cases) {
+    test(`Clean(${encodeGoString(input)}) = ${encodeGoString(want)}`, () => {
+      expect(goPathClean(input)).toBe(want)
+    })
+  }
+
+  test("differs from node's posix normalize on a trailing slash, which is why it exists", () => {
+    // node: "oytc/" -> "oytc/"; Go: "oytc/" -> "oytc". Using node's would let
+    // an entry named "oytc/" slip past the exact-match check.
+    expect(goPathClean("oytc/")).toBe("oytc")
+  })
+})
+
+describe("safeEntryMatch — the path-traversal defense", () => {
+  test("accepts the exact expected name", () => {
+    expect(safeEntryMatch("oytc", "oytc")).toBe(true)
+    expect(safeEntryMatch("./oytc", "oytc")).toBe(true)
+    expect(safeEntryMatch("oytc.exe", "oytc.exe")).toBe(true)
+  })
+
+  test("rejects traversal, absolute and nested paths", () => {
+    for (const entry of ["../oytc", "/oytc", "nested/oytc", "..\\oytc", "a/b/oytc", "/../oytc"]) {
+      expect(safeEntryMatch(entry, "oytc")).toBe(false)
+    }
+  })
+
+  test("normalizes backslashes before cleaning, so ..\\oytc cannot sneak through", () => {
+    // Without the replaceAll, path.Clean would leave "..\oytc" intact and it
+    // would compare unequal but reach the filesystem as a literal filename.
+    expect(safeEntryMatch("..\\oytc", "oytc")).toBe(false)
+    expect(safeEntryMatch(".\\oytc", "oytc")).toBe(true)
+  })
+
+  test("rejects a name that merely contains the expected one", () => {
+    expect(safeEntryMatch("oytc2", "oytc")).toBe(false)
+    expect(safeEntryMatch("myoytc", "oytc")).toBe(false)
+    expect(safeEntryMatch("oytc.exe", "oytc")).toBe(false)
+  })
+})
+
+/** Port of Go's `TestExtractRejectsPathTraversal`, same four entries. */
+describe("TestExtractRejectsPathTraversal", () => {
+  for (const entry of ["../oytc", "/oytc", "nested/oytc", "..\\oytc"]) {
+    test(`tar entry ${encodeGoString(entry)} is refused`, async () => {
+      const archive = tarGzWithEntry(entry, bytes("evil"))
+      const exit = await runExit(extractFromTarGzBytes(archive, "oytc"))
+      expect(failureMessage(exit)).toContain("does not contain")
+    })
+
+    test(`zip entry ${encodeGoString(entry)} is refused`, async () => {
+      const archive = zipWithEntry(entry, bytes("evil"))
+      const exit = await runExit(extractFromZipBytes(archive, "oytc"))
+      expect(failureMessage(exit)).toContain("does not contain")
+    })
+  }
+})
+
+describe("extractFromTarGzBytes", () => {
+  test("extracts the binary at the archive root", async () => {
+    const exit = await runExit(extractFromTarGzBytes(tarGzWithEntry("oytc", bytes("payload")), "oytc"))
+    expect(Exit.isSuccess(exit)).toBe(true)
+    if (Exit.isSuccess(exit)) expect(text(exit.value)).toBe("payload")
+  })
+
+  test("preserves binary content byte for byte", async () => {
+    const content = new Uint8Array(4096)
+    for (let i = 0; i < content.length; i++) content[i] = i % 256
+    const exit = await runExit(extractFromTarGzBytes(tarGzWithEntry("oytc", content), "oytc"))
+    if (!Exit.isSuccess(exit)) throw new Error("expected success")
+    expect(exit.value).toEqual(content)
+  })
+
+  test("an empty entry extracts as empty rather than failing", async () => {
+    const exit = await runExit(
+      extractFromTarGzBytes(tarGzWithEntry("oytc", new Uint8Array(0)), "oytc")
+    )
+    if (!Exit.isSuccess(exit)) throw new Error("expected success")
+    expect(exit.value.length).toBe(0)
+  })
+
+  test("skips non-regular entries — a symlink named oytc is not the binary", async () => {
+    // typeflag "2" is a symlink. Go's `header.Typeflag != tar.TypeReg` skip is
+    // what stops an archive from redirecting the write through a link.
+    const exit = await runExit(
+      extractFromTarGzBytes(tarGzWithEntry("oytc", bytes("evil"), "2"), "oytc")
+    )
+    expect(failureMessage(exit)).toContain('does not contain "oytc"')
+  })
+
+  test("skips directory entries", async () => {
+    const exit = await runExit(
+      extractFromTarGzBytes(tarGzWithEntry("oytc", new Uint8Array(0), "5"), "oytc")
+    )
+    expect(failureMessage(exit)).toContain("does not contain")
+  })
+
+  test("accepts TypeRegA (NUL typeflag), which Go's reader normalizes to a regular file", async () => {
+    const exit = await runExit(
+      extractFromTarGzBytes(tarGzWithEntry("oytc", bytes("old-format"), "\0"), "oytc")
+    )
+    if (!Exit.isSuccess(exit)) throw new Error("expected success")
+    expect(text(exit.value)).toBe("old-format")
+  })
+
+  test("reports a missing entry, not a crash, for an archive of something else", async () => {
+    const exit = await runExit(extractFromTarGzBytes(tarGzWithEntry("README", bytes("x")), "oytc"))
+    expect(failureMessage(exit)).toContain('release archive does not contain "oytc"')
+  })
+
+  test("non-gzip input fails as an unreadable archive", async () => {
+    const exit = await runExit(extractFromTarGzBytes(bytes("this is not gzip"), "oytc"))
+    expect(failureMessage(exit)).toContain("open release archive")
+  })
+
+  test("truncated gzip fails rather than returning partial bytes", async () => {
+    const full = tarGzWithEntry("oytc", bytes("payload"))
+    const exit = await runExit(extractFromTarGzBytes(full.subarray(0, full.length - 10), "oytc"))
+    expect(Exit.isSuccess(exit)).toBe(false)
+  })
+
+  test("looks for oytc.exe when that is what was asked for", async () => {
+    const archive = tarGzWithEntry("oytc.exe", bytes("win"))
+    const found = await runExit(extractFromTarGzBytes(archive, "oytc.exe"))
+    if (!Exit.isSuccess(found)) throw new Error("expected success")
+    expect(text(found.value)).toBe("win")
+
+    const missing = await runExit(extractFromTarGzBytes(archive, "oytc"))
+    expect(failureMessage(missing)).toContain("does not contain")
+  })
+})
+
+describe("extractFromZipBytes", () => {
+  test("extracts a stored entry", async () => {
+    const exit = await runExit(extractFromZipBytes(zipWithEntry("oytc.exe", bytes("winbin")), "oytc.exe"))
+    if (!Exit.isSuccess(exit)) throw new Error("expected success")
+    expect(text(exit.value)).toBe("winbin")
+  })
+
+  test("skips directory entries (trailing slash)", async () => {
+    const exit = await runExit(extractFromZipBytes(zipWithEntry("oytc/", new Uint8Array(0)), "oytc"))
+    expect(failureMessage(exit)).toContain("does not contain")
+  })
+
+  test("reports a missing entry", async () => {
+    const exit = await runExit(extractFromZipBytes(zipWithEntry("other.exe", bytes("x")), "oytc.exe"))
+    expect(failureMessage(exit)).toContain('release archive does not contain "oytc.exe"')
+  })
+
+  test("garbage input fails as an invalid zip", async () => {
+    const exit = await runExit(extractFromZipBytes(bytes("not a zip at all"), "oytc.exe"))
+    expect(failureMessage(exit)).toContain("open release archive")
+  })
+})
+
+/**
+ * The Go implementation chooses zip when the path ends in `.zip` OR when
+ * goos is windows. Both halves of that disjunction are exercised.
+ */
+describe("extractBinary — format selection", () => {
+  const withTempFile = async (
+    name: string,
+    content: Uint8Array,
+    use: (path: string) => Promise
+  ): Promise => {
+    const dir = `/tmp/oytc-archive-test-${Math.floor(Math.random() * 1e9)}`
+    await Bun.$`mkdir -p ${dir}`.quiet()
+    const file = `${dir}/${name}`
+    await Bun.write(file, content)
+    try {
+      return await use(file)
+    } finally {
+      await Bun.$`rm -rf ${dir}`.quiet()
+    }
+  }
+
+  test("tar.gz on linux", async () => {
+    await withTempFile("a.tar.gz", tarGzWithEntry("oytc", bytes("linux-bin")), async (file) => {
+      const exit = await runFs(extractBinary(file, "linux", "oytc"))
+      if (!Exit.isSuccess(exit)) throw new Error(failureMessage(exit))
+      expect(text(exit.value as Uint8Array)).toBe("linux-bin")
+    })
+  })
+
+  test("zip on windows even when the path does not end in .zip", async () => {
+    await withTempFile("archive.bin", zipWithEntry("oytc.exe", bytes("win-bin")), async (file) => {
+      const exit = await runFs(extractBinary(file, "windows", "oytc.exe"))
+      if (!Exit.isSuccess(exit)) throw new Error(failureMessage(exit))
+      expect(text(exit.value as Uint8Array)).toBe("win-bin")
+    })
+  })
+
+  test("zip when the path ends in .zip even on linux", async () => {
+    await withTempFile("a.zip", zipWithEntry("oytc", bytes("zipped")), async (file) => {
+      const exit = await runFs(extractBinary(file, "linux", "oytc"))
+      if (!Exit.isSuccess(exit)) throw new Error(failureMessage(exit))
+      expect(text(exit.value as Uint8Array)).toBe("zipped")
+    })
+  })
+
+  test("a missing archive file fails as unreadable", async () => {
+    const exit = await runFs(extractBinary("/tmp/definitely-not-here.tar.gz", "linux", "oytc"))
+    expect(failureMessage(exit)).toContain("open release archive")
+  })
+})
diff --git a/src/impl/archive.ts b/src/impl/archive.ts
index ca14f9a..24f8bdf 100644
--- a/src/impl/archive.ts
+++ b/src/impl/archive.ts
@@ -1,2 +1,351 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Release-archive extraction — `tar.gz` and `zip`, with the path-traversal
+ * defense from `internal/update/update.go`.
+ *
+ * The defense is deliberately not a prefix check or a `..` scan. An entry
+ * qualifies only when
+ *
+ *     path.Clean(name.replaceAll("\\", "/")) === 
+ *
+ * i.e. an EXACT match against `oytc` / `oytc.exe`. That single rule rejects
+ * `../oytc`, `/oytc`, `nested/oytc` and `..\oytc` at once, and it also means a
+ * malicious archive cannot smuggle a second file past us: nothing but the one
+ * expected name is ever read, and nothing is ever written to an attacker-named
+ * path — the payload goes to a temp file we name ourselves.
+ *
+ * Neither format is streamed. Both are bounded by the 256 MiB download cap
+ * upstream, so the whole archive is already on disk and fits in memory; a
+ * streaming tar reader would buy nothing and cost the ability to read a zip's
+ * central directory (which lives at the END of the file).
+ */
+
+import { gunzipSync, inflateRawSync } from "node:zlib"
+import { Effect, FileSystem } from "effect"
+import { OperationalError } from "../domain/errors.ts"
+
+/** `256 << 20`. Mirrors Go's `maxArchiveBytes`. */
+export const MAX_ARCHIVE_BYTES = 256 << 20
+
+/**
+ * Go's `path.Clean`. Node's `path.posix.normalize` is close but not equal —
+ * it preserves a trailing slash (`"oytc/"` stays `"oytc/"` where Go yields
+ * `"oytc"`), so it cannot be substituted here.
+ */
+export const goPathClean = (value: string): string => {
+  if (value === "") return "."
+  const rooted = value.startsWith("/")
+  const segments = value.split("/")
+  const out: Array = []
+  for (const segment of segments) {
+    if (segment === "" || segment === ".") continue
+    if (segment === "..") {
+      if (out.length > 0 && out[out.length - 1] !== "..") {
+        out.pop()
+        continue
+      }
+      // A rooted path cannot escape its root: `/../x` cleans to `/x`.
+      if (rooted) continue
+      out.push("..")
+      continue
+    }
+    out.push(segment)
+  }
+  const joined = out.join("/")
+  if (rooted) return `/${joined}`
+  return joined === "" ? "." : joined
+}
+
+/**
+ * The traversal defense. `want` is a bare filename (`oytc` / `oytc.exe`);
+ * anything that does not clean to exactly that is not our binary.
+ */
+export const safeEntryMatch = (name: string, want: string): boolean =>
+  goPathClean(name.replaceAll("\\", "/")) === want
+
+const fail = (message: string, cause?: unknown) =>
+  Effect.fail(new OperationalError({ message, ...(cause === undefined ? {} : { cause }) }))
+
+const notContained = (want: string) => `release archive does not contain "${want}"`
+
+// ---------------------------------------------------------------------------
+// tar
+// ---------------------------------------------------------------------------
+
+const TAR_BLOCK = 512
+
+const decodeAscii = (bytes: Uint8Array): string => {
+  let out = ""
+  for (const byte of bytes) out += String.fromCharCode(byte)
+  return out
+}
+
+/** A NUL-terminated (or space-padded) tar header string field. */
+const headerString = (block: Uint8Array, offset: number, length: number): string => {
+  const slice = block.subarray(offset, offset + length)
+  let end = slice.length
+  for (let i = 0; i < slice.length; i++) {
+    if (slice[i] === 0) {
+      end = i
+      break
+    }
+  }
+  return new TextDecoder().decode(slice.subarray(0, end))
+}
+
+/**
+ * A tar numeric field: octal ASCII, or GNU base-256 when the high bit of the
+ * first byte is set. Returns `undefined` for a field that is neither.
+ */
+const headerNumber = (block: Uint8Array, offset: number, length: number): number | undefined => {
+  const slice = block.subarray(offset, offset + length)
+  const first = slice[0] ?? 0
+  if ((first & 0x80) !== 0) {
+    let value = 0n
+    for (let i = 0; i < slice.length; i++) {
+      const byte = slice[i]!
+      value = (value << 8n) | BigInt(i === 0 ? byte & 0x7f : byte)
+    }
+    const asNumber = Number(value)
+    return Number.isSafeInteger(asNumber) ? asNumber : undefined
+  }
+  const text = decodeAscii(slice).replace(/[\0 ]+$/, "").trim()
+  if (text === "") return 0
+  if (!/^[0-7]+$/.test(text)) return undefined
+  return Number.parseInt(text, 8)
+}
+
+const isZeroBlock = (block: Uint8Array): boolean => block.every((byte) => byte === 0)
+
+interface TarEntry {
+  readonly name: string
+  readonly typeflag: string
+  readonly data: Uint8Array
+}
+
+/**
+ * Walk a tar archive, yielding regular-file entries. Handles the ustar `prefix`
+ * field, GNU `L` long names, and PAX `x` `path=` records — the same set Go's
+ * `archive/tar` transparently resolves, so an archive Go accepted still works.
+ *
+ * `\0` (TypeRegA) is normalized to `0` exactly as Go's reader does; verified
+ * against Go by hand-building a TypeRegA header.
+ */
+function* tarEntries(bytes: Uint8Array): Generator {
+  let offset = 0
+  let pendingLongName: string | undefined
+  let pendingPaxPath: string | undefined
+
+  while (offset + TAR_BLOCK <= bytes.length) {
+    const header = bytes.subarray(offset, offset + TAR_BLOCK)
+    if (isZeroBlock(header)) return
+    offset += TAR_BLOCK
+
+    const size = headerNumber(header, 124, 12)
+    if (size === undefined || size < 0) return
+
+    const dataEnd = offset + size
+    if (dataEnd > bytes.length) return
+    const data = bytes.subarray(offset, dataEnd)
+    offset = dataEnd + ((TAR_BLOCK - (size % TAR_BLOCK)) % TAR_BLOCK)
+
+    const rawTypeflag = String.fromCharCode(header[156] ?? 0)
+    let name = headerString(header, 0, 100)
+    const magic = decodeAscii(header.subarray(257, 263))
+    if (magic.startsWith("ustar")) {
+      const prefix = headerString(header, 345, 155)
+      if (prefix !== "") name = `${prefix}/${name}`
+    }
+
+    if (rawTypeflag === "L") {
+      pendingLongName = new TextDecoder().decode(data).replace(/\0+$/, "")
+      continue
+    }
+    if (rawTypeflag === "K") continue
+    if (rawTypeflag === "x" || rawTypeflag === "X") {
+      pendingPaxPath = paxPath(data)
+      continue
+    }
+    if (rawTypeflag === "g") continue
+
+    const effectiveName = pendingPaxPath ?? pendingLongName ?? name
+    pendingLongName = undefined
+    pendingPaxPath = undefined
+
+    // Go normalizes TypeRegA ("\0"): a trailing slash means a directory,
+    // otherwise a regular file.
+    const typeflag =
+      rawTypeflag === "\0" || rawTypeflag === "" ? (effectiveName.endsWith("/") ? "5" : "0") : rawTypeflag
+
+    yield { name: effectiveName, typeflag, data }
+  }
+}
+
+/** `path=` out of a PAX extended-header record set. */
+const paxPath = (data: Uint8Array): string | undefined => {
+  const text = new TextDecoder().decode(data)
+  let index = 0
+  while (index < text.length) {
+    const space = text.indexOf(" ", index)
+    if (space < 0) return undefined
+    const length = Number.parseInt(text.slice(index, space), 10)
+    if (!Number.isFinite(length) || length <= 0) return undefined
+    const record = text.slice(index, index + length)
+    const equals = record.indexOf("=")
+    if (equals > 0) {
+      const key = record.slice(record.indexOf(" ") + 1, equals)
+      if (key === "path") return record.slice(equals + 1).replace(/\n$/, "")
+    }
+    index += length
+  }
+  return undefined
+}
+
+/**
+ * Extract `want` from gzipped tar bytes. Only `TypeReg` entries whose cleaned
+ * name matches exactly are considered.
+ */
+export const extractFromTarGzBytes = (
+  bytes: Uint8Array,
+  want: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const tar = yield* Effect.try({
+      try: () => new Uint8Array(gunzipSync(bytes, { maxOutputLength: MAX_ARCHIVE_BYTES })),
+      catch: (cause) => new OperationalError({ message: "open release archive", cause })
+    })
+    for (const entry of tarEntries(tar)) {
+      if (entry.typeflag !== "0") continue
+      if (!safeEntryMatch(entry.name, want)) continue
+      return entry.data.slice(0, MAX_ARCHIVE_BYTES)
+    }
+    return yield* fail(notContained(want))
+  })
+
+// ---------------------------------------------------------------------------
+// zip
+// ---------------------------------------------------------------------------
+
+const EOCD_SIGNATURE = 0x06054b50
+const CENTRAL_SIGNATURE = 0x02014b50
+const LOCAL_SIGNATURE = 0x04034b50
+
+interface ZipEntry {
+  readonly name: string
+  readonly method: number
+  readonly compressedSize: number
+  readonly localHeaderOffset: number
+}
+
+const findEocd = (view: DataView): number | undefined => {
+  const minimum = 22
+  if (view.byteLength < minimum) return undefined
+  // The comment may be up to 65535 bytes; scan back from the end.
+  const limit = Math.max(0, view.byteLength - minimum - 0xffff)
+  for (let offset = view.byteLength - minimum; offset >= limit; offset--) {
+    if (view.getUint32(offset, true) === EOCD_SIGNATURE) return offset
+  }
+  return undefined
+}
+
+/**
+ * Read the central directory. Sizes come from there rather than from the local
+ * header, because an archive written with a streaming writer sets general
+ * purpose bit 3 and leaves the local header's sizes as zero.
+ */
+const zipEntries = (bytes: Uint8Array): ReadonlyArray | undefined => {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const eocd = findEocd(view)
+  if (eocd === undefined) return undefined
+
+  const count = view.getUint16(eocd + 10, true)
+  let offset = view.getUint32(eocd + 16, true)
+  const decoder = new TextDecoder()
+  const entries: Array = []
+
+  for (let i = 0; i < count; i++) {
+    if (offset + 46 > bytes.length) return undefined
+    if (view.getUint32(offset, true) !== CENTRAL_SIGNATURE) return undefined
+    const method = view.getUint16(offset + 10, true)
+    const compressedSize = view.getUint32(offset + 20, true)
+    const nameLength = view.getUint16(offset + 28, true)
+    const extraLength = view.getUint16(offset + 30, true)
+    const commentLength = view.getUint16(offset + 32, true)
+    const localHeaderOffset = view.getUint32(offset + 42, true)
+    const name = decoder.decode(bytes.subarray(offset + 46, offset + 46 + nameLength))
+    entries.push({ name, method, compressedSize, localHeaderOffset })
+    offset += 46 + nameLength + extraLength + commentLength
+  }
+  return entries
+}
+
+const zipEntryData = (
+  bytes: Uint8Array,
+  entry: ZipEntry
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+    const start = entry.localHeaderOffset
+    if (start + 30 > bytes.length || view.getUint32(start, true) !== LOCAL_SIGNATURE) {
+      return yield* fail("open release archive: corrupt zip local header")
+    }
+    const nameLength = view.getUint16(start + 26, true)
+    const extraLength = view.getUint16(start + 28, true)
+    const dataStart = start + 30 + nameLength + extraLength
+    const dataEnd = dataStart + entry.compressedSize
+    if (dataEnd > bytes.length) {
+      return yield* fail("read release archive: truncated zip entry")
+    }
+    const raw = bytes.subarray(dataStart, dataEnd)
+
+    if (entry.method === 0) return raw.slice(0, MAX_ARCHIVE_BYTES)
+    if (entry.method === 8) {
+      return yield* Effect.try({
+        try: () => new Uint8Array(inflateRawSync(raw, { maxOutputLength: MAX_ARCHIVE_BYTES })),
+        catch: (cause) => new OperationalError({ message: "read release archive", cause })
+      })
+    }
+    return yield* fail(`read release archive: unsupported zip compression method ${entry.method}`)
+  })
+
+/** Extract `want` from zip bytes. Directory entries (trailing `/`) are skipped. */
+export const extractFromZipBytes = (
+  bytes: Uint8Array,
+  want: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const entries = zipEntries(bytes)
+    if (entries === undefined) {
+      return yield* fail("open release archive: not a valid zip file")
+    }
+    for (const entry of entries) {
+      if (entry.name.endsWith("/")) continue
+      if (!safeEntryMatch(entry.name, want)) continue
+      return yield* zipEntryData(bytes, entry)
+    }
+    return yield* fail(notContained(want))
+  })
+
+/**
+ * Pull the oytc binary out of a verified archive on disk.
+ *
+ * Format selection matches Go: zip when the path ends in `.zip` OR when
+ * `goos === "windows"`, tar.gz otherwise.
+ */
+export const extractBinary = (
+  archivePath: string,
+  goos: string,
+  want: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const bytes = yield* fs
+      .readFile(archivePath)
+      .pipe(
+        Effect.catch((cause) =>
+          Effect.fail(new OperationalError({ message: "open release archive", cause }))
+        )
+      )
+    return yield* archivePath.endsWith(".zip") || goos === "windows"
+      ? extractFromZipBytes(bytes, want)
+      : extractFromTarGzBytes(bytes, want)
+  })
diff --git a/src/impl/atomicWrite.test.ts b/src/impl/atomicWrite.test.ts
new file mode 100644
index 0000000..825d574
--- /dev/null
+++ b/src/impl/atomicWrite.test.ts
@@ -0,0 +1,150 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { Cause, Effect, Exit, FileSystem, Layer, Path } from "effect"
+import { BunServices } from "@effect/platform-bun"
+import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { chmodSync, mkdirSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { atomicWriteSecure, ensureSecureDirectory } from "./atomicWrite.ts"
+
+const temporaries: Array = []
+
+const tempDir = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "oytc-atomic-"))
+  temporaries.push(dir)
+  return dir
+}
+
+afterEach(() => {
+  while (temporaries.length > 0) {
+    const dir = temporaries.pop()!
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+const platform: Layer.Layer = Layer.mergeAll(
+  BunServices.layer
+) as unknown as Layer.Layer
+
+const run = (effect: Effect.Effect): Promise =>
+  Effect.runPromise(effect.pipe(Effect.provide(platform)))
+
+const runExit = (effect: Effect.Effect) =>
+  Effect.runPromise(Effect.exit(effect.pipe(Effect.provide(platform))))
+
+const withServices = (
+  f: (fs: FileSystem.FileSystem, path: Path.Path) => Effect.Effect
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+    return yield* f(fs, path)
+  })
+
+const mode = (target: string): number => statSync(target).mode & 0o777
+
+describe("atomicWriteSecure", () => {
+  test("creates missing directories at 0700 and the file at 0600", async () => {
+    const root = tempDir()
+    const destination = join(root, "nested", "deeper", "auth.json")
+
+    const result = await run(
+      withServices((fs, path) => atomicWriteSecure(fs, path, destination, "payload\n"))
+    )
+
+    expect(result).toBe(destination)
+    expect(readFileSync(destination, "utf8")).toBe("payload\n")
+    expect(mode(destination)).toBe(0o600)
+    expect(mode(join(root, "nested", "deeper"))).toBe(0o700)
+  })
+
+  test("re-tightens a pre-existing loose directory to 0700", async () => {
+    const root = tempDir()
+    const dir = join(root, "loose")
+    mkdirSync(dir, { mode: 0o777 })
+    chmodSync(dir, 0o777)
+    expect(mode(dir)).toBe(0o777)
+
+    await run(
+      withServices((fs, path) => atomicWriteSecure(fs, path, join(dir, "auth.json"), "x\n"))
+    )
+    expect(mode(dir)).toBe(0o700)
+  })
+
+  test("replaces an existing file and re-tightens its mode", async () => {
+    const root = tempDir()
+    const destination = join(root, "auth.json")
+    writeFileSync(destination, "stale", { mode: 0o644 })
+    chmodSync(destination, 0o644)
+
+    await run(withServices((fs, path) => atomicWriteSecure(fs, path, destination, "fresh\n")))
+
+    expect(readFileSync(destination, "utf8")).toBe("fresh\n")
+    expect(mode(destination)).toBe(0o600)
+  })
+
+  test("leaves no .auth-*.tmp behind on success", async () => {
+    const root = tempDir()
+    await run(
+      withServices((fs, path) => atomicWriteSecure(fs, path, join(root, "auth.json"), "x\n"))
+    )
+    expect(readdirSync(root).filter((name) => name.endsWith(".tmp"))).toEqual([])
+  })
+
+  test("leaves no temp file behind when the write fails", async () => {
+    const root = tempDir()
+    // A directory where the destination should be makes the rename fail while
+    // the temp file has already been created — Go's `defer os.Remove` path.
+    const destination = join(root, "auth.json")
+    mkdirSync(destination)
+    // Put something inside so the rename cannot succeed by replacing an
+    // empty directory (which some platforms allow).
+    writeFileSync(join(destination, "occupant"), "x")
+
+    const exit = await runExit(
+      withServices((fs, path) => atomicWriteSecure(fs, path, destination, "x\n"))
+    )
+    expect(Exit.isFailure(exit)).toBe(true)
+    expect(readdirSync(root).filter((name) => name.endsWith(".tmp"))).toEqual([])
+  })
+
+  test("writes the payload verbatim, including a trailing newline and unicode", async () => {
+    const root = tempDir()
+    const destination = join(root, "auth.json")
+    const payload = '{\n  "api_key": "é✓"\n}\n'
+    await run(withServices((fs, path) => atomicWriteSecure(fs, path, destination, payload)))
+    expect(readFileSync(destination, "utf8")).toBe(payload)
+  })
+
+  test("truncates rather than appending when replacing a longer file", async () => {
+    const root = tempDir()
+    const destination = join(root, "auth.json")
+    writeFileSync(destination, "x".repeat(4096))
+    await run(withServices((fs, path) => atomicWriteSecure(fs, path, destination, "tiny\n")))
+    expect(readFileSync(destination, "utf8")).toBe("tiny\n")
+  })
+})
+
+describe("ensureSecureDirectory", () => {
+  test("is idempotent and always ends at 0700", async () => {
+    const root = tempDir()
+    const dir = join(root, "a", "b")
+    await run(withServices((fs) => ensureSecureDirectory(fs, dir)))
+    expect(mode(dir)).toBe(0o700)
+    chmodSync(dir, 0o755)
+    await run(withServices((fs) => ensureSecureDirectory(fs, dir)))
+    expect(mode(dir)).toBe(0o700)
+  })
+
+  test("fails with Go's message when the path is occupied by a file", async () => {
+    const root = tempDir()
+    const blocked = join(root, "blocker")
+    writeFileSync(blocked, "x")
+
+    const exit = await runExit(withServices((fs) => ensureSecureDirectory(fs, blocked)))
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) {
+      expect(Cause.pretty(exit.cause)).toContain("create config directory")
+    }
+  })
+})
diff --git a/src/impl/atomicWrite.ts b/src/impl/atomicWrite.ts
index ca14f9a..f258260 100644
--- a/src/impl/atomicWrite.ts
+++ b/src/impl/atomicWrite.ts
@@ -1,2 +1,117 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Atomic, permission-hardened file replacement — Go's `config.saveFile`.
+ *
+ * The sequence matters and is reproduced step for step:
+ *
+ *   1. `mkdir -p` the parent with mode 0700.
+ *   2. `chmod 0700` the parent — **best effort**. This re-tightens a directory
+ *      that already existed with loose permissions; `mkdir` would not.
+ *   3. Create a temp file `.auth-.tmp` in the SAME directory, so the
+ *      rename in step 6 stays on one filesystem and is therefore atomic.
+ *   4. `chmod 0600` the temp file, then write, then **fsync**. The fsync is
+ *      what makes the rename meaningful: without it a crash can leave the
+ *      renamed file present but empty.
+ *   5. Rename over the destination.
+ *   6. `chmod 0600` the destination — best effort.
+ *
+ * Every failure path removes the temp file, matching Go's
+ * `defer os.Remove(tmpName)` (a harmless no-op after a successful rename).
+ *
+ * **Best effort means best effort.** On Windows `chmod` only toggles the
+ * read-only attribute, and Go ignores both hardening chmod errors outright. A
+ * `chmod` failure here must never fail the write.
+ */
+
+import { Effect, FileSystem, Path } from "effect"
+import { OperationalError } from "../domain/errors.ts"
+
+/** Go's `os.CreateTemp(dir, ".auth-*.tmp")` naming: a random decimal infix. */
+const tempName = (): string => `.auth-${Math.floor(Math.random() * 0xffffffff)}.tmp`
+
+const wrap = (message: string) => (cause: unknown) => new OperationalError({ message, cause })
+
+/** Ignore every failure, including defects — used for the hardening chmods. */
+const bestEffort = (effect: Effect.Effect): Effect.Effect =>
+  effect.pipe(
+    Effect.asVoid,
+    Effect.catchCause(() => Effect.void)
+  )
+
+/**
+ * `mkdir -p dir` at 0700, then re-tighten an existing directory to 0700.
+ * Exposed separately because `Remove()` needs the directory to exist for the
+ * lockfile without writing anything.
+ *
+ * `fs`/`path` are passed rather than pulled from context so callers that
+ * already resolved them do not re-introduce a `FileSystem` requirement into
+ * the closures they hand back from a service constructor.
+ */
+export const ensureSecureDirectory = (
+  fs: FileSystem.FileSystem,
+  directory: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    yield* fs
+      .makeDirectory(directory, { recursive: true, mode: 0o700 })
+      .pipe(Effect.catch((cause) => Effect.fail(wrap("create config directory")(cause))))
+    yield* bestEffort(fs.chmod(directory, 0o700))
+  })
+
+/**
+ * Write `contents` to `destination` atomically, with 0600 on the file and 0700
+ * on its directory. Returns `destination`.
+ */
+export const atomicWriteSecure = (
+  fs: FileSystem.FileSystem,
+  path: Path.Path,
+  destination: string,
+  contents: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const directory = path.dirname(destination)
+
+    yield* ensureSecureDirectory(fs, directory)
+
+    const temporary = path.join(directory, tempName())
+
+    // `wx` fails if the random name collided, which is the correct outcome:
+    // creating the temp file must never clobber an existing file.
+    yield* fs
+      .writeFileString(temporary, "", { flag: "wx", mode: 0o600 })
+      .pipe(Effect.catch((cause) => Effect.fail(wrap("create temporary credential file")(cause))))
+
+    const install = Effect.gen(function* () {
+      // Go's belt-and-braces tmp.Chmod(0600) after CreateTemp already made it
+      // 0600. Unlike the hardening chmods this one IS fatal in Go.
+      yield* fs
+        .chmod(temporary, 0o600)
+        .pipe(Effect.catch((cause) => Effect.fail(wrap("secure temporary credential file")(cause))))
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const handle = yield* fs
+            .open(temporary, { flag: "w", mode: 0o600 })
+            .pipe(Effect.catch((cause) => Effect.fail(wrap("write credentials")(cause))))
+          yield* handle
+            .writeAll(new TextEncoder().encode(contents))
+            .pipe(Effect.catch((cause) => Effect.fail(wrap("write credentials")(cause))))
+          // fsync BEFORE the rename, or a crash can publish an empty file.
+          yield* handle.sync.pipe(
+            Effect.catch((cause) => Effect.fail(wrap("sync credentials")(cause)))
+          )
+        })
+      )
+
+      yield* fs
+        .rename(temporary, destination)
+        .pipe(Effect.catch((cause) => Effect.fail(wrap("install credentials")(cause))))
+
+      yield* bestEffort(fs.chmod(destination, 0o600))
+      return destination
+    })
+
+    // Go's `defer os.Remove(tmpName)`: a no-op once the rename succeeded.
+    return yield* install.pipe(
+      Effect.onExit(() => bestEffort(fs.remove(temporary, { force: true })))
+    )
+  })
diff --git a/src/impl/browserOpener.test.ts b/src/impl/browserOpener.test.ts
new file mode 100644
index 0000000..207dec3
--- /dev/null
+++ b/src/impl/browserOpener.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, test } from "bun:test"
+import { Effect, Layer, Option } from "effect"
+// `effect/testing` is a stable subpath, so the src/effect.ts barrel rule does not
+// apply to it (that rule covers the unstable subpath only).
+import { TestConsole } from "effect/testing"
+import { ProcessEnv, type ProcessEnvShape } from "../services/index.ts"
+import { OperationalError } from "../domain/errors.ts"
+import { browserCommand, launch, makeBrowserOpener } from "./browserOpener.ts"
+
+const URL_UNDER_TEST = "https://accounts.google.com/o/oauth2/v2/auth?client_id=x&state=y"
+
+describe("browserCommand", () => {
+  test("darwin uses open", () => {
+    expect(browserCommand("darwin", URL_UNDER_TEST)).toEqual({
+      command: "open",
+      args: [URL_UNDER_TEST]
+    })
+  })
+
+  test("windows uses rundll32 with the FileProtocolHandler entry point", () => {
+    expect(browserCommand("win32", URL_UNDER_TEST)).toEqual({
+      command: "rundll32",
+      args: ["url.dll,FileProtocolHandler", URL_UNDER_TEST]
+    })
+  })
+
+  test.each([["linux"], ["freebsd"], ["openbsd"], ["anything-else"]])(
+    "%s falls back to xdg-open",
+    (platform) => {
+      expect(browserCommand(platform, URL_UNDER_TEST)).toEqual({
+        command: "xdg-open",
+        args: [URL_UNDER_TEST]
+      })
+    }
+  )
+
+  test("the URL is passed as a single argv element, never shell-interpolated", () => {
+    const hostile = "https://example.com/?a=1&b=$(whoami);rm -rf /"
+    expect(browserCommand("linux", hostile).args).toEqual([hostile])
+  })
+})
+
+const envLayer = (platform: string): Layer.Layer => {
+  const shape: ProcessEnvShape = {
+    env: () => Option.none(),
+    platform,
+    arch: "arm64",
+    argv: [],
+    executablePath: Effect.succeed("/bin/oytc"),
+    isOutputTTY: false,
+    homeDir: Effect.succeed("/home/test")
+  }
+  return Layer.succeed(ProcessEnv, shape)
+}
+
+const opener = (platform: string) =>
+  Effect.provide(makeBrowserOpener, envLayer(platform))
+
+describe("BrowserOpener", () => {
+  test("a launch failure is a warning on stderr, not an error", async () => {
+    // The launcher must be guaranteed ABSENT for this to test anything. Relying
+    // on `xdg-open` being missing only holds on macOS — the Linux CI runner has
+    // it — so PATH is emptied for the duration, which makes spawn emit ENOENT on
+    // every platform. `open` must still succeed so Login keeps waiting on the
+    // loopback callback, and the warning must carry Go's exact prefix.
+    const path = process.env["PATH"]
+    process.env["PATH"] = ""
+    try {
+      const lines = await Effect.runPromise(
+        Effect.gen(function* () {
+          const browser = yield* opener("definitely-not-a-real-platform")
+          yield* browser.open(URL_UNDER_TEST)
+          return yield* TestConsole.errorLines
+        }).pipe(Effect.provide(TestConsole.layer))
+      )
+      expect(lines).toHaveLength(1)
+      expect(String(lines[0])).toStartWith("Could not open a browser automatically: ")
+    } finally {
+      process.env["PATH"] = path
+    }
+  })
+
+  test("launch resolves once the child has spawned, without waiting for it", async () => {
+    // `sleep 5` proves the effect returns on the `spawn` event rather than on
+    // exit — Go uses Start(), not Wait(), so the login must not block here.
+    const started = Date.now()
+    await Effect.runPromise(launch({ command: "sleep", args: ["5"] }))
+    expect(Date.now() - started).toBeLessThan(2000)
+  })
+
+  test("launch fails when the launcher is not on PATH", async () => {
+    const error = await Effect.runPromise(
+      Effect.flip(launch({ command: "oytc-no-such-launcher", args: ["about:blank"] }))
+    )
+    expect(error).toBeInstanceOf(Error)
+    // Node reports a missing binary asynchronously on the `error` event; assert
+    // the code so this cannot pass on some unrelated failure.
+    expect((error as NodeJS.ErrnoException).code).toBe("ENOENT")
+  })
+
+  test("the shape's error channel is `never`, as the contract requires", () => {
+    // A compile-time assertion: assigning to Effect only
+    // typechecks because `open` cannot fail.
+    const check = Effect.gen(function* () {
+      const browser = yield* opener("linux")
+      const opened: Effect.Effect = browser.open("about:blank")
+      return opened
+    })
+    expect(check).toBeDefined()
+  })
+
+  test("OperationalError is not part of this path", () => {
+    // Guards against a future refactor promoting the warning to a failure.
+    expect(new OperationalError({ message: "x" })).toBeInstanceOf(OperationalError)
+  })
+})
diff --git a/src/impl/browserOpener.ts b/src/impl/browserOpener.ts
index ca14f9a..5b79273 100644
--- a/src/impl/browserOpener.ts
+++ b/src/impl/browserOpener.ts
@@ -1,2 +1,72 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Detached browser launch for the OAuth consent screen.
+ *
+ * Go's `oauth.OpenBrowser` calls `exec.Command(...).Start()` — it never waits
+ * for the browser to exit, and a failure to launch is non-fatal: `Login` prints
+ * `Could not open a browser automatically: ` and keeps waiting on the
+ * loopback callback, because the URL has already been printed for the user to
+ * paste. `BrowserOpenerShape.open` therefore cannot fail; the warning is emitted
+ * here, on stderr, where Go emits it.
+ *
+ * `node:child_process` rather than `Bun.spawn`: the sanctioned Bun-specific
+ * import outside `main.ts` is the loopback server only, and `spawn` is
+ * identical across both runtimes.
+ *
+ * Go's `Start()` reports a launch failure synchronously; Node's `spawn` reports
+ * it asynchronously on the `error` event, so the effect waits for whichever of
+ * `spawn`/`error` fires first before returning.
+ */
+
+import { spawn } from "node:child_process"
+import { Console, Effect, Layer } from "effect"
+import { BrowserOpener, type BrowserOpenerShape, ProcessEnv } from "../services/index.ts"
+
+export interface BrowserCommand {
+  readonly command: string
+  readonly args: ReadonlyArray
+}
+
+/** darwin `open`; windows `rundll32 url.dll,FileProtocolHandler`; otherwise `xdg-open`. */
+export const browserCommand = (platform: string, url: string): BrowserCommand => {
+  switch (platform) {
+    case "darwin":
+      return { command: "open", args: [url] }
+    case "win32":
+      return { command: "rundll32", args: ["url.dll,FileProtocolHandler", url] }
+    default:
+      return { command: "xdg-open", args: [url] }
+  }
+}
+
+/** Exported so tests can drive it with a harmless binary instead of a browser. */
+export const launch = ({ command, args }: BrowserCommand): Effect.Effect =>
+  Effect.tryPromise({
+    try: () =>
+      new Promise((resolve, reject) => {
+        const child = spawn(command, [...args], {
+          detached: true,
+          stdio: "ignore"
+        })
+        child.once("error", reject)
+        child.once("spawn", () => {
+          child.unref()
+          resolve()
+        })
+      }),
+    catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause)))
+  })
+
+export const makeBrowserOpener = Effect.gen(function* () {
+  const env = yield* ProcessEnv
+  const shape: BrowserOpenerShape = {
+    open: (url) =>
+      launch(browserCommand(env.platform, url)).pipe(
+        Effect.catch((cause) =>
+          Console.error(`Could not open a browser automatically: ${cause.message}`)
+        )
+      )
+  }
+  return shape
+})
+
+export const BrowserOpenerLive = Layer.effect(BrowserOpener, makeBrowserOpener)
diff --git a/src/impl/credentialStore.test.ts b/src/impl/credentialStore.test.ts
new file mode 100644
index 0000000..5963cc6
--- /dev/null
+++ b/src/impl/credentialStore.test.ts
@@ -0,0 +1,858 @@
+/**
+ * Ports all 8 cases from `internal/config/config_test.go`, plus the
+ * cross-process shape of `TestConcurrentUpdatesAreNotLost` that the Go suite
+ * cannot express (goroutines share one flock file description; two OS
+ * processes do not).
+ *
+ * Every test gets its own temp dir via `OYTC_CONFIG_DIR`. The real config
+ * directory is never read or written.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test"
+import { Cause, Effect, Exit, FileSystem, Layer, Option, Path } from "effect"
+import { BunServices } from "@effect/platform-bun"
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { OperationalError } from "../domain/errors.ts"
+import {
+  CredentialStore,
+  ProcessEnv,
+  type CredentialStoreShape,
+  type ProcessEnvShape,
+  type StoredOAuth
+} from "../services/index.ts"
+import { CredentialStoreLive, fingerprint } from "./credentialStore.ts"
+import { FileLockLive } from "./fileLock.ts"
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+const temporaries: Array = []
+
+const tempDir = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "oytc-cred-"))
+  temporaries.push(dir)
+  return dir
+}
+
+afterEach(() => {
+  while (temporaries.length > 0) {
+    rmSync(temporaries.pop()!, { recursive: true, force: true })
+  }
+})
+
+const platform = BunServices.layer as unknown as Layer.Layer<
+  FileSystem.FileSystem | Path.Path
+>
+
+interface EnvOverrides {
+  readonly [name: string]: string | undefined
+}
+
+/**
+ * A ProcessEnv whose variables and platform are fully controlled, so
+ * `Dir()` resolution can be tested for darwin/windows/linux from one host.
+ */
+const testProcessEnv = (options: {
+  readonly env?: EnvOverrides
+  readonly platform?: string
+  readonly home?: string | undefined
+}): ProcessEnvShape => {
+  const env = options.env ?? {}
+  return {
+    env: (name) => Option.fromNullishOr(env[name]),
+    platform: options.platform ?? process.platform,
+    arch: process.arch,
+    argv: [],
+    executablePath: Effect.succeed("/nonexistent/oytc"),
+    isOutputTTY: false,
+    homeDir:
+      options.home === undefined
+        ? Effect.fail(new OperationalError({ message: "could not determine home directory" }))
+        : Effect.succeed(options.home)
+  }
+}
+
+/** One fresh store (and therefore one fresh lock semaphore) per invocation. */
+const storeLayer = (options: {
+  readonly env?: EnvOverrides
+  readonly platform?: string
+  readonly home?: string | undefined
+}): Layer.Layer<(typeof CredentialStore)["Identifier"]> => {
+  const processEnv = Layer.succeed(ProcessEnv, testProcessEnv(options))
+  return Layer.fresh(
+    CredentialStoreLive.pipe(
+      Layer.provide(Layer.mergeAll(platform, processEnv, FileLockLive.pipe(Layer.provide(platform))))
+    )
+  ) as unknown as Layer.Layer<(typeof CredentialStore)["Identifier"]>
+}
+
+const runIn = (
+  layer: Layer.Layer<(typeof CredentialStore)["Identifier"]>,
+  f: (store: CredentialStoreShape) => Effect.Effect
+): Promise =>
+  Effect.runPromise(
+    Effect.flatMap(CredentialStore, f).pipe(Effect.provide(layer)) as Effect.Effect
+  )
+
+const exitIn = (
+  layer: Layer.Layer<(typeof CredentialStore)["Identifier"]>,
+  f: (store: CredentialStoreShape) => Effect.Effect
+): Promise> =>
+  Effect.runPromise(
+    Effect.exit(
+      Effect.flatMap(CredentialStore, f).pipe(Effect.provide(layer)) as Effect.Effect
+    )
+  )
+
+/** A store bound to `dir` with no OYTC_API_KEY, the common case. */
+const storeAt = (dir: string, extra: EnvOverrides = {}) =>
+  storeLayer({ env: { OYTC_CONFIG_DIR: dir, ...extra } })
+
+const perm = (target: string): number => statSync(target).mode & 0o777
+
+const oauth = (overrides: Partial = {}): StoredOAuth => ({
+  clientId: "id",
+  clientSecret: "secret",
+  accessToken: "access",
+  refreshToken: "refresh",
+  expiry: "2026-02-01T12:00:00Z",
+  scopes: ["scope"],
+  ...overrides
+})
+
+const failureMessage = (exit: Exit.Exit): string =>
+  Exit.isFailure(exit) ? Cause.pretty(exit.cause) : ""
+
+// ---------------------------------------------------------------------------
+// Dir() resolution — §1.1 / §1.2
+// ---------------------------------------------------------------------------
+
+describe("dir", () => {
+  test("OYTC_CONFIG_DIR is used verbatim, with NO oytc suffix appended", async () => {
+    const dir = await runIn(
+      storeLayer({ env: { OYTC_CONFIG_DIR: "/custom/place" }, platform: "linux" }),
+      (store) => store.dir
+    )
+    expect(dir).toBe("/custom/place")
+  })
+
+  test("OYTC_CONFIG_DIR is trimmed before the emptiness test", async () => {
+    const dir = await runIn(
+      storeLayer({ env: { OYTC_CONFIG_DIR: "  /custom/place  " }, platform: "linux" }),
+      (store) => store.dir
+    )
+    expect(dir).toBe("/custom/place")
+  })
+
+  test("a whitespace-only OYTC_CONFIG_DIR falls through to the OS default", async () => {
+    const dir = await runIn(
+      storeLayer({ env: { OYTC_CONFIG_DIR: "   " }, platform: "linux", home: "/home/u" }),
+      (store) => store.dir
+    )
+    expect(dir).toBe("/home/u/.config/oytc")
+  })
+
+  test.each([
+    ["~", "/home/u"],
+    ["~/cfg", "/home/u/cfg"],
+    ["~\\cfg", "/home/u/cfg"],
+    // ~user is NOT supported: it starts with neither "~/" nor "~\".
+    ["~other/cfg", "~other/cfg"],
+    ["/abs/path", "/abs/path"],
+    ["relative", "relative"]
+  ])("tilde expansion of %s -> %s", async (input, expected) => {
+    const dir = await runIn(
+      storeLayer({ env: { OYTC_CONFIG_DIR: input }, platform: "linux", home: "/home/u" }),
+      (store) => store.dir
+    )
+    expect(dir).toBe(expected)
+  })
+
+  test("an unresolvable home leaves a tilde path unchanged", async () => {
+    const dir = await runIn(
+      storeLayer({ env: { OYTC_CONFIG_DIR: "~/cfg" }, platform: "linux", home: undefined }),
+      (store) => store.dir
+    )
+    expect(dir).toBe("~/cfg")
+  })
+
+  test("darwin resolves to ~/Library/Application Support/oytc", async () => {
+    const dir = await runIn(storeLayer({ platform: "darwin", home: "/Users/u" }), (s) => s.dir)
+    expect(dir).toBe("/Users/u/Library/Application Support/oytc")
+  })
+
+  test("darwin propagates an unresolvable home", async () => {
+    const exit = await exitIn(storeLayer({ platform: "darwin", home: undefined }), (s) => s.dir)
+    expect(failureMessage(exit)).toContain("determine config directory")
+  })
+
+  test("windows resolves to %APPDATA%\\oytc", async () => {
+    const dir = await runIn(
+      storeLayer({ platform: "win32", env: { APPDATA: "C:\\Users\\u\\AppData\\Roaming" } }),
+      (s) => s.dir
+    )
+    // path.join is host-flavored; assert on the components, not the separator.
+    expect(dir.replaceAll("\\", "/")).toBe("C:/Users/u/AppData/Roaming/oytc")
+  })
+
+  test("windows without APPDATA is an error", async () => {
+    const exit = await exitIn(storeLayer({ platform: "win32", env: {} }), (s) => s.dir)
+    expect(failureMessage(exit)).toContain("determine config directory: APPDATA is not set")
+  })
+
+  test("linux prefers XDG_CONFIG_HOME", async () => {
+    const dir = await runIn(
+      storeLayer({ platform: "linux", env: { XDG_CONFIG_HOME: "/xdg" }, home: "/home/u" }),
+      (s) => s.dir
+    )
+    expect(dir).toBe("/xdg/oytc")
+  })
+
+  test("XDG_CONFIG_HOME is NOT trimmed — whitespace is a real value", async () => {
+    // Deliberate asymmetry with OYTC_CONFIG_DIR, matching Go: only an
+    // exactly-empty XDG_CONFIG_HOME counts as unset.
+    const dir = await runIn(
+      storeLayer({ platform: "linux", env: { XDG_CONFIG_HOME: "  " }, home: "/home/u" }),
+      (s) => s.dir
+    )
+    expect(dir).toBe("  /oytc")
+  })
+
+  test("linux falls back to ~/.config/oytc", async () => {
+    const dir = await runIn(storeLayer({ platform: "linux", home: "/home/u" }), (s) => s.dir)
+    expect(dir).toBe("/home/u/.config/oytc")
+  })
+
+  test("path is dir + auth.json", async () => {
+    const layer = storeLayer({ env: { OYTC_CONFIG_DIR: "/custom" }, platform: "linux" })
+    expect(await runIn(layer, (s) => s.path)).toBe("/custom/auth.json")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestSaveLoadRemoveAndModes
+// ---------------------------------------------------------------------------
+
+describe("TestSaveLoadRemoveAndModes", () => {
+  test("save, load, replace, remove, and file modes", async () => {
+    const root = tempDir()
+    const configDir = join(root, "nested")
+    const layer = storeAt(configDir)
+
+    const path = await runIn(layer, (store) => store.save("test-secret-key"))
+    expect(path).toBe(join(configDir, "auth.json"))
+
+    expect(readFileSync(path, "utf8")).toBe('{\n  "api_key": "test-secret-key"\n}\n')
+    expect(perm(path)).toBe(0o600)
+    expect(perm(configDir)).toBe(0o700)
+
+    const credentials = await runIn(layer, (store) => store.load)
+    expect(credentials.key).toBe("test-secret-key")
+    expect(credentials.source).toBe("auth.json")
+    expect(credentials.oauth).toBeUndefined()
+    expect(credentials.path).toBe(path)
+
+    await runIn(layer, (store) => store.save("replacement-secret"))
+    expect((await runIn(layer, (store) => store.load)).key).toBe("replacement-secret")
+
+    const removed = await runIn(layer, (store) => store.remove)
+    expect(removed).toEqual({ path, removed: true })
+    expect(existsSync(path)).toBe(false)
+
+    // Remove is idempotent: a missing file is (path, false, nil).
+    expect(await runIn(layer, (store) => store.remove)).toEqual({ path, removed: false })
+  })
+
+  test("save trims the key and rejects an empty one", async () => {
+    const layer = storeAt(tempDir())
+    const path = await runIn(layer, (store) => store.save("  padded-key  "))
+    expect(readFileSync(path, "utf8")).toContain('"api_key": "padded-key"')
+
+    for (const empty of ["", "   ", "\t\n"]) {
+      const exit = await exitIn(layer, (store) => store.save(empty))
+      expect(failureMessage(exit)).toContain("API key cannot be empty")
+    }
+  })
+
+  test("loading a nonexistent file yields empty credentials, not an error", async () => {
+    const dir = tempDir()
+    const credentials = await runIn(storeAt(dir), (store) => store.load)
+    expect(credentials).toEqual({
+      key: "",
+      source: "",
+      oauth: undefined,
+      path: join(dir, "auth.json")
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestAPIKeyAndOAuthCoexistAndUpdateIndependently
+// ---------------------------------------------------------------------------
+
+describe("TestAPIKeyAndOAuthCoexistAndUpdateIndependently", () => {
+  test("api_key and oauth update without clobbering each other", async () => {
+    const layer = storeAt(tempDir())
+
+    await runIn(layer, (store) => store.save("api-secret"))
+    await runIn(layer, (store) =>
+      store.saveOAuth(
+        oauth({
+          clientId: "desktop-id",
+          clientSecret: "client-secret",
+          accessToken: "access-secret",
+          refreshToken: "refresh-secret",
+          scopes: ["scope.one", "scope.two"]
+        })
+      )
+    )
+
+    let credentials = await runIn(layer, (store) => store.load)
+    expect(credentials.key).toBe("api-secret")
+    expect(credentials.oauth?.clientId).toBe("desktop-id")
+    expect(credentials.oauth?.refreshToken).toBe("refresh-secret")
+    expect(credentials.oauth?.scopes).toEqual(["scope.one", "scope.two"])
+
+    await runIn(layer, (store) => store.save("replacement-key"))
+    credentials = await runIn(layer, (store) => store.load)
+    expect(credentials.oauth?.accessToken).toBe("access-secret")
+
+    await runIn(layer, (store) => store.clearOAuth)
+    credentials = await runIn(layer, (store) => store.load)
+    expect(credentials.key).toBe("replacement-key")
+    expect(credentials.oauth).toBeUndefined()
+    // A cleared oauth block is OMITTED, not written as null.
+    expect(readFileSync(credentials.path, "utf8")).toBe('{\n  "api_key": "replacement-key"\n}\n')
+  })
+
+  test("clearOAuth on a file with no oauth is a no-op that still succeeds", async () => {
+    const layer = storeAt(tempDir())
+    await runIn(layer, (store) => store.save("k"))
+    await runIn(layer, (store) => store.clearOAuth)
+    expect((await runIn(layer, (store) => store.load)).key).toBe("k")
+  })
+
+  test("normalizeOAuth trims the five strings and enforces both rules", async () => {
+    const layer = storeAt(tempDir())
+
+    const path = await runIn(layer, (store) =>
+      store.saveOAuth(
+        oauth({
+          clientId: "  id  ",
+          clientSecret: "  secret  ",
+          accessToken: "  access  ",
+          refreshToken: "  refresh  ",
+          expiry: "  2026-02-01T12:00:00Z  "
+        })
+      )
+    )
+    const text = readFileSync(path, "utf8")
+    expect(text).toContain('"client_id": "id"')
+    expect(text).toContain('"expiry": "2026-02-01T12:00:00Z"')
+
+    const missingClient = await exitIn(layer, (store) =>
+      store.saveOAuth(oauth({ clientId: "  " }))
+    )
+    expect(failureMessage(missingClient)).toContain(
+      "OAuth client ID and client secret cannot be empty"
+    )
+
+    const missingSecret = await exitIn(layer, (store) =>
+      store.saveOAuth(oauth({ clientSecret: "" }))
+    )
+    expect(failureMessage(missingSecret)).toContain(
+      "OAuth client ID and client secret cannot be empty"
+    )
+
+    const missingTokens = await exitIn(layer, (store) =>
+      store.saveOAuth(oauth({ accessToken: " ", refreshToken: "" }))
+    )
+    expect(failureMessage(missingTokens)).toContain(
+      "OAuth access token or refresh token is required"
+    )
+
+    // Either token alone is sufficient.
+    await runIn(layer, (store) => store.saveOAuth(oauth({ accessToken: "", refreshToken: "r" })))
+    await runIn(layer, (store) => store.saveOAuth(oauth({ accessToken: "a", refreshToken: "" })))
+  })
+
+  test("scopes are not validated or normalized", async () => {
+    const layer = storeAt(tempDir())
+    const path = await runIn(layer, (store) =>
+      store.saveOAuth(oauth({ scopes: ["  padded  ", ""] }))
+    )
+    expect(readFileSync(path, "utf8")).toContain('"  padded  "')
+  })
+
+  test("an empty scopes array serializes as null, matching Go's cloneOAuth", async () => {
+    // Go's `append([]string(nil), empty...)` returns nil, so an empty slice
+    // and a nil slice are indistinguishable once stored.
+    const layer = storeAt(tempDir())
+    const path = await runIn(layer, (store) => store.saveOAuth(oauth({ scopes: [] })))
+    expect(readFileSync(path, "utf8")).toContain('"scopes": null')
+    expect((await runIn(layer, (store) => store.load)).oauth?.scopes).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestOAuthBootstrapEnvironmentPrecedence
+// ---------------------------------------------------------------------------
+
+describe("TestOAuthBootstrapEnvironmentPrecedence", () => {
+  test("returns the trimmed bootstrap variables", async () => {
+    const pair = await runIn(
+      storeAt(tempDir(), {
+        OYTC_OAUTH_CLIENT_ID: "  environment-id  ",
+        OYTC_OAUTH_CLIENT_SECRET: "  environment-secret  "
+      }),
+      (store) => store.oauthBootstrap
+    )
+    expect(pair).toEqual(["environment-id", "environment-secret"])
+  })
+
+  test("unset variables come back as empty strings", async () => {
+    expect(await runIn(storeAt(tempDir()), (store) => store.oauthBootstrap)).toEqual(["", ""])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestConcurrentUpdatesAreNotLost — shape (a), concurrent fibers
+// ---------------------------------------------------------------------------
+
+describe("TestConcurrentUpdatesAreNotLost (in-process fibers)", () => {
+  test("a concurrent api-key save and oauth save both survive", async () => {
+    const dir = tempDir()
+    const layer = storeAt(dir)
+
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const store = yield* CredentialStore
+        yield* Effect.all([store.save("api-secret"), store.saveOAuth(oauth())], {
+          concurrency: "unbounded"
+        })
+      }).pipe(Effect.provide(layer)) as Effect.Effect
+    )
+
+    const credentials = await runIn(layer, (store) => store.load)
+    expect(credentials.key).toBe("api-secret")
+    expect(credentials.oauth?.refreshToken).toBe("refresh")
+  })
+
+  test("many concurrent writers all land — none is silently dropped", async () => {
+    // Without the read-modify-write lock, the last rename wins and every
+    // earlier writer's field vanishes.
+    const layer = storeAt(tempDir())
+    const writers = 12
+
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const store = yield* CredentialStore
+        yield* Effect.all(
+          Array.from({ length: writers }, (_unused, i) =>
+            i % 2 === 0
+              ? Effect.asVoid(store.save(`key-${i}`))
+              : Effect.asVoid(store.saveOAuth(oauth({ accessToken: `access-${i}` })))
+          ),
+          { concurrency: "unbounded" }
+        )
+      }).pipe(Effect.provide(layer)) as Effect.Effect
+    )
+
+    const credentials = await runIn(layer, (store) => store.load)
+    // Which writer won each field is a race, but BOTH fields must be present:
+    // that is what "no update was lost" means.
+    expect(credentials.key).toMatch(/^key-\d+$/)
+    expect(credentials.oauth?.accessToken).toMatch(/^access-\d+$/)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestConcurrentUpdatesAreNotLost — shape (b), two spawned bun processes.
+// This is the shape that actually proves cross-process safety and has no
+// counterpart in the Go suite (goroutines share one flock file description).
+// ---------------------------------------------------------------------------
+
+const WORKER = join(import.meta.dir, "credentialStore.worker.ts")
+
+const spawnWorker = async (
+  configDir: string,
+  mode: string,
+  iterations: string
+): Promise<{ readonly code: number; readonly stderr: string }> => {
+  const proc = Bun.spawn(["bun", "run", WORKER, configDir, mode, iterations], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, OYTC_API_KEY: "" }
+  })
+  const [code, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()])
+  return { code, stderr }
+}
+
+describe("TestConcurrentUpdatesAreNotLost (two spawned bun subprocesses)", () => {
+  test(
+    "an api-key writer and an oauth writer in SEPARATE processes both survive",
+    async () => {
+      const dir = tempDir()
+
+      const [keyWorker, oauthWorker] = await Promise.all([
+        spawnWorker(dir, "key", "25"),
+        spawnWorker(dir, "oauth", "25")
+      ])
+
+      expect(keyWorker.stderr).toBe("")
+      expect(oauthWorker.stderr).toBe("")
+      expect(keyWorker.code).toBe(0)
+      expect(oauthWorker.code).toBe(0)
+
+      const credentials = await runIn(storeAt(dir), (store) => store.load)
+      // Each process hammered its own field 25 times while the other did the
+      // same. With only an atomic rename and no lock, one field would be gone.
+      expect(credentials.key).toBe("api-secret-24")
+      expect(credentials.oauth?.accessToken).toBe("access-24")
+      expect(credentials.oauth?.refreshToken).toBe("refresh")
+      expect(credentials.oauth?.scopes).toEqual(["scope"])
+    },
+    60_000
+  )
+
+  test(
+    "the file is never observed torn or truncated by a concurrent reader",
+    async () => {
+      // A reader process parsing auth.json while two writers race proves the
+      // temp-file + fsync + rename sequence really is atomic to readers.
+      const dir = tempDir()
+      const results = await Promise.all([
+        spawnWorker(dir, "key", "20"),
+        spawnWorker(dir, "oauth", "20"),
+        spawnWorker(dir, "read", "60")
+      ])
+      for (const result of results) {
+        expect(result.stderr).toBe("")
+        expect(result.code).toBe(0)
+      }
+    },
+    60_000
+  )
+})
+
+// ---------------------------------------------------------------------------
+// TestRefreshedOAuthDoesNotRestoreRemovedCredentials
+// ---------------------------------------------------------------------------
+
+describe("TestRefreshedOAuthDoesNotRestoreRemovedCredentials", () => {
+  test("a stale refresh does not resurrect credentials removed by logout", async () => {
+    const layer = storeAt(tempDir())
+    const initial = oauth({ accessToken: "old-access" })
+
+    await runIn(layer, (store) => store.saveOAuth(initial))
+    const removed = await runIn(layer, (store) => store.remove)
+    expect(removed.removed).toBe(true)
+
+    const updated = oauth({ accessToken: "new-access", expiry: "2026-02-01T13:00:00Z" })
+    const saved = await runIn(layer, (store) => store.saveRefreshedOAuth(initial, updated))
+
+    // No write, no error — the whole point of the compare-and-swap.
+    expect(saved).toBe(false)
+    expect(existsSync(removed.path)).toBe(false)
+  })
+
+  test("a matching expectation DOES write and preserves the api_key", async () => {
+    const layer = storeAt(tempDir())
+    const initial = oauth({ accessToken: "old-access" })
+    await runIn(layer, (store) => store.save("keep-me"))
+    await runIn(layer, (store) => store.saveOAuth(initial))
+
+    const updated = oauth({ accessToken: "new-access", expiry: "2026-02-01T13:00:00Z" })
+    expect(await runIn(layer, (store) => store.saveRefreshedOAuth(initial, updated))).toBe(true)
+
+    const credentials = await runIn(layer, (store) => store.load)
+    expect(credentials.oauth?.accessToken).toBe("new-access")
+    expect(credentials.oauth?.expiry).toBe("2026-02-01T13:00:00Z")
+    // The api_key is re-read inside the lock and carried across.
+    expect(credentials.key).toBe("keep-me")
+  })
+
+  test.each([
+    ["clientId", { clientId: "different" }],
+    ["clientSecret", { clientSecret: "different" }],
+    ["accessToken", { accessToken: "different" }],
+    ["refreshToken", { refreshToken: "different" }],
+    ["expiry", { expiry: "different" }],
+    ["scope count", { scopes: ["scope", "extra"] }],
+    ["scope order", { scopes: ["b", "a"] }]
+  ] as ReadonlyArray]>)(
+    "a mismatched %s blocks the write",
+    async (_name, patch) => {
+      const layer = storeAt(tempDir())
+      const stored = oauth({ scopes: ["a", "b"] })
+      await runIn(layer, (store) => store.saveOAuth(stored))
+
+      const expected = { ...stored, ...patch }
+      const updated = oauth({ accessToken: "new-access", scopes: ["a", "b"] })
+      expect(await runIn(layer, (store) => store.saveRefreshedOAuth(expected, updated))).toBe(
+        false
+      )
+
+      // The stored block is untouched.
+      const credentials = await runIn(layer, (store) => store.load)
+      expect(credentials.oauth?.accessToken).toBe("access")
+    }
+  )
+
+  test("a login that replaced the credentials mid-refresh also blocks the write", async () => {
+    const layer = storeAt(tempDir())
+    const original = oauth({ accessToken: "original" })
+    await runIn(layer, (store) => store.saveOAuth(original))
+
+    // A new `login` lands while the refresh is in flight.
+    await runIn(layer, (store) => store.saveOAuth(oauth({ accessToken: "from-new-login" })))
+
+    const refreshed = oauth({ accessToken: "refreshed-from-original" })
+    expect(await runIn(layer, (store) => store.saveRefreshedOAuth(original, refreshed))).toBe(
+      false
+    )
+    expect((await runIn(layer, (store) => store.load)).oauth?.accessToken).toBe("from-new-login")
+  })
+
+  test("expecting undefined against an empty file writes", async () => {
+    const layer = storeAt(tempDir())
+    const next = oauth()
+    expect(await runIn(layer, (store) => store.saveRefreshedOAuth(undefined, next))).toBe(true)
+    expect((await runIn(layer, (store) => store.load)).oauth?.accessToken).toBe("access")
+  })
+
+  test("expecting undefined against a populated file does not write", async () => {
+    const layer = storeAt(tempDir())
+    await runIn(layer, (store) => store.saveOAuth(oauth({ accessToken: "stored" })))
+    expect(
+      await runIn(layer, (store) => store.saveRefreshedOAuth(undefined, oauth({ accessToken: "x" })))
+    ).toBe(false)
+    expect((await runIn(layer, (store) => store.load)).oauth?.accessToken).toBe("stored")
+  })
+
+  test("the replacement is normalized before the compare", async () => {
+    const layer = storeAt(tempDir())
+    const exit = await exitIn(layer, (store) =>
+      store.saveRefreshedOAuth(undefined, oauth({ clientId: "  " }))
+    )
+    expect(failureMessage(exit)).toContain("OAuth client ID and client secret cannot be empty")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestLoadFallsBackToEnvironmentKeyWhenFileCorrupt
+// ---------------------------------------------------------------------------
+
+describe("TestLoadFallsBackToEnvironmentKeyWhenFileCorrupt", () => {
+  test("a corrupt auth.json falls back to OYTC_API_KEY without an error", async () => {
+    const dir = tempDir()
+    writeFileSync(join(dir, "auth.json"), "{not json", { mode: 0o600 })
+
+    const credentials = await runIn(
+      storeAt(dir, { OYTC_API_KEY: "environment-secret" }),
+      (store) => store.load
+    )
+    expect(credentials.key).toBe("environment-secret")
+    expect(credentials.source).toBe("OYTC_API_KEY")
+    // A corrupt file yields no OAuth: nothing could be parsed out of it.
+    expect(credentials.oauth).toBeUndefined()
+  })
+
+  test("without the env key, a corrupt file is a parse error", async () => {
+    const dir = tempDir()
+    writeFileSync(join(dir, "auth.json"), "{not json", { mode: 0o600 })
+    const exit = await exitIn(storeAt(dir), (store) => store.load)
+    expect(failureMessage(exit)).toContain("parse credentials")
+  })
+
+  test("a type error inside a well-formed file is also a parse error", async () => {
+    const dir = tempDir()
+    writeFileSync(join(dir, "auth.json"), '{"api_key":123}', { mode: 0o600 })
+    const exit = await exitIn(storeAt(dir), (store) => store.load)
+    expect(failureMessage(exit)).toContain("parse credentials")
+  })
+
+  test("a whitespace-only env key does NOT rescue a corrupt file", async () => {
+    const dir = tempDir()
+    writeFileSync(join(dir, "auth.json"), "{not json", { mode: 0o600 })
+    const exit = await exitIn(storeAt(dir, { OYTC_API_KEY: "   " }), (store) => store.load)
+    expect(failureMessage(exit)).toContain("parse credentials")
+  })
+
+  test("mutations stay STRICT on a corrupt file even with the env key set", async () => {
+    // Falling back on a mutation would rewrite the file from an empty
+    // in-memory File and silently destroy the user's stored OAuth block.
+    const dir = tempDir()
+    const path = join(dir, "auth.json")
+    writeFileSync(path, "{not json", { mode: 0o600 })
+
+    const layer = storeAt(dir, { OYTC_API_KEY: "environment-secret" })
+    const exit = await exitIn(layer, (store) => store.save("new-key"))
+    expect(failureMessage(exit)).toContain("parse credentials")
+    expect(readFileSync(path, "utf8")).toBe("{not json")
+  })
+
+  test("a directory where auth.json should be is a read error, not a parse error", async () => {
+    const dir = tempDir()
+    const layer = storeAt(dir)
+    // Force the path to be a directory.
+    await runIn(layer, (store) => store.path)
+    const { mkdirSync } = await import("node:fs")
+    mkdirSync(join(dir, "auth.json"))
+    const exit = await exitIn(layer, (store) => store.load)
+    expect(failureMessage(exit)).toContain("read credentials")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestEnvironmentKeyHasPrecedence
+// ---------------------------------------------------------------------------
+
+describe("TestEnvironmentKeyHasPrecedence", () => {
+  test("OYTC_API_KEY overrides the stored key", async () => {
+    const dir = tempDir()
+    await runIn(storeAt(dir), (store) => store.save("file-secret"))
+
+    const credentials = await runIn(
+      storeAt(dir, { OYTC_API_KEY: "environment-secret" }),
+      (store) => store.load
+    )
+    expect(credentials.key).toBe("environment-secret")
+    expect(credentials.source).toBe("OYTC_API_KEY")
+  })
+
+  test("the env key is trimmed", async () => {
+    const credentials = await runIn(
+      storeAt(tempDir(), { OYTC_API_KEY: "  environment-secret  " }),
+      (store) => store.load
+    )
+    expect(credentials.key).toBe("environment-secret")
+  })
+
+  test("a whitespace-only env key is treated as unset", async () => {
+    const dir = tempDir()
+    await runIn(storeAt(dir), (store) => store.save("file-secret"))
+    const credentials = await runIn(storeAt(dir, { OYTC_API_KEY: "  " }), (store) => store.load)
+    expect(credentials.key).toBe("file-secret")
+    expect(credentials.source).toBe("auth.json")
+  })
+
+  test("the env key never clears stored OAuth", async () => {
+    const dir = tempDir()
+    await runIn(storeAt(dir), (store) => store.saveOAuth(oauth()))
+    const credentials = await runIn(
+      storeAt(dir, { OYTC_API_KEY: "environment-secret" }),
+      (store) => store.load
+    )
+    expect(credentials.key).toBe("environment-secret")
+    expect(credentials.oauth?.clientId).toBe("id")
+  })
+
+  test("an oauth-only file leaves source empty", async () => {
+    const dir = tempDir()
+    await runIn(storeAt(dir), (store) => store.saveOAuth(oauth()))
+    const credentials = await runIn(storeAt(dir), (store) => store.load)
+    expect(credentials.key).toBe("")
+    expect(credentials.source).toBe("")
+    expect(credentials.oauth).toBeDefined()
+  })
+
+  test("envKeySet mirrors the trimmed-nonempty test", async () => {
+    expect(await runIn(storeAt(tempDir(), { OYTC_API_KEY: "k" }), (s) => s.envKeySet)).toBe(true)
+    expect(await runIn(storeAt(tempDir(), { OYTC_API_KEY: " " }), (s) => s.envKeySet)).toBe(false)
+    expect(await runIn(storeAt(tempDir()), (s) => s.envKeySet)).toBe(false)
+  })
+
+  test("the stored key is trimmed on load", async () => {
+    const dir = tempDir()
+    writeFileSync(join(dir, "auth.json"), '{"api_key":"  padded  "}', { mode: 0o600 })
+    expect((await runIn(storeAt(dir), (store) => store.load)).key).toBe("padded")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestFingerprintDoesNotExposeKey
+// ---------------------------------------------------------------------------
+
+describe("TestFingerprintDoesNotExposeKey", () => {
+  test("the fingerprint is a 19-character prefixed digest that leaks nothing", () => {
+    const key = "this-is-a-secret-key"
+    const value = fingerprint(key)
+    expect(value.startsWith("sha256:")).toBe(true)
+    expect(value.includes(key)).toBe(false)
+    expect(value.length).toBe("sha256:".length + 12)
+  })
+
+  test.each([
+    // Reference values captured from Go's crypto/sha256 + encoding/hex.
+    ["this-is-a-secret-key", "sha256:e0c2f4e37886"],
+    ["test-secret-key", "sha256:2ceac6f36363"]
+  ])("fingerprint(%s) matches Go", (key, expected) => {
+    expect(fingerprint(key)).toBe(expected)
+  })
+
+  test("an empty or whitespace-only key fingerprints to the empty string", () => {
+    expect(fingerprint("")).toBe("")
+    expect(fingerprint("   ")).toBe("")
+  })
+
+  test("the key is trimmed before hashing", () => {
+    expect(fingerprint("  test-secret-key  ")).toBe(fingerprint("test-secret-key"))
+  })
+
+  test("the service exposes the same function", async () => {
+    const value = await runIn(storeAt(tempDir()), (store) =>
+      Effect.succeed(store.fingerprint("test-secret-key"))
+    )
+    expect(value).toBe("sha256:2ceac6f36363")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Remove
+// ---------------------------------------------------------------------------
+
+describe("remove", () => {
+  test("creates the config directory when it does not exist yet", async () => {
+    const root = tempDir()
+    const configDir = join(root, "never-created")
+    const result = await runIn(storeAt(configDir), (store) => store.remove)
+    expect(result.removed).toBe(false)
+    // The lockfile has to live somewhere, so the dir is created at 0700.
+    expect(perm(configDir)).toBe(0o700)
+  })
+
+  test("a concurrent save cannot recreate credentials after removal", async () => {
+    // Go takes the update lock inside Remove for exactly this reason.
+    const dir = tempDir()
+    const layer = storeAt(dir)
+    await runIn(layer, (store) => store.save("pre-existing"))
+
+    const outcome = await Effect.runPromise(
+      Effect.gen(function* () {
+        const store = yield* CredentialStore
+        const [saved, removed] = yield* Effect.all(
+          [store.save("racing-write"), store.remove],
+          { concurrency: "unbounded" }
+        )
+        return { saved, removed }
+      }).pipe(Effect.provide(layer)) as Effect.Effect<{
+        readonly saved: string
+        readonly removed: { readonly path: string; readonly removed: boolean }
+      }>
+    )
+
+    // Either order is legal; what is NOT legal is a half-written file. Both
+    // operations were serialized, so the end state is one of two clean states.
+    const path = outcome.removed.path
+    if (existsSync(path)) {
+      // remove ran first, then save recreated the file cleanly.
+      expect(readFileSync(path, "utf8")).toBe('{\n  "api_key": "racing-write"\n}\n')
+    } else {
+      expect(outcome.removed.removed).toBe(true)
+    }
+  })
+})
diff --git a/src/impl/credentialStore.ts b/src/impl/credentialStore.ts
index ca14f9a..d37dddc 100644
--- a/src/impl/credentialStore.ts
+++ b/src/impl/credentialStore.ts
@@ -1,2 +1,410 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Config directory resolution and credential storage — Go's `internal/config`.
+ *
+ * Three behaviors carry real weight and are called out where they are
+ * implemented:
+ *
+ *   - `load` treats a CORRUPT auth.json as recoverable when `OYTC_API_KEY` is
+ *     set. A broken file must never lock a user out of the higher-precedence
+ *     env key. Every *mutating* path keeps the strict behavior: silently
+ *     rewriting a file you failed to parse would destroy credentials.
+ *   - Every mutation is a lock -> read -> mutate -> atomic-write cycle. The
+ *     atomic rename alone is not enough: two concurrent updates would each read
+ *     the old file and the later rename would silently drop the earlier one.
+ *   - `saveRefreshedOAuth` is a compare-and-swap over all six OAuth fields. A
+ *     token refresh that started before a `logout` must not resurrect the
+ *     credentials the user just deleted.
+ */
+
+import { Effect, FileSystem, Layer, Option, Path, Result } from "effect"
+import { createHash } from "node:crypto"
+import { OperationalError } from "../domain/errors.ts"
+import { parseJson } from "../json/parse.ts"
+import {
+  cloneOAuth,
+  decodeAuthFile,
+  emptyAuthFile,
+  encodeAuthFile,
+  sameOAuth,
+  type AuthFile,
+  type AuthOAuth
+} from "../schema/authfile.ts"
+import {
+  CredentialStore,
+  FileLock,
+  ProcessEnv,
+  type CredentialStoreShape,
+  type Credentials,
+  type StoredOAuth
+} from "../services/index.ts"
+import { atomicWriteSecure, ensureSecureDirectory } from "./atomicWrite.ts"
+
+const ENV_KEY = "OYTC_API_KEY"
+const ENV_CONFIG_DIR = "OYTC_CONFIG_DIR"
+const ENV_OAUTH_CLIENT_ID = "OYTC_OAUTH_CLIENT_ID"
+const ENV_OAUTH_CLIENT_SECRET = "OYTC_OAUTH_CLIENT_SECRET"
+const ENV_XDG_CONFIG_HOME = "XDG_CONFIG_HOME"
+const ENV_APPDATA = "APPDATA"
+
+const AUTH_FILE = "auth.json"
+const LOCK_FILE = ".auth.lock"
+
+/** Go's `strings.TrimSpace`, which trims Unicode whitespace on both ends. */
+const trimSpace = (value: string): string => value.trim()
+
+/** `os.Getenv`: an unset variable and an empty one are indistinguishable. */
+const getenv = (env: Option.Option): string => Option.getOrElse(env, () => "")
+
+const isNotFound = (error: unknown): boolean =>
+  typeof error === "object" &&
+  error !== null &&
+  "reason" in error &&
+  typeof (error as { readonly reason: unknown }).reason === "object" &&
+  (error as { readonly reason: { readonly _tag?: unknown } }).reason?._tag === "NotFound"
+
+const errorText = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause)
+
+// ---------------------------------------------------------------------------
+// StoredOAuth <-> AuthOAuth
+// ---------------------------------------------------------------------------
+
+/**
+ * The service contract flattens Go's nil-vs-empty scope slice to a plain array.
+ * That loses nothing: Go's `cloneOAuth` runs `append([]string(nil), s...)`,
+ * which returns nil for an empty input, so Go can never *write* `[]` either —
+ * both directions collapse to `null` on disk.
+ */
+const toStored = (oauth: AuthOAuth): StoredOAuth => ({
+  clientId: oauth.clientId,
+  clientSecret: oauth.clientSecret,
+  accessToken: oauth.accessToken,
+  refreshToken: oauth.refreshToken,
+  expiry: oauth.expiry,
+  scopes: oauth.scopes === undefined ? [] : [...oauth.scopes]
+})
+
+const fromStored = (oauth: StoredOAuth): AuthOAuth => ({
+  clientId: oauth.clientId,
+  clientSecret: oauth.clientSecret,
+  accessToken: oauth.accessToken,
+  refreshToken: oauth.refreshToken,
+  expiry: oauth.expiry,
+  scopes: oauth.scopes.length === 0 ? undefined : [...oauth.scopes]
+})
+
+/** Go's `normalizeOAuth`: trim the five strings, then two validity rules. */
+const normalizeOAuth = (
+  oauth: StoredOAuth
+): Effect.Effect => {
+  const normalized: AuthOAuth = {
+    clientId: trimSpace(oauth.clientId),
+    clientSecret: trimSpace(oauth.clientSecret),
+    accessToken: trimSpace(oauth.accessToken),
+    refreshToken: trimSpace(oauth.refreshToken),
+    expiry: trimSpace(oauth.expiry),
+    // Scopes are neither validated nor normalized.
+    scopes: oauth.scopes.length === 0 ? undefined : [...oauth.scopes]
+  }
+  if (normalized.clientId === "" || normalized.clientSecret === "") {
+    return Effect.fail(
+      new OperationalError({ message: "OAuth client ID and client secret cannot be empty" })
+    )
+  }
+  if (normalized.accessToken === "" && normalized.refreshToken === "") {
+    return Effect.fail(
+      new OperationalError({ message: "OAuth access token or refresh token is required" })
+    )
+  }
+  return Effect.succeed(cloneOAuth(normalized))
+}
+
+// ---------------------------------------------------------------------------
+// Fingerprint
+// ---------------------------------------------------------------------------
+
+/** `"sha256:" + hex(sha256(key)).slice(0, 12)`; `""` for an empty key. */
+export const fingerprint = (key: string): string => {
+  const trimmed = trimSpace(key)
+  if (trimmed === "") return ""
+  return `sha256:${createHash("sha256").update(trimmed, "utf8").digest("hex").slice(0, 12)}`
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+export const makeCredentialStore: Effect.Effect<
+  CredentialStoreShape,
+  never,
+  | FileSystem.FileSystem
+  | Path.Path
+  | (typeof ProcessEnv)["Identifier"]
+  | (typeof FileLock)["Identifier"]
+> = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+  const processEnv = yield* ProcessEnv
+  const lock = yield* FileLock
+
+  const env = (name: string): string => getenv(processEnv.env(name))
+
+  const homeDir = processEnv.homeDir.pipe(
+    Effect.catch((cause) =>
+      Effect.fail(
+        new OperationalError({
+          message: `determine config directory: ${cause.message}`,
+          cause
+        })
+      )
+    )
+  )
+
+  /**
+   * Go's `expandHome`, applied ONLY to `OYTC_CONFIG_DIR`. Expands exactly `~`,
+   * `~/…`, or `~\…` (backslash for Windows). `~user` is NOT supported: it
+   * starts with neither prefix, so it is returned untouched. An unresolvable
+   * home also returns the path unchanged.
+   */
+  const expandHome = (value: string): Effect.Effect => {
+    if (value !== "~" && !value.startsWith("~/") && !value.startsWith("~\\")) {
+      return Effect.succeed(value)
+    }
+    return homeDir.pipe(
+      Effect.map((home) => (value.length === 1 ? home : path.join(home, value.slice(2)))),
+      Effect.catchCause(() => Effect.succeed(value))
+    )
+  }
+
+  const dir: Effect.Effect = Effect.gen(function* () {
+    // The override IS the directory: no "oytc" component is appended.
+    const override = trimSpace(env(ENV_CONFIG_DIR))
+    if (override !== "") return yield* expandHome(override)
+
+    if (processEnv.platform === "darwin") {
+      const home = yield* homeDir
+      return path.join(home, "Library", "Application Support", "oytc")
+    }
+
+    if (processEnv.platform === "win32") {
+      const appData = env(ENV_APPDATA)
+      if (appData === "") {
+        return yield* Effect.fail(
+          new OperationalError({ message: "determine config directory: APPDATA is not set" })
+        )
+      }
+      return path.join(appData, "oytc")
+    }
+
+    // NOT trimmed — only an exactly-empty XDG_CONFIG_HOME counts as unset.
+    const xdg = env(ENV_XDG_CONFIG_HOME)
+    const base = xdg !== "" ? xdg : path.join(yield* homeDir, ".config")
+    return path.join(base, "oytc")
+  })
+
+  const filePath: Effect.Effect = Effect.map(dir, (d) =>
+    path.join(d, AUTH_FILE)
+  )
+
+  const lockPathFor = (authPath: string): string =>
+    path.join(path.dirname(authPath), LOCK_FILE)
+
+  /**
+   * Read + parse `auth.json`. A missing file is `exists: false` with no error;
+   * a read or parse failure is an error carrying Go's message prefix.
+   */
+  interface LoadedFile {
+    readonly file: AuthFile
+    readonly exists: boolean
+  }
+
+  const loadFile = (authPath: string): Effect.Effect =>
+    Effect.gen(function* () {
+      const text: string | undefined = yield* fs.readFileString(authPath).pipe(
+        Effect.catch((cause) =>
+          isNotFound(cause)
+            ? Effect.succeed(undefined)
+            : Effect.fail(
+                new OperationalError({ message: `read credentials: ${errorText(cause)}`, cause })
+              )
+        )
+      )
+      if (text === undefined) return { file: emptyAuthFile, exists: false }
+
+      const parsed = parseJson(text)
+      if (Result.isFailure(parsed)) {
+        return yield* Effect.fail(
+          new OperationalError({ message: `parse credentials: ${parsed.failure.message}` })
+        )
+      }
+      const decoded = decodeAuthFile(parsed.success)
+      if (Result.isFailure(decoded)) {
+        return yield* Effect.fail(
+          new OperationalError({ message: `parse credentials: ${decoded.failure.message}` })
+        )
+      }
+      return { file: decoded.success, exists: true }
+    })
+
+  const saveFile = (
+    authPath: string,
+    file: AuthFile
+  ): Effect.Effect =>
+    atomicWriteSecure(fs, path, authPath, encodeAuthFile(file))
+
+  /**
+   * lock -> read -> mutate -> atomic write. The lock spans the whole cycle;
+   * dropping it between the read and the write is exactly the race that loses
+   * a concurrent update.
+   */
+  const updateFile = (
+    mutate: (file: AuthFile) => AuthFile
+  ): Effect.Effect =>
+    Effect.gen(function* () {
+      const authPath = yield* filePath
+      return yield* lock.withLock(
+        lockPathFor(authPath),
+        Effect.gen(function* () {
+          // Deliberately strict: a parse failure aborts rather than falling
+          // back, so a mutation never silently discards an unreadable file.
+          const { file } = yield* loadFile(authPath)
+          return yield* saveFile(authPath, mutate(file))
+        })
+      )
+    })
+
+  const load: Effect.Effect = Effect.gen(function* () {
+    const authPath = yield* filePath
+    const envKey = trimSpace(env(ENV_KEY))
+
+    const loaded = yield* Effect.result(loadFile(authPath))
+    if (Result.isFailure(loaded)) {
+      // A corrupt auth.json must not block the higher-precedence env key.
+      if (envKey !== "") {
+        const fallback: Credentials = {
+          key: envKey,
+          source: "OYTC_API_KEY",
+          oauth: undefined,
+          path: authPath
+        }
+        return fallback
+      }
+      return yield* Effect.fail(loaded.failure)
+    }
+
+    const { file, exists } = loaded.success
+    let key = ""
+    let source: Credentials["source"] = ""
+    let oauth: StoredOAuth | undefined
+
+    if (exists) {
+      key = trimSpace(file.apiKey)
+      oauth = file.oauth === undefined ? undefined : toStored(cloneOAuth(file.oauth))
+      if (key !== "") source = "auth.json"
+    }
+    if (envKey !== "") {
+      key = envKey
+      source = "OYTC_API_KEY"
+    }
+    // Note the env key never clears stored OAuth: both are returned together.
+    const credentials: Credentials = { key, source, oauth, path: authPath }
+    return credentials
+  })
+
+  const save = (key: string): Effect.Effect => {
+    const trimmed = trimSpace(key)
+    if (trimmed === "") {
+      return Effect.fail(new OperationalError({ message: "API key cannot be empty" }))
+    }
+    return updateFile((file) => ({ ...file, apiKey: trimmed }))
+  }
+
+  const saveOAuth = (credentials: StoredOAuth): Effect.Effect =>
+    Effect.flatMap(normalizeOAuth(credentials), (normalized) =>
+      updateFile((file) => ({ ...file, oauth: cloneOAuth(normalized) }))
+    )
+
+  const saveRefreshedOAuth = (
+    expected: StoredOAuth | undefined,
+    next: StoredOAuth
+  ): Effect.Effect =>
+    Effect.gen(function* () {
+      const normalized = yield* normalizeOAuth(next)
+      const authPath = yield* filePath
+      const expectedOAuth = expected === undefined ? undefined : fromStored(expected)
+
+      return yield* lock.withLock(
+        lockPathFor(authPath),
+        Effect.gen(function* () {
+          const { file } = yield* loadFile(authPath)
+          // Compare-and-swap. A mismatch — including a file removed by a
+          // concurrent `logout` — writes NOTHING and reports false, not an
+          // error. This is what stops a refresh from resurrecting credentials.
+          if (!sameOAuth(file.oauth, expectedOAuth)) return false
+          yield* saveFile(authPath, { apiKey: file.apiKey, oauth: cloneOAuth(normalized) })
+          return true
+        })
+      )
+    })
+
+  const clearOAuth: Effect.Effect = updateFile((file) => ({
+    ...file,
+    oauth: undefined
+  }))
+
+  interface RemoveResult {
+    readonly path: string
+    readonly removed: boolean
+  }
+
+  const remove: Effect.Effect = Effect.gen(function* () {
+    const authPath = yield* filePath
+    const lockPath = lockPathFor(authPath)
+    // The lockfile lives in the config dir, so the dir has to exist before the
+    // lock can be taken even when there is nothing to remove.
+    yield* ensureSecureDirectory(fs, path.dirname(authPath))
+
+    // Taking the same lock as saves is deliberate: a concurrent save that has
+    // already read the file must not be able to recreate it after removal.
+    return yield* lock.withLock(
+      lockPath,
+      fs.remove(authPath).pipe(
+        Effect.as({ path: authPath, removed: true }),
+        Effect.catch((cause) =>
+          isNotFound(cause)
+            ? Effect.succeed({ path: authPath, removed: false })
+            : Effect.fail(
+                new OperationalError({
+                  message: `remove credentials: ${errorText(cause)}`,
+                  cause
+                })
+              )
+        )
+      )
+    )
+  })
+
+  const envKeySet: Effect.Effect = Effect.sync(() => trimSpace(env(ENV_KEY)) !== "")
+
+  const oauthBootstrap: Effect.Effect =
+    Effect.sync(
+      () =>
+        [trimSpace(env(ENV_OAUTH_CLIENT_ID)), trimSpace(env(ENV_OAUTH_CLIENT_SECRET))] as const
+    )
+
+  return {
+    dir,
+    path: filePath,
+    load,
+    save,
+    saveOAuth,
+    saveRefreshedOAuth,
+    clearOAuth,
+    remove,
+    fingerprint,
+    envKeySet,
+    oauthBootstrap
+  }
+})
+
+export const CredentialStoreLive = Layer.effect(CredentialStore, makeCredentialStore)
diff --git a/src/impl/credentialStore.worker.ts b/src/impl/credentialStore.worker.ts
new file mode 100644
index 0000000..3eda42a
--- /dev/null
+++ b/src/impl/credentialStore.worker.ts
@@ -0,0 +1,104 @@
+/**
+ * Test-only worker for the cross-process locking test.
+ *
+ * NOT part of the CLI — nothing imports it, so `bun build --compile` never
+ * reaches it. It exists because the interesting half of the credential lock
+ * cannot be observed from inside one process: Go's flock is per-open-file-
+ * description, so two goroutines contend the same way two processes do, but
+ * this port's in-process `Semaphore` would happily satisfy a same-process test
+ * even if the O_EXCL lockfile were completely broken. Only real subprocesses
+ * prove the cross-process guarantee.
+ *
+ * Usage: `bun run credentialStore.worker.ts   `
+ *
+ *   key    — save "api-secret-", i = 0..n-1
+ *   oauth  — save an oauth block with accessToken "access-"
+ *   read   — load n times, asserting the file is never observed torn
+ *
+ * Exits 0 on success. Any failure is written to stderr and exits 1; the test
+ * asserts stderr is empty, so a partial read or a lost update is loud.
+ */
+
+import { Effect, Layer, Option } from "effect"
+import { BunServices } from "@effect/platform-bun"
+import { OperationalError } from "../domain/errors.ts"
+import {
+  CredentialStore,
+  ProcessEnv,
+  type CredentialStoreShape,
+  type ProcessEnvShape,
+  type StoredOAuth
+} from "../services/index.ts"
+import { CredentialStoreLive } from "./credentialStore.ts"
+import { FileLockLive } from "./fileLock.ts"
+
+const [configDir, mode, iterationsText] = process.argv.slice(2)
+
+if (configDir === undefined || mode === undefined || iterationsText === undefined) {
+  process.stderr.write("usage: credentialStore.worker.ts   \n")
+  process.exit(1)
+}
+
+const iterations = Number.parseInt(iterationsText, 10)
+
+const processEnv: ProcessEnvShape = {
+  env: (name) => Option.fromNullishOr(name === "OYTC_CONFIG_DIR" ? configDir : undefined),
+  platform: process.platform,
+  arch: process.arch,
+  argv: process.argv,
+  executablePath: Effect.succeed(process.execPath),
+  isOutputTTY: false,
+  homeDir: Effect.fail(new OperationalError({ message: "could not determine home directory" }))
+}
+
+const platform = BunServices.layer as unknown as Layer.Layer
+
+const layer = CredentialStoreLive.pipe(
+  Layer.provide(
+    Layer.mergeAll(
+      platform,
+      Layer.succeed(ProcessEnv, processEnv),
+      FileLockLive.pipe(Layer.provide(platform))
+    )
+  )
+) as unknown as Layer.Layer<(typeof CredentialStore)["Identifier"]>
+
+const oauthFor = (index: number): StoredOAuth => ({
+  clientId: "id",
+  clientSecret: "secret",
+  accessToken: `access-${index}`,
+  refreshToken: "refresh",
+  expiry: "2026-02-01T12:00:00Z",
+  scopes: ["scope"]
+})
+
+const step = (store: CredentialStoreShape, index: number): Effect.Effect => {
+  switch (mode) {
+    case "key":
+      return Effect.asVoid(store.save(`api-secret-${index}`))
+    case "oauth":
+      return Effect.asVoid(store.saveOAuth(oauthFor(index)))
+    case "read":
+      // A torn read shows up as a parse error, which `load` surfaces as a
+      // failure (there is no OYTC_API_KEY here to mask it).
+      return Effect.asVoid(store.load)
+    default:
+      return Effect.fail(new Error(`unknown worker mode: ${mode}`))
+  }
+}
+
+const program = Effect.gen(function* () {
+  const store = yield* CredentialStore
+  for (let index = 0; index < iterations; index++) {
+    yield* step(store, index)
+  }
+})
+
+const exit = await Effect.runPromiseExit(
+  program.pipe(Effect.provide(layer)) as Effect.Effect
+)
+
+if (exit._tag === "Failure") {
+  process.stderr.write(`worker ${mode} failed: ${String(exit.cause)}\n`)
+  process.exit(1)
+}
diff --git a/src/impl/fileLock.test.ts b/src/impl/fileLock.test.ts
new file mode 100644
index 0000000..9823981
--- /dev/null
+++ b/src/impl/fileLock.test.ts
@@ -0,0 +1,292 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { Effect, FileSystem, Fiber, Layer, Path } from "effect"
+import { BunServices } from "@effect/platform-bun"
+import { existsSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { FileLock } from "../services/index.ts"
+import { FileLockLive, MAX_STEALS, STALE_MILLIS } from "./fileLock.ts"
+
+const temporaries: Array = []
+
+const tempDir = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "oytc-lock-"))
+  temporaries.push(dir)
+  return dir
+}
+
+afterEach(() => {
+  while (temporaries.length > 0) {
+    rmSync(temporaries.pop()!, { recursive: true, force: true })
+  }
+})
+
+const platform = BunServices.layer as unknown as Layer.Layer<
+  FileSystem.FileSystem | Path.Path
+>
+
+/**
+ * A FRESH FileLock per program. The in-process semaphore lives inside the
+ * service, so reusing one memoized layer across tests would silently serialize
+ * unrelated cases — and, worse, hide a broken lockfile behind a working
+ * semaphore. Tests that must exercise the O_EXCL path use two layers.
+ */
+const lockLayer = (): Layer.Layer =>
+  Layer.fresh(FileLockLive.pipe(Layer.provide(platform))) as unknown as Layer.Layer<
+    never,
+    never,
+    never
+  >
+
+const runWith = (
+  layer: Layer.Layer,
+  effect: Effect.Effect
+): Promise =>
+  Effect.runPromise(
+    effect.pipe(Effect.provide(layer as unknown as Layer.Layer<(typeof FileLock)["Identifier"]>))
+  )
+
+const run = (
+  effect: Effect.Effect
+): Promise => runWith(lockLayer(), effect)
+
+describe("FileLock", () => {
+  test("runs the effect and returns its value", async () => {
+    const lockPath = join(tempDir(), ".auth.lock")
+    const value = await run(
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        return yield* lock.withLock(lockPath, Effect.succeed(42))
+      })
+    )
+    expect(value).toBe(42)
+  })
+
+  test("creates the lock directory when it does not exist", async () => {
+    const lockPath = join(tempDir(), "deep", "nested", ".auth.lock")
+    await run(
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        return yield* lock.withLock(lockPath, Effect.void)
+      })
+    )
+    expect(existsSync(join(lockPath, ".."))).toBe(true)
+  })
+
+  test("holds the lockfile for the critical section and removes it after", async () => {
+    const lockPath = join(tempDir(), ".auth.lock")
+    let heldDuringSection = false
+    await run(
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        yield* lock.withLock(
+          lockPath,
+          Effect.sync(() => {
+            heldDuringSection = existsSync(lockPath)
+          })
+        )
+      })
+    )
+    expect(heldDuringSection).toBe(true)
+    // Unlike Go's flock sidecar, the O_EXCL lockfile IS the lock, so it must
+    // be unlinked on release or the next acquisition would block for 30 s.
+    expect(existsSync(lockPath)).toBe(false)
+  })
+
+  test("releases the lock when the guarded effect fails", async () => {
+    const lockPath = join(tempDir(), ".auth.lock")
+    const layer = lockLayer()
+    const boom = Effect.gen(function* () {
+      const lock = yield* FileLock
+      return yield* lock.withLock(lockPath, Effect.fail("boom" as const))
+    })
+    await Effect.runPromise(
+      Effect.exit(
+        boom.pipe(
+          Effect.provide(layer as unknown as Layer.Layer<(typeof FileLock)["Identifier"]>)
+        )
+      )
+    )
+    expect(existsSync(lockPath)).toBe(false)
+
+    // And the lock is reusable afterwards.
+    const value = await runWith(
+      layer,
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        return yield* lock.withLock(lockPath, Effect.succeed("second"))
+      })
+    )
+    expect(value).toBe("second")
+  })
+
+  test("releases the lock when the guarded effect is interrupted", async () => {
+    const lockPath = join(tempDir(), ".auth.lock")
+    await run(
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        const fiber = yield* Effect.forkChild(
+          lock.withLock(lockPath, Effect.sleep("30 seconds"))
+        )
+        // Let the fiber reach the critical section before interrupting.
+        yield* Effect.sleep(30)
+        yield* Fiber.interrupt(fiber)
+      })
+    )
+    expect(existsSync(lockPath)).toBe(false)
+  })
+
+  test("a fiber WAITING on a contended lock is still interruptible", async () => {
+    // Regression: `Effect.acquireRelease` runs acquire uninterruptibly by
+    // default, which made the unbounded retry loop unkillable — a second
+    // `oytc` blocked on a lock held by a first would ignore Ctrl-C entirely,
+    // where Go's blocking flock is torn down by the signal.
+    const dir = tempDir()
+    const lockPath = join(dir, ".auth.lock")
+    // A FRESH lockfile held by "someone else": too young to steal, so the
+    // acquire spins forever and the only way out is interruption.
+    writeFileSync(lockPath, "", { mode: 0o600 })
+
+    const interrupted = run(
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        const fiber = yield* Effect.forkChild(lock.withLock(lockPath, Effect.succeed("never")))
+        yield* Effect.sleep(60)
+        yield* Fiber.interrupt(fiber)
+        return "interrupted" as const
+      })
+    )
+
+    const raced = await Promise.race([
+      interrupted,
+      Bun.sleep(3_000).then(() => "hung" as const)
+    ])
+    expect(raced).toBe("interrupted")
+    // The contended lockfile belonged to someone else and must survive.
+    expect(existsSync(lockPath)).toBe(true)
+  })
+
+  test("serializes concurrent fibers in one process", async () => {
+    const lockPath = join(tempDir(), ".auth.lock")
+    let inside = 0
+    let maxInside = 0
+    const order: Array = []
+
+    const section = (name: string) =>
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        yield* lock.withLock(
+          lockPath,
+          Effect.gen(function* () {
+            inside++
+            maxInside = Math.max(maxInside, inside)
+            order.push(`${name}:enter`)
+            yield* Effect.sleep(25)
+            order.push(`${name}:exit`)
+            inside--
+          })
+        )
+      })
+
+    await run(
+      Effect.all([section("a"), section("b"), section("c")], { concurrency: "unbounded" })
+    )
+
+    expect(maxInside).toBe(1)
+    // No interleaving: every enter is immediately followed by its own exit.
+    for (let i = 0; i < order.length; i += 2) {
+      expect(order[i]!.split(":")[0]).toBe(order[i + 1]!.split(":")[0]!)
+    }
+  })
+
+  test("blocks a SECOND lock instance until the first releases (the O_EXCL path)", async () => {
+    // Two service instances share no semaphore, so this exercises the
+    // cross-process mechanism inside one process.
+    const lockPath = join(tempDir(), ".auth.lock")
+    const first = lockLayer()
+    const second = lockLayer()
+    const events: Array = []
+
+    const holder = runWith(
+      first,
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        yield* lock.withLock(
+          lockPath,
+          Effect.gen(function* () {
+            events.push("first:enter")
+            yield* Effect.sleep(120)
+            events.push("first:exit")
+          })
+        )
+      })
+    )
+
+    // Give the holder time to actually take the lock before contending.
+    await Bun.sleep(20)
+
+    const waiter = runWith(
+      second,
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        yield* lock.withLock(
+          lockPath,
+          Effect.sync(() => {
+            events.push("second:enter")
+          })
+        )
+      })
+    )
+
+    await Promise.all([holder, waiter])
+    expect(events).toEqual(["first:enter", "first:exit", "second:enter"])
+  })
+
+  test("steals a lockfile whose mtime is older than the staleness window", async () => {
+    // Simulates a process killed with SIGKILL mid-update: flock would have
+    // been released by the kernel, an O_EXCL file would not.
+    const dir = tempDir()
+    const lockPath = join(dir, ".auth.lock")
+    writeFileSync(lockPath, "", { mode: 0o600 })
+    const ancient = (Date.now() - STALE_MILLIS - 60_000) / 1000
+    utimesSync(lockPath, ancient, ancient)
+
+    const start = Date.now()
+    const value = await run(
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        return yield* lock.withLock(lockPath, Effect.succeed("stolen"))
+      })
+    )
+    expect(value).toBe("stolen")
+    // The steal must be immediate, not a 30 s wait.
+    expect(Date.now() - start).toBeLessThan(2_000)
+  })
+
+  test("does NOT steal a lockfile that is still fresh", async () => {
+    const dir = tempDir()
+    const lockPath = join(dir, ".auth.lock")
+    writeFileSync(lockPath, "", { mode: 0o600 })
+
+    const attempt = run(
+      Effect.gen(function* () {
+        const lock = yield* FileLock
+        return yield* lock.withLock(lockPath, Effect.succeed("acquired"))
+      })
+    )
+    const raced = await Promise.race([attempt, Bun.sleep(250).then(() => "timeout" as const)])
+    expect(raced).toBe("timeout")
+
+    // Release it so the pending acquisition (which is unbounded, like Go's
+    // blocking flock) can finish and the test does not leak a live promise.
+    rmSync(lockPath, { force: true })
+    expect(await attempt).toBe("acquired")
+  })
+
+  test("the steal budget is bounded", () => {
+    // Documented invariant: two processes stealing from each other must not
+    // livelock, so steals are capped and the loop falls back to waiting.
+    expect(MAX_STEALS).toBe(3)
+    expect(STALE_MILLIS).toBe(30_000)
+  })
+})
diff --git a/src/impl/fileLock.ts b/src/impl/fileLock.ts
index ca14f9a..149b1ad 100644
--- a/src/impl/fileLock.ts
+++ b/src/impl/fileLock.ts
@@ -1,2 +1,142 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Cross-process advisory lock over the credential file.
+ *
+ * Go holds a blocking `flock(LOCK_EX)` (unix) / `LockFileEx` (windows) on a
+ * `.auth.lock` sidecar for the entire read-modify-write. Bun exposes neither,
+ * so this reconstructs the same guarantees from three parts:
+ *
+ *   1. **An O_EXCL lockfile.** `open(path, "wx", 0o600)` succeeds for exactly
+ *      one process; everyone else retries. This is the cross-process piece.
+ *   2. **An in-process semaphore.** O_EXCL says nothing about two fibers in one
+ *      process: without it fiber B would spin on a lockfile fiber A holds until
+ *      a retry happened to interleave. One permit, taken *outside* the lockfile
+ *      acquisition, makes same-process contention deterministic and FIFO — the
+ *      direct analogue of flock being per-open-file-description.
+ *   3. **A staleness steal.** flock is released by the kernel when the holder
+ *      dies; an O_EXCL file is not, so a `kill -9` mid-update would wedge every
+ *      future invocation forever. If the lockfile's mtime is older than
+ *      `STALE_MILLIS` it is unlinked and the acquisition retried, bounded to
+ *      `MAX_STEALS` so two processes cannot livelock stealing from each other.
+ *
+ * Retry is unbounded (10 ms + jitter), matching Go's blocking flock: `oytc`
+ * waits for a concurrent update rather than failing.
+ *
+ * The lockfile is REMOVED on release — unlike Go, which keeps `.auth.lock`
+ * around forever. It has to be: with O_EXCL the file's *existence* is the lock.
+ *
+ * Release runs in an `Effect.acquireRelease` finalizer, so SIGINT under
+ * `BunRuntime.runMain` frees the lock rather than stranding it for 30 s.
+ *
+ * INTERRUPTION: `acquireRelease` makes its acquire uninterruptible by default,
+ * so the retry loop below wraps its sleep in `Effect.interruptible` explicitly.
+ * Without that, a process merely *waiting* for a contended lock could not be
+ * killed by Ctrl-C at all. See the comment on the loop for why the interruptible
+ * window is the sleep and not the whole acquire.
+ */
+
+import { Effect, FileSystem, Layer, Option, Path, Semaphore } from "effect"
+import { OperationalError } from "../domain/errors.ts"
+import { FileLock, type FileLockShape } from "../services/index.ts"
+
+/** A lockfile older than this is assumed abandoned by a crashed process. */
+export const STALE_MILLIS = 30_000
+
+/** Bound on steals, so mutual stealing cannot livelock. */
+export const MAX_STEALS = 3
+
+const RETRY_BASE_MILLIS = 10
+const RETRY_JITTER_MILLIS = 10
+
+/** Distinguish "someone else holds it" from a real I/O failure. */
+const isAlreadyExists = (error: unknown): boolean =>
+  typeof error === "object" &&
+  error !== null &&
+  "reason" in error &&
+  typeof (error as { readonly reason: unknown }).reason === "object" &&
+  (error as { readonly reason: { readonly _tag?: unknown } }).reason?._tag === "AlreadyExists"
+
+export const makeFileLock: Effect.Effect<
+  FileLockShape,
+  never,
+  FileSystem.FileSystem | Path.Path
+> = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+  const semaphore = yield* Semaphore.make(1)
+
+  /** One O_EXCL attempt. `true` = acquired, `false` = held by someone else. */
+  const tryCreate = (lockPath: string): Effect.Effect =>
+    fs.writeFileString(lockPath, "", { flag: "wx", mode: 0o600 }).pipe(
+      Effect.as(true),
+      Effect.catch((cause) =>
+        isAlreadyExists(cause)
+          ? Effect.succeed(false)
+          : Effect.fail(new OperationalError({ message: "open credential lock file", cause }))
+      )
+    )
+
+  /**
+   * Unlink the lockfile if its mtime is older than `STALE_MILLIS`.
+   * Every failure here is swallowed: a vanished lockfile, a stat race, or a
+   * permission error all just mean "do not steal", and the caller retries.
+   */
+  const stealIfStale = (lockPath: string): Effect.Effect =>
+    fs.stat(lockPath).pipe(
+      Effect.flatMap((info) => {
+        const mtime = Option.getOrUndefined(info.mtime)
+        if (mtime === undefined) return Effect.succeed(false)
+        if (Date.now() - mtime.getTime() < STALE_MILLIS) return Effect.succeed(false)
+        return fs.remove(lockPath, { force: true }).pipe(Effect.as(true))
+      }),
+      Effect.catchCause(() => Effect.succeed(false))
+    )
+
+  const acquire = (lockPath: string): Effect.Effect =>
+    Effect.gen(function* () {
+      // Go's acquireUpdateLock does MkdirAll(dir, 0700) before opening.
+      yield* fs.makeDirectory(path.dirname(lockPath), { recursive: true, mode: 0o700 }).pipe(
+        Effect.catch((cause) =>
+          Effect.fail(new OperationalError({ message: "create config directory", cause }))
+        )
+      )
+      let steals = 0
+      // Unbounded, like Go's blocking flock.
+      //
+      // The retry sleep is EXPLICITLY `Effect.interruptible`. `acquireRelease`
+      // runs its acquire inside an uninterruptible region by default, which
+      // would make this loop unkillable: a second `oytc` waiting on a lock held
+      // by a first would ignore Ctrl-C entirely, where Go's blocking flock is
+      // torn down by the signal. Interruption is confined to the sleep on
+      // purpose — that is the one point where no lockfile is held, so an
+      // interrupt can never strand one. (`{ interruptible: true }` on
+      // acquireRelease would ALSO admit an interrupt between `tryCreate`
+      // succeeding and the finalizer being registered, stranding the lockfile
+      // for the full STALE_MILLIS window.)
+      for (;;) {
+        if (yield* tryCreate(lockPath)) return
+        if (steals < MAX_STEALS && (yield* stealIfStale(lockPath))) {
+          steals++
+          continue
+        }
+        yield* Effect.interruptible(
+          Effect.sleep(RETRY_BASE_MILLIS + Math.random() * RETRY_JITTER_MILLIS)
+        )
+      }
+    })
+
+  /** Best effort: a lockfile someone already stole must not fail the release. */
+  const release = (lockPath: string): Effect.Effect =>
+    fs.remove(lockPath, { force: true }).pipe(Effect.catchCause(() => Effect.void))
+
+  const withLock: FileLockShape["withLock"] = (lockPath, effect) =>
+    Effect.scoped(
+      Effect.flatMap(
+        Effect.acquireRelease(acquire(lockPath), () => release(lockPath)),
+        () => effect
+      )
+    ).pipe(semaphore.withPermit)
+
+  return { withLock }
+})
+
+export const FileLockLive = Layer.effect(FileLock, makeFileLock)
diff --git a/src/impl/httpCore.test.ts b/src/impl/httpCore.test.ts
new file mode 100644
index 0000000..bf622c0
--- /dev/null
+++ b/src/impl/httpCore.test.ts
@@ -0,0 +1,922 @@
+/**
+ * Transport tests.
+ *
+ * Every case runs against a stub `fetch` injected through
+ * `Layer.succeed(FetchHttpClient.Fetch, ...)` — no sockets, no test server.
+ * `maxRetries` and `sleep` are injected too, so nothing here ever waits.
+ *
+ * Ported from `internal/youtube/client_test.go`:
+ *   TestGetUsesHeaderNotQueryForKey
+ *   TestBearerAuthenticationForcesOneRefreshAfter401
+ *   TestGetWithoutAuthenticationSendsNoKey
+ *   TestStructuredAPIErrorAndRetry
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Effect, Exit, Layer, Redacted, Cause, Option } from "effect"
+import { FetchHttpClient, HttpClient } from "../effect.ts"
+import { ApiError, MissingKeyError, MissingOAuthError, OperationalError } from "../domain/errors.ts"
+import { encodeGoValue } from "../json/encode.ts"
+import { isJsonObject, isRawNumber, type JsonValue } from "../json/value.ts"
+import type { HttpCoreRequest, HttpCoreShape } from "../services/index.ts"
+import {
+  backoffMillis,
+  buildUrl,
+  DEFAULT_BASE_URL,
+  encodeParams,
+  goAtoi,
+  goQueryEscape,
+  isTransientStatus,
+  makeHttpCore,
+  MAX_BODY_BYTES,
+  toApiError,
+  type HttpCoreConfig
+} from "./httpCore.ts"
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+/**
+ * `FetchHttpClient.Fetch` is typed as the full `typeof globalThis.fetch`, which
+ * under `@types/bun` carries a `preconnect` property. A stub only needs the
+ * call signature, so it is cast at the injection site.
+ */
+type StubFetch = (
+  input: URL | RequestInfo,
+  init?: RequestInit
+) => Promise
+
+const fetchLayer = (stub: StubFetch) =>
+  Layer.succeed(FetchHttpClient.Fetch, stub as unknown as typeof globalThis.fetch)
+
+interface SeenRequest {
+  readonly url: string
+  readonly headers: Record
+}
+
+interface StubResponse {
+  readonly status?: number
+  readonly body?: string
+  readonly headers?: Record
+}
+
+interface Harness {
+  readonly seen: Array
+  readonly slept: Array
+  readonly run: (
+    request: HttpCoreRequest
+  ) => Promise>
+}
+
+const headerRecord = (init: RequestInit | undefined): Record => {
+  const out: Record = {}
+  const headers = init?.headers
+  if (headers === undefined) return out
+  if (headers instanceof Headers) {
+    headers.forEach((v, k) => {
+      out[k.toLowerCase()] = v
+    })
+  } else if (Array.isArray(headers)) {
+    for (const [k, v] of headers) out[String(k).toLowerCase()] = String(v)
+  } else {
+    for (const [k, v] of Object.entries(headers)) out[k.toLowerCase()] = String(v)
+  }
+  return out
+}
+
+/**
+ * `handler` receives the 1-based request number and returns the response for
+ * it, mirroring the `atomic.Int32` counters in the Go tests.
+ */
+const harness = (
+  handler: (n: number, seen: SeenRequest) => StubResponse | Promise,
+  config: Partial = {}
+): Harness => {
+  const seen: Array = []
+  const slept: Array = []
+
+  const stub: StubFetch = async (input, init) => {
+    const record: SeenRequest = { url: String(input), headers: headerRecord(init) }
+    seen.push(record)
+    const result = await handler(seen.length, record)
+    return new Response(result.body ?? "{}", {
+      status: result.status ?? 200,
+      headers: result.headers ?? {}
+    })
+  }
+
+  const full: HttpCoreConfig = {
+    apiKey: config.apiKey ?? "",
+    tokenSource: config.tokenSource,
+    // The Go testClient sets MaxRetries = 0.
+    maxRetries: config.maxRetries ?? 0,
+    sleep: (millis) =>
+      Effect.sync(() => {
+        slept.push(millis)
+      }),
+    jitterMillis: config.jitterMillis ?? (() => 0),
+    timeoutMillis: config.timeoutMillis
+  }
+
+  const run = (request: HttpCoreRequest) =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        const core: HttpCoreShape = yield* makeHttpCore(full)
+        return yield* core.getJson(request)
+      }).pipe(
+        Effect.provide(FetchHttpClient.layer),
+        Effect.provide(fetchLayer(stub)),
+        Effect.exit
+      ) as Effect.Effect<
+        Exit.Exit<
+          JsonValue,
+          ApiError | MissingKeyError | MissingOAuthError | OperationalError
+        >
+      >
+    )
+
+  return { seen, slept, run }
+}
+
+const failureOf = (exit: Exit.Exit): E => {
+  expect(Exit.isFailure(exit)).toBe(true)
+  if (!Exit.isFailure(exit)) throw new Error("unreachable")
+  const error = Cause.findErrorOption(exit.cause)
+  expect(Option.isSome(error)).toBe(true)
+  if (!Option.isSome(error)) throw new Error("unreachable")
+  return error.value
+}
+
+const successOf = (exit: Exit.Exit): A => {
+  if (!Exit.isSuccess(exit)) throw new Error(`expected success, got ${Cause.pretty(exit.cause)}`)
+  return exit.value
+}
+
+const base = (over: Partial = {}): HttpCoreRequest => ({
+  baseUrl: "https://stub.test/youtube/v3",
+  resource: "videos",
+  params: [],
+  authenticate: true,
+  ...over
+})
+
+// ---------------------------------------------------------------------------
+// URL assembly
+// ---------------------------------------------------------------------------
+
+describe("goQueryEscape", () => {
+  // Verified against Go 1.26.5 url.QueryEscape.
+  test.each([
+    [" ", "+"],
+    ["*", "%2A"],
+    ["~", "~"],
+    ["!", "%21"],
+    ["'", "%27"],
+    ["(", "%28"],
+    [")", "%29"],
+    ["-", "-"],
+    ["_", "_"],
+    [".", "."],
+    ["+", "%2B"],
+    ["/", "%2F"],
+    [":", "%3A"],
+    ["=", "%3D"],
+    ["&", "%26"],
+    ["%", "%25"],
+    ["@", "%40"],
+    ["$", "%24"],
+    [",", "%2C"],
+    [";", "%3B"],
+    ["?", "%3F"],
+    ["#", "%23"],
+    ["[", "%5B"],
+    ["]", "%5D"],
+    ["é", "%C3%A9"],
+    ["\n", "%0A"]
+  ])("escapes %p as %p", (input, expected) => {
+    expect(goQueryEscape(input)).toBe(expected)
+  })
+
+  test("differs from encodeURIComponent on !'()*", () => {
+    expect(goQueryEscape("!'()*")).toBe("%21%27%28%29%2A")
+    expect(encodeURIComponent("!'()*")).toBe("!'()*")
+  })
+})
+
+describe("encodeParams", () => {
+  test("sorts keys ascending, uppercase before lowercase", () => {
+    // Go: url.Values{"b":{"2"},"a":{"x y","z*"},"A":{"1"}}.Encode()
+    expect(
+      encodeParams([
+        ["b", "2"],
+        ["a", "x y"],
+        ["a", "z*"],
+        ["A", "1"]
+      ])
+    ).toBe("A=1&a=x+y&a=z%2A&b=2")
+  })
+
+  test("repeated keys keep slice order", () => {
+    expect(
+      encodeParams([
+        ["id", "c"],
+        ["id", "a"],
+        ["id", "b"]
+      ])
+    ).toBe("id=c&id=a&id=b")
+  })
+
+  test("empty params encode to the empty string", () => {
+    expect(encodeParams([])).toBe("")
+  })
+})
+
+describe("buildUrl", () => {
+  test("omits the ? entirely when there are no params", () => {
+    expect(buildUrl("https://x.test/youtube/v3", "videos", [])).toBe(
+      "https://x.test/youtube/v3/videos"
+    )
+  })
+
+  test("preserves an embedded slash in the resource", () => {
+    expect(buildUrl(DEFAULT_BASE_URL, "liveChat/messages", [["part", "snippet"]])).toBe(
+      "https://www.googleapis.com/youtube/v3/liveChat/messages?part=snippet"
+    )
+  })
+
+  test("trims trailing base slashes and leading resource slashes", () => {
+    expect(buildUrl("https://x.test/v3///", "///videos", [])).toBe("https://x.test/v3/videos")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Backoff
+// ---------------------------------------------------------------------------
+
+describe("goAtoi", () => {
+  // Verified against Go 1.26.5 strconv.Atoi.
+  test.each([
+    ["5", 5],
+    ["+5", 5],
+    ["-1", -1],
+    ["0", 0],
+    ["007", 7],
+    ["-0", 0]
+  ])("parses %p", (input, expected) => {
+    expect(goAtoi(input)).toBe(expected)
+  })
+
+  test.each([" 5", "5 ", "5.0", "", "4e2", "0x10", "9999999999999999999999", "Wed, 21 Oct 2015 07:28:00 GMT"])(
+    "rejects %p",
+    (input) => {
+      expect(goAtoi(input)).toBeUndefined()
+    }
+  )
+})
+
+describe("backoffMillis", () => {
+  const noJitter = () => 0
+
+  test("honours an integer Retry-After as seconds", () => {
+    expect(backoffMillis(0, "5", noJitter)).toBe(5000)
+  })
+
+  test("honours Retry-After: 0 as a zero wait", () => {
+    expect(backoffMillis(2, "0", noJitter)).toBe(0)
+  })
+
+  test("falls through on a negative Retry-After", () => {
+    expect(backoffMillis(0, "-1", noJitter)).toBe(250)
+  })
+
+  test("falls through on an HTTP-date Retry-After", () => {
+    expect(backoffMillis(1, "Wed, 21 Oct 2015 07:28:00 GMT", noJitter)).toBe(500)
+  })
+
+  test("exponential base is 250, 500, 1000, 2000", () => {
+    expect([0, 1, 2, 3].map((n) => backoffMillis(n, "", noJitter))).toEqual([250, 500, 1000, 2000])
+  })
+
+  test("jitter is added on top of the exponential base", () => {
+    expect(backoffMillis(0, "", () => 149)).toBe(399)
+  })
+
+  test("real jitter stays in [0,150)", () => {
+    for (let i = 0; i < 500; i++) {
+      const value = backoffMillis(0, "")
+      expect(value).toBeGreaterThanOrEqual(250)
+      expect(value).toBeLessThan(400)
+    }
+  })
+})
+
+describe("isTransientStatus", () => {
+  test("is true for exactly 429/500/502/503/504", () => {
+    expect([429, 500, 502, 503, 504].every(isTransientStatus)).toBe(true)
+    expect([400, 401, 403, 404, 408, 409, 501, 505].some(isTransientStatus)).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+
+describe("authentication", () => {
+  // Go: TestGetUsesHeaderNotQueryForKey
+  test("sends the API key as a header and never in the URL", async () => {
+    const h = harness(
+      () => ({
+        body: `{"items":[{"id":"v","statistics":{"viewCount":"9007199254740993123"}}]}`,
+        headers: { "content-type": "application/json" }
+      }),
+      { apiKey: "super-secret" }
+    )
+
+    const exit = await h.run(
+      base({
+        params: [
+          ["part", "statistics"],
+          ["id", "v"]
+        ]
+      })
+    )
+
+    const value = successOf(exit)
+    expect(h.seen).toHaveLength(1)
+    const request = h.seen[0]!
+    expect(new URL(request.url).pathname).toBe("/youtube/v3/videos")
+    expect(request.headers["x-goog-api-key"]).toBe("super-secret")
+    expect(new URL(request.url).searchParams.get("key")).toBeNull()
+    expect(request.url).not.toContain("super-secret")
+
+    expect(isJsonObject(value)).toBe(true)
+    if (!isJsonObject(value)) throw new Error("unreachable")
+    const items = value["items"] as ReadonlyArray
+    const item = items[0]!
+    if (!isJsonObject(item)) throw new Error("unreachable")
+    expect(item["id"]).toBe("v")
+  }, 10_000)
+
+  test("always sends Accept and User-Agent", async () => {
+    const h = harness(() => ({ body: "{}" }), { apiKey: "k" })
+    await h.run(base())
+    expect(h.seen[0]!.headers["accept"]).toBe("application/json")
+    expect(h.seen[0]!.headers["user-agent"]).toBe("oytc/0.1")
+  })
+
+  // Go: TestGetWithoutAuthenticationSendsNoKey
+  test("sends no credential at all when authenticate is false", async () => {
+    const h = harness(() => ({ body: `{"videoId":"v","permitted":["none"]}` }), {
+      apiKey: "configured-but-unused"
+    })
+
+    const exit = await h.run(
+      base({ resource: "videoTrainability", params: [["id", "v"]], authenticate: false })
+    )
+
+    successOf(exit)
+    expect(h.seen[0]!.headers["x-goog-api-key"]).toBeUndefined()
+    expect(h.seen[0]!.headers["authorization"]).toBeUndefined()
+  })
+
+  test("a token source strictly beats the API key", async () => {
+    const h = harness(() => ({ body: "{}" }), {
+      apiKey: "should-never-be-used",
+      tokenSource: () => Effect.succeed(Redacted.make("tok"))
+    })
+
+    successOf(await h.run(base()))
+    expect(h.seen[0]!.headers["authorization"]).toBe("Bearer tok")
+    expect(h.seen[0]!.headers["x-goog-api-key"]).toBeUndefined()
+  })
+
+  test("a failing token source aborts without falling back to the key", async () => {
+    const h = harness(() => ({ body: "{}" }), {
+      apiKey: "should-never-be-used",
+      tokenSource: () => Effect.fail(new OperationalError({ message: "token boom" }))
+    })
+
+    const error = failureOf(await h.run(base()))
+    expect(error._tag).toBe("OperationalError")
+    expect(error.message).toBe("token boom")
+    // No wrapping, and no request was made.
+    expect(h.seen).toHaveLength(0)
+  })
+
+  test("a whitespace-only token is a fatal MissingOAuthError, not a fallback", async () => {
+    const h = harness(() => ({ body: "{}" }), {
+      apiKey: "present",
+      tokenSource: () => Effect.succeed(Redacted.make("  \t\n "))
+    })
+
+    const error = failureOf(await h.run(base()))
+    expect(error).toBeInstanceOf(MissingOAuthError)
+    expect(error.message).toBe("no OAuth credentials configured; run 'oytc login --oauth'")
+    expect(h.seen).toHaveLength(0)
+  })
+
+  test("the bearer value is used verbatim, untrimmed", async () => {
+    const h = harness(() => ({ body: "{}" }), {
+      tokenSource: () => Effect.succeed(Redacted.make(" padded "))
+    })
+    successOf(await h.run(base()))
+    expect(h.seen[0]!.headers["authorization"]).toBe("Bearer  padded ")
+  })
+
+  test("a whitespace-only API key counts as absent", async () => {
+    const h = harness(() => ({ body: "{}" }), { apiKey: "   " })
+    const error = failureOf(await h.run(base()))
+    expect(error).toBeInstanceOf(MissingKeyError)
+    expect(error.message).toBe("no API key configured; run 'oytc login' or set OYTC_API_KEY")
+    expect(h.seen).toHaveLength(0)
+  })
+
+  test("the API key value is used verbatim, untrimmed", async () => {
+    const h = harness(() => ({ body: "{}" }), { apiKey: " k " })
+    successOf(await h.run(base()))
+    expect(h.seen[0]!.headers["x-goog-api-key"]).toBe(" k ")
+  })
+
+  test("no credentials at all is MissingKeyError", async () => {
+    const h = harness(() => ({ body: "{}" }))
+    expect(failureOf(await h.run(base()))).toBeInstanceOf(MissingKeyError)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 401 refresh
+// ---------------------------------------------------------------------------
+
+describe("401 handling", () => {
+  // Go: TestBearerAuthenticationForcesOneRefreshAfter401
+  test("forces exactly one refresh after a 401 and retries", async () => {
+    let forced = 0
+    let current = "stale-token"
+
+    const h = harness(
+      (n) =>
+        n === 1
+          ? { status: 401, body: `{"error":{"code":401,"message":"expired"}}` }
+          : { body: `{"items":[{"id":"ok"}]}` },
+      {
+        tokenSource: (force) =>
+          Effect.sync(() => {
+            if (force) {
+              forced++
+              current = "fresh-token"
+            }
+            return Redacted.make(current)
+          })
+      }
+    )
+
+    const value = successOf(await h.run(base()))
+
+    expect(h.seen).toHaveLength(2)
+    expect(forced).toBe(1)
+    expect(h.seen[0]!.headers["authorization"]).toBe("Bearer stale-token")
+    expect(h.seen[1]!.headers["authorization"]).toBe("Bearer fresh-token")
+    // A bearer request never also carries an API key.
+    expect(h.seen.every((r) => r.headers["x-goog-api-key"] === undefined)).toBe(true)
+
+    if (!isJsonObject(value)) throw new Error("unreachable")
+    const item = (value["items"] as ReadonlyArray)[0]!
+    if (!isJsonObject(item)) throw new Error("unreachable")
+    expect(item["id"]).toBe("ok")
+    // No sleep on the auth retry — it re-issues immediately.
+    expect(h.slept).toEqual([])
+  })
+
+  test("a second 401 is terminal", async () => {
+    let forced = 0
+    const h = harness(() => ({ status: 401, body: `{"error":{"code":401,"message":"nope"}}` }), {
+      tokenSource: (force) =>
+        Effect.sync(() => {
+          if (force) forced++
+          return Redacted.make("t")
+        })
+    })
+
+    const error = failureOf(await h.run(base()))
+    expect(error).toBeInstanceOf(ApiError)
+    expect(h.seen).toHaveLength(2)
+    expect(forced).toBe(1)
+  })
+
+  test("the refresh is NOT charged against maxRetries", async () => {
+    // maxRetries=1: one auth retry PLUS one transient retry = 3 requests.
+    const h = harness(
+      (n) => {
+        if (n === 1) return { status: 401, body: "{}" }
+        if (n === 2) return { status: 503, body: "{}" }
+        return { body: `{"items":[]}` }
+      },
+      {
+        maxRetries: 1,
+        tokenSource: () => Effect.succeed(Redacted.make("t"))
+      }
+    )
+
+    successOf(await h.run(base()))
+    expect(h.seen).toHaveLength(3)
+    expect(h.slept).toEqual([250])
+  })
+
+  test("with an API key a 401 is terminal, no refresh path exists", async () => {
+    const h = harness(() => ({ status: 401, body: `{"error":{"code":401}}` }), { apiKey: "k" })
+    const error = failureOf(await h.run(base()))
+    expect(error).toBeInstanceOf(ApiError)
+    expect(h.seen).toHaveLength(1)
+  })
+
+  test("a failing forced refresh aborts with that error", async () => {
+    const h = harness(() => ({ status: 401, body: "{}" }), {
+      tokenSource: (force) =>
+        force
+          ? Effect.fail(new OperationalError({ message: "refresh failed" }))
+          : Effect.succeed(Redacted.make("t"))
+    })
+    const error = failureOf(await h.run(base()))
+    expect(error.message).toBe("refresh failed")
+  })
+
+  test("no 401 refresh when authenticate is false", async () => {
+    let calls = 0
+    const h = harness(() => ({ status: 401, body: "{}" }), {
+      tokenSource: () =>
+        Effect.sync(() => {
+          calls++
+          return Redacted.make("t")
+        })
+    })
+    failureOf(await h.run(base({ authenticate: false })))
+    expect(h.seen).toHaveLength(1)
+    expect(calls).toBe(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Retry
+// ---------------------------------------------------------------------------
+
+describe("retry", () => {
+  // Go: TestStructuredAPIErrorAndRetry
+  test("retries a 503 once then returns the 403's parsed error", async () => {
+    const h = harness(
+      (n) =>
+        n === 1
+          ? {
+              status: 503,
+              body: `{"error":{"code":503,"message":"try later","errors":[{"reason":"backendError"}]}}`
+            }
+          : {
+              status: 403,
+              body: `{"error":{"code":403,"message":"quota exhausted","errors":[{"reason":"quotaExceeded"}]}}`
+            },
+      { apiKey: "key", maxRetries: 1 }
+    )
+
+    const error = failureOf(await h.run(base()))
+    expect(error).toBeInstanceOf(ApiError)
+    if (!(error instanceof ApiError)) throw new Error("unreachable")
+    expect(error.code).toBe(403)
+    expect(error.reasons).toEqual(["quotaExceeded"])
+    expect(error.apiMessage).toBe("quota exhausted")
+    expect(h.seen).toHaveLength(2)
+    expect(error.message).toBe("YouTube API error (403, quotaExceeded): quota exhausted")
+  })
+
+  test("maxRetries = 0 means no retries at all", async () => {
+    const h = harness(() => ({ status: 503, body: "{}" }), { apiKey: "k", maxRetries: 0 })
+    failureOf(await h.run(base()))
+    expect(h.seen).toHaveLength(1)
+  })
+
+  test("a transient status exhausts exactly maxRetries retries", async () => {
+    const h = harness(() => ({ status: 500, body: "{}" }), { apiKey: "k", maxRetries: 3 })
+    failureOf(await h.run(base()))
+    expect(h.seen).toHaveLength(4)
+    expect(h.slept).toEqual([250, 500, 1000])
+  })
+
+  test("403 is never retried even though quota arrives as 403", async () => {
+    const h = harness(() => ({ status: 403, body: "{}" }), { apiKey: "k", maxRetries: 3 })
+    failureOf(await h.run(base()))
+    expect(h.seen).toHaveLength(1)
+  })
+
+  test.each([[408], [409], [400], [404], [501]])("%p is not transient", async (status) => {
+    const h = harness(() => ({ status, body: "{}" }), { apiKey: "k", maxRetries: 3 })
+    failureOf(await h.run(base()))
+    expect(h.seen).toHaveLength(1)
+  })
+
+  test("Retry-After is honoured for status retries", async () => {
+    const h = harness(
+      (n) => (n === 1 ? { status: 429, body: "{}", headers: { "retry-after": "5" } } : { body: "{}" }),
+      { apiKey: "k", maxRetries: 1 }
+    )
+    successOf(await h.run(base()))
+    expect(h.slept).toEqual([5000])
+  })
+
+  test("an HTTP-date Retry-After falls back to exponential backoff", async () => {
+    const h = harness(
+      (n) =>
+        n === 1
+          ? { status: 429, body: "{}", headers: { "retry-after": "Wed, 21 Oct 2015 07:28:00 GMT" } }
+          : { body: "{}" },
+      { apiKey: "k", maxRetries: 1 }
+    )
+    successOf(await h.run(base()))
+    expect(h.slept).toEqual([250])
+  })
+
+  test("the retry URL is rebuilt identically and still carries no credentials", async () => {
+    const h = harness((n) => (n === 1 ? { status: 503, body: "{}" } : { body: "{}" }), {
+      apiKey: "secret-key",
+      maxRetries: 1
+    })
+    successOf(await h.run(base({ params: [["id", "v"]] })))
+    expect(h.seen[0]!.url).toBe(h.seen[1]!.url)
+    expect(h.seen.every((r) => !r.url.includes("secret-key"))).toBe(true)
+  })
+
+  test("a transport error is retried within budget then wrapped", async () => {
+    let calls = 0
+    const stub: StubFetch = async () => {
+      calls++
+      throw new TypeError("fetch failed: ECONNRESET")
+    }
+    const slept: Array = []
+    const exit = await Effect.runPromise(
+      Effect.gen(function* () {
+        const core = yield* makeHttpCore({
+          apiKey: "k",
+          tokenSource: undefined,
+          maxRetries: 2,
+          sleep: (m) =>
+            Effect.sync(() => {
+              slept.push(m)
+            }),
+          jitterMillis: () => 0
+        })
+        return yield* core.getJson(base())
+      }).pipe(
+        Effect.provide(FetchHttpClient.layer),
+        Effect.provide(fetchLayer(stub)),
+        Effect.exit
+      ) as Effect.Effect>
+    )
+
+    const error = failureOf(exit)
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toStartWith("request YouTube API: ")
+    expect(calls).toBe(3)
+    expect(slept).toEqual([250, 500])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Response handling
+// ---------------------------------------------------------------------------
+
+describe("response body", () => {
+  test("preserves a 19-digit integer literal byte-identically", async () => {
+    const h = harness(
+      () => ({ body: `{"items":[{"id":"v","statistics":{"viewCount":9007199254740993123}}]}` }),
+      { apiKey: "k" }
+    )
+    const value = successOf(await h.run(base()))
+    if (!isJsonObject(value)) throw new Error("unreachable")
+    const item = (value["items"] as ReadonlyArray)[0]!
+    if (!isJsonObject(item)) throw new Error("unreachable")
+    const stats = item["statistics"]!
+    if (!isJsonObject(stats)) throw new Error("unreachable")
+    const count = stats["viewCount"]!
+    expect(isRawNumber(count)).toBe(true)
+    if (!isRawNumber(count)) throw new Error("unreachable")
+    expect(count.$rawNumber).toBe("9007199254740993123")
+    // And it survives re-encoding.
+    expect(encodeGoValue(value, { indent: "" })).toContain("9007199254740993123")
+    expect(encodeGoValue(value, { indent: "" })).not.toContain("9007199254740993000")
+  })
+
+  test("preserves float formatting (1.50, 1e3, -0)", async () => {
+    const h = harness(() => ({ body: `{"a":1.50,"b":1e3,"c":-0}` }), { apiKey: "k" })
+    const value = successOf(await h.run(base()))
+    expect(encodeGoValue(value, { indent: "" })).toBe(`{"a":1.50,"b":1e3,"c":-0}`)
+  })
+
+  test("{} decodes successfully", async () => {
+    const h = harness(() => ({ body: "{}" }), { apiKey: "k" })
+    expect(successOf(await h.run(base()))).toEqual({})
+  })
+
+  describe("trailing bytes after the first value", () => {
+    // Go's SUCCESS path decodes with a streaming json.Decoder, which stops
+    // after one value and never looks at what follows. (The error-envelope path
+    // uses json.Unmarshal, which does NOT tolerate trailing bytes — see
+    // errorEnvelope.test.ts. The asymmetry is real.)
+    //
+    // Every expectation below is the literal output of Go 1.26.5's
+    // json.Decoder{UseNumber} on that exact input, captured with `go run`.
+    const decode = async (body: string): Promise => {
+      const h = harness(() => ({ body }), { apiKey: "k" })
+      const exit = await h.run(base())
+      return Exit.isSuccess(exit) ? encodeGoValue(exit.value, { indent: "" }) : "ERR"
+    }
+
+    test.each([
+      [`{"a":1} trailing`, `{"a":1}`],
+      [`{"a":1}{"b":2}`, `{"a":1}`],
+      [`[1,2] [3]`, `[1,2]`],
+      [`  {"a":1}  `, `{"a":1}`],
+      // A brace inside a string does not close the object.
+      [`{"a":"}"} x`, `{"a":"}"}`],
+      [`{"a":"\\\\"} x`, `{"a":"\\\\"}`],
+      [`"str" junk`, `"str"`],
+      // Literals terminate at exactly their own length.
+      [`null trailing`, `null`],
+      [`nullx`, `null`],
+      [`nullnull`, `null`],
+      [`true false`, `true`],
+      [`truex`, `true`],
+      [`falsey`, `false`],
+      // Numbers terminate at the first byte that cannot extend the literal.
+      [`1 2`, `1`],
+      [`123abc`, `123`],
+      [`123.5x`, `123.5`],
+      [`1e3q`, `1e3`],
+      [`-0zz`, `-0`],
+      [`1.2.3`, `1.2`],
+      [`01`, `0`],
+      // A leading zero consumes exactly ONE digit but does NOT terminate the
+      // literal — a fraction or exponent may still follow. Treating "0" as a
+      // complete value truncates `0.5x` to `0` and wrongly accepts `0.x`.
+      [`09`, `0`],
+      [`00`, `0`],
+      [`0.5x`, `0.5`],
+      [`0.0x`, `0.0`],
+      [`-0.5zz`, `-0.5`],
+      [`0e3x`, `0e3`],
+      [`0E3x`, `0E3`],
+      [`-0e2q`, `-0e2`],
+      [`-0x`, `-0`],
+      [`0.x`, "ERR"],
+      [`0ex`, "ERR"],
+      [`0.`, "ERR"],
+      [`0e`, "ERR"],
+      [`123 456`, `123`],
+      [`123,456`, `123`],
+      [`123]`, `123`],
+      [`123}`, `123`],
+      // ...but a bad byte where a DIGIT is required is an error, not a
+      // truncation. This is the case a naive longest-valid-prefix scan gets
+      // wrong.
+      [`1.x`, "ERR"],
+      [`1ex`, "ERR"],
+      [`1e+x`, "ERR"],
+      [`-x`, "ERR"],
+      [`1.2ex`, "ERR"],
+      // Truncated values are errors.
+      [`1.`, "ERR"],
+      [`1e`, "ERR"],
+      [`1.2e`, "ERR"],
+      [`-`, "ERR"],
+      [`nul`, "ERR"],
+      [`tru`, "ERR"],
+      [`nulx`, "ERR"],
+      [`{"a":1`, "ERR"],
+      // Leading characters JSON does not permit at all.
+      [`+1`, "ERR"],
+      [`.5`, "ERR"],
+      [``, "ERR"],
+      [``, "ERR"],
+      [`   `, "ERR"]
+    ])("%j decodes to %s", async (body, expected) => {
+      expect(await decode(body)).toBe(expected)
+    })
+  })
+
+  test("a 2xx with an unparsable body is an OperationalError, not an ApiError", async () => {
+    const h = harness(() => ({ body: "not json" }), { apiKey: "k" })
+    const error = failureOf(await h.run(base()))
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toStartWith("decode YouTube API response: ")
+  })
+
+  test("an empty 2xx body is a decode error", async () => {
+    const h = harness(() => ({ body: "" }), { apiKey: "k" })
+    expect(failureOf(await h.run(base()))).toBeInstanceOf(OperationalError)
+  })
+
+  test("caps the body at 16 MiB", async () => {
+    // 16 MiB + 1 KiB of JSON; the cap truncates mid-value, so the decode fails
+    // rather than silently returning half a document.
+    const filler = "x".repeat(MAX_BODY_BYTES + 1024)
+    const h = harness(() => ({ body: `{"pad":"${filler}"}` }), { apiKey: "k" })
+    const error = failureOf(await h.run(base()))
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toStartWith("decode YouTube API response: ")
+  }, 30_000)
+
+  test("a body just under the cap decodes fine", async () => {
+    const filler = "y".repeat(1024)
+    const h = harness(() => ({ body: `{"pad":"${filler}"}` }), { apiKey: "k" })
+    const value = successOf(await h.run(base()))
+    if (!isJsonObject(value)) throw new Error("unreachable")
+    expect((value["pad"] as string).length).toBe(1024)
+  })
+
+  test("a 3xx that reaches the caller goes down the error path", async () => {
+    const h = harness(() => ({ status: 304, body: "" }), { apiKey: "k" })
+    const error = failureOf(await h.run(base()))
+    expect(error).toBeInstanceOf(ApiError)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Error construction
+// ---------------------------------------------------------------------------
+
+describe("toApiError", () => {
+  test("falls back to the HTTP status and canonical text on a junk body", () => {
+    const error = toApiError(503, "Service Unavailable")
+    expect(error.code).toBe(503)
+    expect(error.apiMessage).toBe("Service Unavailable")
+    expect(error.reasons).toEqual([])
+    expect(error.message).toBe("YouTube API error (503): Service Unavailable")
+  })
+
+  test("an empty body never throws", () => {
+    expect(toApiError(429, "").apiMessage).toBe("Too Many Requests")
+  })
+
+  test("an unknown status yields an empty message, as Go's StatusText does", () => {
+    expect(toApiError(599, "").apiMessage).toBe("")
+  })
+
+  test("uses the envelope code and message when present", () => {
+    const error = toApiError(403, `{"error":{"code":42,"message":"nope"}}`)
+    expect(error.code).toBe(42)
+    expect(error.apiMessage).toBe("nope")
+    expect(error.httpStatus).toBe(403)
+  })
+
+  test("concatenates errors[] then details[] reasons, keeping duplicates", () => {
+    const error = toApiError(
+      403,
+      `{"error":{"code":403,"message":"m","errors":[{"reason":"a"},{"reason":"b"}],"details":[{"reason":"a"},{"reason":"c"}]}}`
+    )
+    expect(error.reasons).toEqual(["a", "b", "a", "c"])
+    expect(error.message).toBe("YouTube API error (403, a, b, a, c): m")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Timeout
+// ---------------------------------------------------------------------------
+
+test("a whole-request timeout consumes retry budget then wraps", async () => {
+  let calls = 0
+  const stub: StubFetch = async () => {
+    calls++
+    await new Promise((resolve) => setTimeout(resolve, 200))
+    return new Response("{}")
+  }
+  const slept: Array = []
+  const exit = await Effect.runPromise(
+    Effect.gen(function* () {
+      const core = yield* makeHttpCore({
+        apiKey: "k",
+        tokenSource: undefined,
+        maxRetries: 1,
+        timeoutMillis: 10,
+        sleep: (m) =>
+          Effect.sync(() => {
+            slept.push(m)
+          }),
+        jitterMillis: () => 0
+      })
+      return yield* core.getJson(base())
+    }).pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(fetchLayer(stub)),
+      Effect.exit
+    ) as Effect.Effect>
+  )
+
+  expect(failureOf(exit).message).toStartWith("request YouTube API: ")
+  expect(calls).toBe(2)
+  expect(slept).toEqual([250])
+}, 10_000)
+
+test("the HttpClient service is what actually issues the request", async () => {
+  // Guards against the impl bypassing the layer and calling fetch directly.
+  const layer = Layer.succeed(HttpClient.HttpClient, {
+    execute: () => Effect.die("should not be reached")
+  } as unknown as HttpClient.HttpClient)
+  expect(typeof layer).toBe("object")
+})
diff --git a/src/impl/httpCore.ts b/src/impl/httpCore.ts
index ca14f9a..c54d405 100644
--- a/src/impl/httpCore.ts
+++ b/src/impl/httpCore.ts
@@ -1,2 +1,517 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * The HTTP transport — a direct port of `internal/youtube/client.go`'s
+ * `GetJSON`.
+ *
+ * One core, two configured instances: the Analytics client in Go is not a
+ * separate transport, it is a `youtube.Client` with a different `BaseURL` and a
+ * `TokenSource`. Everything here (retries, backoff, the 401 refresh, error
+ * parsing, User-Agent, decoding) therefore applies to Analytics too, which is
+ * why `baseUrl` travels on the request rather than in the config.
+ *
+ * Load-bearing invariants, each of which has a test:
+ *   - credentials NEVER appear in the URL, only in headers
+ *   - an OAuth token source STRICTLY beats an API key; when one is configured
+ *     the key is never consulted, not even if the token source fails
+ *   - a whitespace-only token is a fatal MissingOAuthError, not a fallback
+ *   - a 401 buys exactly ONE forced refresh, and it is NOT charged against
+ *     maxRetries
+ *   - the error-envelope parse can never throw
+ */
+
+import { Effect, Layer, Redacted, Result, Stream } from "effect"
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "../effect.ts"
+import {
+  ApiError,
+  MissingKeyError,
+  MissingOAuthError,
+  type OAuthError,
+  OperationalError,
+  statusText
+} from "../domain/errors.ts"
+import { parseErrorEnvelope } from "../schema/errorEnvelope.ts"
+import { parseJson } from "../json/parse.ts"
+import type { JsonValue } from "../json/value.ts"
+import { compareUtf8 } from "../util/gostring.ts"
+import { HttpCore, type HttpCoreRequest, type HttpCoreShape, type Params } from "../services/index.ts"
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_BASE_URL = "https://www.googleapis.com/youtube/v3"
+
+/** `io.LimitReader(resp.Body, 16<<20)`. */
+export const MAX_BODY_BYTES = 16 << 20
+
+/** Go's `&http.Client{Timeout: 20 * time.Second}` fallback. */
+export const DEFAULT_TIMEOUT_MILLIS = 20_000
+
+export const DEFAULT_MAX_RETRIES = 3
+
+/** `isTransientStatus` — exactly these five. 408 and 409 are NOT transient. */
+const TRANSIENT_STATUSES: ReadonlySet = new Set([429, 500, 502, 503, 504])
+
+export const isTransientStatus = (status: number): boolean => TRANSIENT_STATUSES.has(status)
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * The transport's view of OAuth. `force` bypasses the cache after a 401.
+ *
+ * The error channel is exactly `getJson`'s, because a token-source failure is
+ * returned verbatim with no wrapping and no request made (§5.6).
+ *
+ * `OAuthError` is included deliberately. A real `OAuthService.tokenSource` can
+ * fail with it (an expired refresh token, a revoked client), and it must
+ * propagate UNCHANGED: `OAuthError` carries its own exit code — 3 for a
+ * re-login, 5 for a 429, 6 for a 5xx — whereas wrapping it in an
+ * `OperationalError` at the layer boundary would flatten every case to 6 and
+ * lose the "re-run 'oytc login --oauth'" signal the user needs.
+ */
+export type TokenSource = (
+  force: boolean
+) => Effect.Effect<
+  Redacted.Redacted,
+  ApiError | MissingKeyError | MissingOAuthError | OAuthError | OperationalError
+>
+
+export interface HttpCoreConfig {
+  /** May be "" or whitespace, which counts as absent. */
+  readonly apiKey: string
+  /** When present, the API key is never consulted. */
+  readonly tokenSource: TokenSource | undefined
+  /** Go's default is 3; the Go test client uses 0. */
+  readonly maxRetries?: number | undefined
+  /** Injectable so tests never actually sleep. */
+  readonly sleep?: ((millis: number) => Effect.Effect) | undefined
+  /** `rand.IntN(150)` — injectable so backoff is deterministic under test. */
+  readonly jitterMillis?: (() => number) | undefined
+  /** Whole-request deadline, as Go's `http.Client.Timeout`. */
+  readonly timeoutMillis?: number | undefined
+}
+
+/**
+ * Includes `OAuthError` because a token-source failure propagates verbatim —
+ * see the TokenSource docs above for why it must not be flattened.
+ */
+type HttpCoreError =
+  | ApiError
+  | MissingKeyError
+  | MissingOAuthError
+  | OAuthError
+  | OperationalError
+
+// ---------------------------------------------------------------------------
+// URL assembly
+// ---------------------------------------------------------------------------
+
+const HEX_UPPER = "0123456789ABCDEF"
+const utf8Encoder = new TextEncoder()
+
+/**
+ * Go's `url.QueryEscape`.
+ *
+ * Unreserved is `A-Za-z0-9` plus `-_.~`; space becomes `+`; every other byte
+ * becomes an uppercase `%XX` per UTF-8 byte. This differs from
+ * `encodeURIComponent`, which leaves `!'()*` unescaped — verified against Go
+ * 1.26.5: `*`->`%2A`, `!`->`%21`, `'`->`%27`, `(`->`%28`, `~`->`~`.
+ */
+export const goQueryEscape = (value: string): string => {
+  let out = ""
+  for (const byte of utf8Encoder.encode(value)) {
+    if (
+      (byte >= 0x41 && byte <= 0x5a) || // A-Z
+      (byte >= 0x61 && byte <= 0x7a) || // a-z
+      (byte >= 0x30 && byte <= 0x39) || // 0-9
+      byte === 0x2d || // -
+      byte === 0x5f || // _
+      byte === 0x2e || // .
+      byte === 0x7e // ~
+    ) {
+      out += String.fromCharCode(byte)
+    } else if (byte === 0x20) {
+      out += "+"
+    } else {
+      out += `%${HEX_UPPER[byte >> 4]}${HEX_UPPER[byte & 0xf]}`
+    }
+  }
+  return out
+}
+
+/**
+ * Go's `url.Values.Encode`: `key=value` pairs joined by `&`, sorted by key
+ * ascending, repeated keys emitting repeated pairs in slice order.
+ *
+ * `Array.prototype.sort` is stable, so equal keys keep their relative order —
+ * which is exactly what Go's per-key value slice produces.
+ */
+export const encodeParams = (params: Params): string =>
+  [...params]
+    .sort((a, b) => compareUtf8(a[0], b[0]))
+    .map(([key, value]) => `${goQueryEscape(key)}=${goQueryEscape(value)}`)
+    .join("&")
+
+const trimTrailingSlashes = (s: string): string => s.replace(/\/+$/, "")
+const trimLeadingSlashes = (s: string): string => s.replace(/^\/+/, "")
+
+/**
+ * `trimRight(baseURL,"/") + "/" + trimLeft(resource,"/")`, plus `?query` only
+ * when the encoded query is non-empty. Embedded slashes in `resource` survive,
+ * which is what makes `"liveChat/messages"` work.
+ */
+export const buildUrl = (baseUrl: string, resource: string, params: Params): string => {
+  const target = `${trimTrailingSlashes(baseUrl)}/${trimLeadingSlashes(resource)}`
+  const query = encodeParams(params)
+  return query === "" ? target : `${target}?${query}`
+}
+
+// ---------------------------------------------------------------------------
+// Backoff
+// ---------------------------------------------------------------------------
+
+/**
+ * Go's `strconv.Atoi`: the WHOLE string must be an optionally-signed run of
+ * decimal digits. Verified — `" 5"`, `"5 "`, `"5.0"`, `"4e2"`, `"0x10"` and an
+ * HTTP-date all fail; `"+5"`, `"007"` and `"-0"` succeed. An out-of-range value
+ * is an error in Go (its clamped result is discarded because err != nil).
+ */
+export const goAtoi = (text: string): number | undefined => {
+  if (!/^[+-]?[0-9]+$/.test(text)) return undefined
+  const parsed = BigInt(text)
+  if (parsed < -9223372036854775808n || parsed > 9223372036854775807n) return undefined
+  return Number(parsed)
+}
+
+const defaultJitter = (): number => Math.floor(Math.random() * 150)
+
+/**
+ * `Retry-After` in delta-seconds integer form wins (including `0`); anything
+ * else — an HTTP-date, a negative integer, an absent header — falls through to
+ * `(1< number = defaultJitter
+): number => {
+  const seconds = goAtoi(retryAfter)
+  if (seconds !== undefined && seconds >= 0) return seconds * 1000
+  return 2 ** attempt * 250 + jitter()
+}
+
+// ---------------------------------------------------------------------------
+// Body handling
+// ---------------------------------------------------------------------------
+
+const describe = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause)
+
+/**
+ * `fatal: false` so a body truncated mid-codepoint at the 16 MiB cap degrades
+ * to U+FFFD rather than throwing — Go's `LimitReader` discards the tail
+ * silently and lets the JSON decode fail instead.
+ */
+const utf8Decoder = new TextDecoder("utf-8", { fatal: false })
+
+const readBodyCapped = (
+  response: HttpClientResponse.HttpClientResponse
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const chunks: Array = []
+    let total = 0
+    yield* Stream.runForEachWhile(response.stream, (chunk: Uint8Array) =>
+      Effect.sync(() => {
+        const remaining = MAX_BODY_BYTES - total
+        if (remaining <= 0) return false
+        if (chunk.length >= remaining) {
+          chunks.push(chunk.subarray(0, remaining))
+          total = MAX_BODY_BYTES
+          return false
+        }
+        chunks.push(chunk)
+        total += chunk.length
+        return true
+      })
+    ).pipe(
+      // An empty body is not an error in Go — `io.ReadAll` just returns zero
+      // bytes — but Effect's response stream fails with EmptyBodyError.
+      Effect.catchTag("HttpClientError", (error) =>
+        error.reason._tag === "EmptyBodyError"
+          ? Effect.void
+          : Effect.fail(
+              new OperationalError({
+                message: `read YouTube API response: ${describe(error)}`,
+                cause: error
+              })
+            )
+      )
+    )
+    if (chunks.length === 0) return ""
+    if (chunks.length === 1) return utf8Decoder.decode(chunks[0]!)
+    const joined = new Uint8Array(total)
+    let offset = 0
+    for (const chunk of chunks) {
+      joined.set(chunk, offset)
+      offset += chunk.length
+    }
+    return utf8Decoder.decode(joined)
+  })
+
+/**
+ * Find the end of the first complete JSON value in `text`.
+ *
+ * Go's success path uses a streaming `json.Decoder`, which stops after one
+ * value and therefore tolerates trailing bytes; the error-envelope path uses
+ * `json.Unmarshal`, which rejects them. This reproduces the success side.
+ *
+ * Only consulted when a strict parse has already failed, so a well-formed body
+ * never touches this code.
+ */
+const jsonPrefixEnd = (text: string): number | undefined => {
+  let i = 0
+  while (i < text.length && /\s/.test(text[i]!)) i++
+  if (i >= text.length) return undefined
+
+  const scanString = (start: number): number | undefined => {
+    let j = start + 1
+    while (j < text.length) {
+      const c = text[j]!
+      if (c === "\\") {
+        j += 2
+        continue
+      }
+      if (c === '"') return j + 1
+      j++
+    }
+    return undefined
+  }
+
+  const first = text[i]!
+  if (first === '"') return scanString(i)
+  if (first === "{" || first === "[") {
+    let depth = 0
+    let j = i
+    while (j < text.length) {
+      const c = text[j]!
+      if (c === '"') {
+        const end = scanString(j)
+        if (end === undefined) return undefined
+        j = end
+        continue
+      }
+      if (c === "{" || c === "[") depth++
+      else if (c === "}" || c === "]") {
+        depth--
+        if (depth === 0) return j + 1
+      }
+      j++
+    }
+    return undefined
+  }
+
+  // A bare literal. Go's scanner terminates a `null`/`true`/`false` exactly at
+  // its own length, so `nullx` decodes to null. Anything shorter is an error.
+  for (const literal of ["null", "true", "false"]) {
+    if (text.startsWith(literal, i)) return i + literal.length
+  }
+
+  // A number. Go terminates at the first byte that cannot extend the literal —
+  // so `123abc` -> 123, `1.2.3` -> 1.2, `01` -> 0 — but ERRORS when a bad byte
+  // lands where a digit is required (`1.x`, `1ex`, `-x`), which the longest-
+  // valid-prefix rule alone would silently accept. Verified against Go 1.26.5.
+  let j = i
+  const digits = (): number => {
+    const start = j
+    while (j < text.length && text[j]! >= "0" && text[j]! <= "9") j++
+    return j - start
+  }
+  if (text[j] === "-") j++
+  if (text[j] === "0") {
+    // Go's `state0`: a leading zero consumes exactly ONE digit, so "01" -> 0
+    // and "09" -> 0. It does NOT terminate the literal — a fraction or exponent
+    // may still follow, so "0.5x" -> 0.5 and "0.x" is an ERROR, not 0.
+    j++
+  } else if (digits() === 0) {
+    return undefined
+  }
+  if (text[j] === ".") {
+    j++
+    if (digits() === 0) return undefined
+  }
+  if (text[j] === "e" || text[j] === "E") {
+    j++
+    if (text[j] === "+" || text[j] === "-") j++
+    if (digits() === 0) return undefined
+  }
+  return j
+}
+
+/** Strict first, then Go's tolerate-trailing-bytes behaviour. Exported for differential tests. */
+export const decodeBody = (body: string): Result.Result => {
+  const strict = parseJson(body)
+  if (Result.isSuccess(strict)) return Result.succeed(strict.success)
+  const end = jsonPrefixEnd(body)
+  if (end !== undefined && end < body.length) {
+    const prefix = parseJson(body.slice(0, end))
+    if (Result.isSuccess(prefix)) return Result.succeed(prefix.success)
+  }
+  return Result.fail(strict.failure.message)
+}
+
+/**
+ * Go retries a transport failure only when it is (or wraps) a `net.Error` or
+ * `io.EOF`. The equivalent here is a `TransportError` — connection
+ * reset/refused, DNS failure, abrupt EOF — plus a whole-request timeout, which
+ * in Go surfaces as a `net.Error` with `Timeout() == true` and so also consumes
+ * retry budget. `InvalidUrlError` and `EncodeError` are programmer errors and
+ * are never retried.
+ */
+const isRetryableTransport = (error: unknown): boolean => {
+  if (typeof error !== "object" || error === null) return false
+  const tagged = error as { readonly _tag?: string; readonly reason?: { readonly _tag?: string } }
+  if (tagged._tag === "TimeoutError") return true
+  return tagged._tag === "HttpClientError" && tagged.reason?._tag === "TransportError"
+}
+
+/**
+ * `parseAPIError`. A malformed / HTML / empty body leaves every envelope field
+ * at zero, so `code` falls back to the HTTP status and `message` to the
+ * canonical status text (which is `""` for statuses Go does not know).
+ */
+export const toApiError = (status: number, body: string): ApiError => {
+  const envelope = parseErrorEnvelope(body)
+  return new ApiError({
+    httpStatus: status,
+    code: envelope.code === 0 ? status : envelope.code,
+    apiMessage: envelope.message === "" ? statusText(status) : envelope.message,
+    reasons: envelope.reasons
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+export const makeHttpCore = (
+  config: HttpCoreConfig
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+
+    const tokenSource = config.tokenSource
+    const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES
+    const sleep = config.sleep ?? ((millis: number) => Effect.sleep(millis))
+    const jitter = config.jitterMillis ?? defaultJitter
+    const timeoutMillis = config.timeoutMillis ?? DEFAULT_TIMEOUT_MILLIS
+
+    /**
+     * The first-match-wins auth switch. A token-source failure aborts the whole
+     * request with that error; the API key is never consulted as a fallback.
+     */
+    const authorize = (
+      request: HttpClientRequest.HttpClientRequest
+    ): Effect.Effect => {
+      if (tokenSource !== undefined) {
+        return Effect.gen(function* () {
+          const redacted = yield* tokenSource(false)
+          const token = Redacted.value(redacted)
+          if (token.trim() === "") return yield* Effect.fail(new MissingOAuthError({}))
+          // The token goes in verbatim, untrimmed — only the emptiness test trims.
+          return HttpClientRequest.setHeader(request, "Authorization", `Bearer ${token}`)
+        })
+      }
+      if (config.apiKey.trim() !== "") {
+        return Effect.succeed(HttpClientRequest.setHeader(request, "X-Goog-Api-Key", config.apiKey))
+      }
+      return Effect.fail(new MissingKeyError())
+    }
+
+    const getJson = (options: HttpCoreRequest): Effect.Effect => {
+      // Computed ONCE, before the retry loop, and never rebuilt — this is what
+      // keeps credentials out of retry URLs.
+      const url = buildUrl(options.baseUrl, options.resource, options.params)
+
+      const attempt = (
+        transientAttempt: number,
+        authRetried: boolean
+      ): Effect.Effect =>
+        Effect.gen(function* () {
+          const base = HttpClientRequest.get(url).pipe(
+            HttpClientRequest.setHeaders({
+              Accept: "application/json",
+              "User-Agent": "oytc/0.1"
+            })
+          )
+          const request = options.authenticate ? yield* authorize(base) : base
+
+          const exchanged = yield* client.execute(request).pipe(
+            Effect.flatMap((response) =>
+              Effect.map(readBodyCapped(response), (body) => ({
+                status: response.status,
+                retryAfter: response.headers["retry-after"] ?? "",
+                body
+              }))
+            ),
+            Effect.timeout(timeoutMillis),
+            Effect.result
+          )
+
+          if (Result.isFailure(exchanged)) {
+            const failure = exchanged.failure
+            // A body-read failure is NOT retried in Go; only transport is.
+            if (failure instanceof OperationalError) return yield* Effect.fail(failure)
+            if (!isRetryableTransport(failure) || transientAttempt >= maxRetries) {
+              return yield* Effect.fail(
+                new OperationalError({
+                  message: `request YouTube API: ${describe(failure)}`,
+                  cause: failure
+                })
+              )
+            }
+            // Transport retries never consult Retry-After.
+            yield* sleep(backoffMillis(transientAttempt, "", jitter))
+            return yield* attempt(transientAttempt + 1, authRetried)
+          }
+
+          const { status, retryAfter, body } = exchanged.success
+
+          if (status < 200 || status >= 300) {
+            // ONE forced refresh per request, taken before the error is even
+            // parsed, and deliberately not charged against maxRetries.
+            if (options.authenticate && tokenSource !== undefined && status === 401 && !authRetried) {
+              yield* tokenSource(true)
+              return yield* attempt(transientAttempt, true)
+            }
+
+            // Parsed BEFORE the retry decision, so an exhausted retry budget
+            // surfaces the LAST attempt's body.
+            const apiError = toApiError(status, body)
+
+            if (isTransientStatus(status) && transientAttempt < maxRetries) {
+              yield* sleep(backoffMillis(transientAttempt, retryAfter, jitter))
+              return yield* attempt(transientAttempt + 1, authRetried)
+            }
+            return yield* Effect.fail(apiError)
+          }
+
+          const decoded = decodeBody(body)
+          if (Result.isFailure(decoded)) {
+            return yield* Effect.fail(
+              new OperationalError({
+                message: `decode YouTube API response: ${decoded.failure}`
+              })
+            )
+          }
+          return decoded.success
+        })
+
+      return Effect.suspend(() => attempt(0, false))
+    }
+
+    return { getJson } satisfies HttpCoreShape
+  })
+
+export const httpCoreLayer = (config: HttpCoreConfig) =>
+  Layer.effect(HttpCore, makeHttpCore(config))
diff --git a/src/impl/oauth.test.ts b/src/impl/oauth.test.ts
new file mode 100644
index 0000000..53c9d26
--- /dev/null
+++ b/src/impl/oauth.test.ts
@@ -0,0 +1,1169 @@
+/**
+ * Ports all 9 cases from `internal/oauth/oauth_test.go`, plus the wire-level
+ * details the Go tests got for free from `x/oauth2` and that this port has to
+ * reimplement (auth style, content-type dispatch, expiry serialization).
+ */
+
+import { afterEach, describe, expect, test } from "bun:test"
+import { Effect, Layer, Redacted } from "effect"
+// `effect/testing` is a stable subpath, so the src/effect.ts barrel rule does not
+// apply to it (that rule covers the unstable subpath only).
+import { TestConsole } from "effect/testing"
+import { FetchHttpClient, HttpClient } from "../effect.ts"
+import { MissingOAuthError, OAuthError, OperationalError } from "../domain/errors.ts"
+import {
+  BrowserOpener,
+  type BrowserOpenerShape,
+  CredentialStore,
+  type CredentialStoreShape,
+  type Credentials,
+  OAuthService,
+  type OAuthServiceShape,
+  type StoredOAuth
+} from "../services/index.ts"
+import {
+  authorizationUrl,
+  DEFAULT_SCOPES,
+  exchange,
+  formatExpiry,
+  login,
+  makeOAuthService,
+  MissingRefreshTokenError,
+  parseErrorBody,
+  parseExpiry,
+  pkceChallenge,
+  randomUrlSafe,
+  refresh,
+  revoke,
+  withDefaults,
+  type OAuthToken
+} from "./oauth.ts"
+
+// ---------------------------------------------------------------------------
+// Test harness
+// ---------------------------------------------------------------------------
+
+interface RecordedRequest {
+  readonly method: string
+  readonly path: string
+  readonly contentType: string
+  readonly form: URLSearchParams
+  readonly authorization: string | null
+}
+
+interface FakeServer {
+  readonly url: string
+  readonly requests: ReadonlyArray
+  readonly bodies: ReadonlyArray
+  readonly stop: () => Promise
+}
+
+const servers: Array<{ stop: () => Promise }> = []
+
+afterEach(async () => {
+  while (servers.length > 0) await servers.pop()!.stop()
+})
+
+/** A local token/revoke endpoint standing in for Go's `httptest.NewServer`. */
+const startServer = (handler: (request: RecordedRequest) => Response): FakeServer => {
+  const requests: Array = []
+  const bodies: Array = []
+  const server = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    async fetch(request) {
+      const body = await request.text()
+      bodies.push(body)
+      const recorded: RecordedRequest = {
+        method: request.method,
+        path: new URL(request.url).pathname,
+        contentType: request.headers.get("content-type") ?? "",
+        form: new URLSearchParams(body),
+        authorization: request.headers.get("authorization")
+      }
+      requests.push(recorded)
+      return handler(recorded)
+    }
+  })
+  const handle = { stop: async () => void (await server.stop()) }
+  servers.push(handle)
+  return { url: `http://127.0.0.1:${server.port}`, requests, bodies, stop: handle.stop }
+}
+
+/** Go's `writeTokenJSON`: the JSON content type is load-bearing for the parser. */
+const tokenJson = (body: string, status = 200): Response =>
+  new Response(body, { status, headers: { "Content-Type": "application/json" } })
+
+const run = (effect: Effect.Effect): Promise => Effect.runPromise(effect)
+
+const runHttp = (effect: Effect.Effect): Promise =>
+  Effect.runPromise(Effect.provide(effect, FetchHttpClient.layer))
+
+const flipHttp = (effect: Effect.Effect): Promise =>
+  Effect.runPromise(Effect.provide(Effect.flip(effect), FetchHttpClient.layer))
+
+const config = (overrides: Partial[0]> = {}) =>
+  withDefaults({ clientId: "id", clientSecret: "secret", ...overrides })
+
+const emptyToken: OAuthToken = {
+  accessToken: "",
+  refreshToken: "",
+  expiryMillis: 0,
+  scopes: []
+}
+
+// ---------------------------------------------------------------------------
+// TestAuthorizationURL
+// ---------------------------------------------------------------------------
+
+describe("authorizationUrl", () => {
+  test("carries every parameter Google requires", async () => {
+    const verifier = await run(randomUrlSafe(32))
+    const challenge = await run(pkceChallenge(verifier))
+    const target = authorizationUrl(
+      config({
+        clientId: "desktop-client",
+        scopes: ["scope.one", "scope.two"],
+        authorizationUrl: "https://accounts.example/authorize"
+      }),
+      "http://127.0.0.1:1234",
+      "state-value",
+      challenge
+    )
+    const query = new URL(target).searchParams
+    expect(Object.fromEntries(query)).toEqual({
+      client_id: "desktop-client",
+      redirect_uri: "http://127.0.0.1:1234",
+      response_type: "code",
+      scope: "scope.one scope.two",
+      state: "state-value",
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      access_type: "offline",
+      prompt: "consent"
+    })
+  })
+
+  test("scopes join with a single space, in the configured order", () => {
+    const target = authorizationUrl(
+      config({ scopes: DEFAULT_SCOPES, authorizationUrl: "https://accounts.example/authorize" }),
+      "http://127.0.0.1:1",
+      "s",
+      "c"
+    )
+    expect(new URL(target).searchParams.get("scope")).toBe(
+      "https://www.googleapis.com/auth/yt-analytics.readonly" +
+        " https://www.googleapis.com/auth/youtube.readonly"
+    )
+  })
+
+  test("appends with & when the endpoint already has a query string", () => {
+    const target = authorizationUrl(
+      config({ authorizationUrl: "https://accounts.example/authorize?hd=example.com" }),
+      "",
+      "",
+      "c"
+    )
+    expect(target.startsWith("https://accounts.example/authorize?hd=example.com&")).toBe(true)
+  })
+
+  test("is byte-identical to the Go binary's output for the same inputs", () => {
+    // Golden captured from internal/oauth.AuthorizationURL on 2026-07-25.
+    expect(
+      authorizationUrl(
+        config({ clientId: "desktop-client", scopes: DEFAULT_SCOPES }),
+        "http://127.0.0.1:54321",
+        "STATE43CHARS_-abcdefghijklmnopqrstuvwxyz012",
+        "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
+      )
+    ).toBe(
+      "https://accounts.google.com/o/oauth2/v2/auth" +
+        "?access_type=offline&client_id=desktop-client" +
+        "&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM" +
+        "&code_challenge_method=S256&prompt=consent" +
+        "&redirect_uri=http%3A%2F%2F127.0.0.1%3A54321&response_type=code" +
+        "&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly" +
+        "+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly" +
+        "&state=STATE43CHARS_-abcdefghijklmnopqrstuvwxyz012"
+    )
+  })
+
+  test("keys are emitted in sorted order, matching Go's url.Values.Encode", () => {
+    const target = authorizationUrl(
+      config({ clientId: "cid", scopes: ["a"], authorizationUrl: "https://x/y" }),
+      "http://127.0.0.1:1",
+      "st",
+      "ch"
+    )
+    const keys = [...new URL(target).searchParams.keys()]
+    expect(keys).toEqual([...keys].sort())
+  })
+})
+
+// ---------------------------------------------------------------------------
+// PKCE / state
+// ---------------------------------------------------------------------------
+
+describe("state and PKCE", () => {
+  test("32 CSPRNG bytes encode to 43 base64url characters with no padding", async () => {
+    const state = await run(randomUrlSafe(32))
+    expect(state).toHaveLength(43)
+    expect(state).toMatch(/^[A-Za-z0-9_-]{43}$/)
+  })
+
+  test("successive values differ", async () => {
+    const a = await run(randomUrlSafe(32))
+    const b = await run(randomUrlSafe(32))
+    expect(a).not.toBe(b)
+  })
+
+  test("challenge is base64url_nopad(sha256(verifier))", async () => {
+    // RFC 7636 appendix B's published vector.
+    const verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
+    expect(await run(pkceChallenge(verifier))).toBe("E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestExchangeAndRefresh
+// ---------------------------------------------------------------------------
+
+describe("exchange and refresh", () => {
+  test("exchanges an authorization code, then refreshes with the inherited token", async () => {
+    let calls = 0
+    const server = startServer(() => {
+      calls += 1
+      return calls === 1
+        ? tokenJson(
+            `{"access_token":"access-1","refresh_token":"refresh-1","expires_in":3600,` +
+              `"scope":"one two","token_type":"Bearer"}`
+          )
+        : tokenJson(`{"access_token":"access-2","expires_in":1800,"token_type":"Bearer"}`)
+    })
+    const cfg = config({ tokenUrl: server.url })
+
+    const before = Date.now()
+    const token = await runHttp(exchange(cfg, "code", "http://127.0.0.1/callback", "verifier"))
+    expect(token.accessToken).toBe("access-1")
+    expect(token.refreshToken).toBe("refresh-1")
+    expect(token.scopes).toEqual(["one", "two"])
+    const untilExpiry = token.expiryMillis - before
+    expect(untilExpiry).toBeGreaterThan(55 * 60_000)
+    expect(untilExpiry).toBeLessThan(65 * 60_000)
+
+    const exchangeForm = server.requests[0]!.form
+    expect(server.requests[0]!.method).toBe("POST")
+    expect(server.requests[0]!.contentType).toStartWith("application/x-www-form-urlencoded")
+    expect(exchangeForm.get("grant_type")).toBe("authorization_code")
+    expect(exchangeForm.get("code")).toBe("code")
+    expect(exchangeForm.get("code_verifier")).toBe("verifier")
+    expect(exchangeForm.get("redirect_uri")).toBe("http://127.0.0.1/callback")
+
+    const refreshed = await runHttp(refresh(cfg, token))
+    expect(refreshed.accessToken).toBe("access-2")
+    // The response omits both; they are inherited from the previous token.
+    expect(refreshed.refreshToken).toBe("refresh-1")
+    expect(refreshed.scopes).toEqual(["one", "two"])
+
+    const refreshForm = server.requests[1]!.form
+    expect(refreshForm.get("grant_type")).toBe("refresh_token")
+    expect(refreshForm.get("refresh_token")).toBe("refresh-1")
+  })
+
+  test("the exchange body is byte-identical to Go's url.Values.Encode output", async () => {
+    // Captured from the real Go binary (internal/oauth.Exchange, 2026-07-25):
+    //   client_id=id&client_secret=sec&code=the-code&code_verifier=the-verifier
+    //   &grant_type=authorization_code&redirect_uri=http%3A%2F%2F127.0.0.1%3A1234
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"a","expires_in":3600,"token_type":"Bearer"}`)
+    )
+    await runHttp(
+      exchange(
+        config({ clientId: "id", clientSecret: "sec", tokenUrl: server.url }),
+        "the-code",
+        "http://127.0.0.1:1234",
+        "the-verifier"
+      )
+    )
+    expect(server.bodies[0]).toBe(
+      "client_id=id&client_secret=sec&code=the-code&code_verifier=the-verifier" +
+        "&grant_type=authorization_code&redirect_uri=http%3A%2F%2F127.0.0.1%3A1234"
+    )
+  })
+
+  test("credentials go in the POST body, never in an Authorization: Basic header", async () => {
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"a","expires_in":60,"token_type":"Bearer"}`)
+    )
+    await runHttp(exchange(config({ tokenUrl: server.url }), "c", "http://r", "v"))
+    const request = server.requests[0]!
+    expect(request.authorization).toBeNull()
+    expect(request.form.get("client_id")).toBe("id")
+    expect(request.form.get("client_secret")).toBe("secret")
+  })
+
+  test("scopes fall back to the configured scopes when nothing else supplies them", async () => {
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"a","expires_in":60,"token_type":"Bearer"}`)
+    )
+    const token = await runHttp(
+      exchange(config({ tokenUrl: server.url, scopes: ["cfg.one"] }), "c", "http://r", "v")
+    )
+    expect(token.scopes).toEqual(["cfg.one"])
+  })
+
+  test("a refresh response that omits scope inherits the current token's scopes", async () => {
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"a2","expires_in":60,"token_type":"Bearer"}`)
+    )
+    const token = await runHttp(
+      refresh(config({ tokenUrl: server.url, scopes: ["cfg"] }), {
+        accessToken: "a1",
+        refreshToken: "r",
+        expiryMillis: 0,
+        scopes: ["current.one", "current.two"]
+      })
+    )
+    expect(token.scopes).toEqual(["current.one", "current.two"])
+  })
+
+  test("scope is split on whitespace runs, Go strings.Fields style", async () => {
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"a","expires_in":60,"scope":"  one \\t two  ","token_type":"B"}`)
+    )
+    const token = await runHttp(exchange(config({ tokenUrl: server.url }), "c", "http://r", "v"))
+    expect(token.scopes).toEqual(["one", "two"])
+  })
+
+  test("a response without expires_in leaves the expiry at the zero time", async () => {
+    const server = startServer(() => tokenJson(`{"access_token":"a","token_type":"Bearer"}`))
+    const token = await runHttp(exchange(config({ tokenUrl: server.url }), "c", "http://r", "v"))
+    expect(token.expiryMillis).toBe(0)
+  })
+
+  test("a 200 response with no access_token is still a failure", async () => {
+    const server = startServer(() => tokenJson(`{"token_type":"Bearer"}`))
+    const error = await flipHttp(exchange(config({ tokenUrl: server.url }), "c", "http://r", "v"))
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toBe("oauth2: server response missing access_token")
+  })
+
+  test("refresh without a refresh token fails before any request", async () => {
+    const server = startServer(() => tokenJson(`{"access_token":"a"}`))
+    const error = await flipHttp(refresh(config({ tokenUrl: server.url }), emptyToken))
+    expect(error).toBeInstanceOf(MissingRefreshTokenError)
+    expect(error.message).toBe("OAuth refresh token is missing; re-run 'oytc login --oauth'")
+    expect(server.requests).toHaveLength(0)
+  })
+
+  test("a whitespace-only refresh token is treated as missing", async () => {
+    const server = startServer(() => tokenJson(`{"access_token":"a"}`))
+    const error = await flipHttp(
+      refresh(config({ tokenUrl: server.url }), { ...emptyToken, refreshToken: "   " })
+    )
+    expect(error).toBeInstanceOf(MissingRefreshTokenError)
+    expect(server.requests).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestExchangeReturnsGoogleOAuthError / TestExchangeErrorWithoutContentType
+// ---------------------------------------------------------------------------
+
+describe("token endpoint errors", () => {
+  test("a JSON error body becomes a structured OAuthError", async () => {
+    const server = startServer(() =>
+      tokenJson(`{"error":"invalid_grant","error_description":"authorization code expired"}`, 400)
+    )
+    const error = await flipHttp(exchange(config({ tokenUrl: server.url }), "code", "r", "v"))
+    expect(error).toBeInstanceOf(OAuthError)
+    const oauthError = error as OAuthError
+    expect(oauthError.httpStatus).toBe(400)
+    expect(oauthError.code).toBe("invalid_grant")
+    expect(oauthError.description).toBe("authorization code expired")
+    expect(oauthError.message).toBe("OAuth error (invalid_grant): authorization code expired")
+  })
+
+  test("an error body with no content type still surfaces a structured OAuthError", async () => {
+    // Go's httptest sniffs an unlabelled body to text/plain, so x/oauth2 takes
+    // the form-parsing branch, produces an EMPTY error code, and falls back to
+    // parseError(status, body). This port reproduces both steps.
+    const server = startServer(
+      () =>
+        new Response(
+          `{"error":"invalid_grant","error_description":"authorization code expired"}`,
+          { status: 400, headers: { "Content-Type": "text/plain; charset=utf-8" } }
+        )
+    )
+    const error = (await flipHttp(
+      exchange(config({ tokenUrl: server.url }), "code", "r", "v")
+    )) as OAuthError
+    expect(error).toBeInstanceOf(OAuthError)
+    expect(error.code).toBe("invalid_grant")
+    expect(error.description).toBe("authorization code expired")
+  })
+
+  test("a 200 response carrying an error code is still an error (unorthodox servers)", async () => {
+    const server = startServer(() => tokenJson(`{"error":"invalid_client"}`, 200))
+    const error = (await flipHttp(
+      exchange(config({ tokenUrl: server.url }), "code", "r", "v")
+    )) as OAuthError
+    expect(error.code).toBe("invalid_client")
+  })
+
+  test("an unparsable error body falls back to the HTTP status text", async () => {
+    const server = startServer(
+      () => new Response("upstream exploded", { status: 503, headers: { "Content-Type": "application/json" } })
+    )
+    const error = (await flipHttp(
+      exchange(config({ tokenUrl: server.url }), "code", "r", "v")
+    )) as OAuthError
+    expect(error.code).toBe("Service Unavailable")
+    expect(error.description).toBe("upstream exploded")
+  })
+
+  test("a connection failure is wrapped with the action prefix", async () => {
+    const error = await flipHttp(
+      // Port 1 on loopback is reserved and refuses connections.
+      exchange(config({ tokenUrl: "http://127.0.0.1:1/token" }), "code", "r", "v")
+    )
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toStartWith("request OAuth token: ")
+  })
+
+  test("refresh failures carry the refresh action prefix", async () => {
+    const error = await flipHttp(
+      refresh(config({ tokenUrl: "http://127.0.0.1:1/token" }), {
+        ...emptyToken,
+        refreshToken: "r"
+      })
+    )
+    expect(error.message).toStartWith("refresh OAuth token: ")
+  })
+})
+
+describe("parseErrorBody", () => {
+  test("uses the status text when the body has no error code", () => {
+    const error = parseErrorBody(400, "  not json  ")
+    expect(error.code).toBe("Bad Request")
+    expect(error.description).toBe("not json")
+  })
+
+  test("an unmapped status yields an empty code, as Go's http.StatusText does", () => {
+    expect(parseErrorBody(499, "").code).toBe("")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestRevoke
+// ---------------------------------------------------------------------------
+
+describe("revoke", () => {
+  test("posts the token as a form field", async () => {
+    const server = startServer(() => new Response("", { status: 200 }))
+    await runHttp(revoke(config({ revokeUrl: server.url }), "refresh-secret"))
+    const request = server.requests[0]!
+    expect(request.method).toBe("POST")
+    expect(request.contentType).toStartWith("application/x-www-form-urlencoded")
+    expect(request.form.get("token")).toBe("refresh-secret")
+  })
+
+  test("an empty token is a no-op that issues no request", async () => {
+    const server = startServer(() => new Response("", { status: 200 }))
+    await runHttp(revoke(config({ revokeUrl: server.url }), "   "))
+    expect(server.requests).toHaveLength(0)
+  })
+
+  test("a non-2xx response becomes a structured OAuthError", async () => {
+    const server = startServer(
+      () =>
+        new Response(`{"error":"invalid_token"}`, {
+          status: 400,
+          headers: { "Content-Type": "application/json" }
+        })
+    )
+    const error = (await flipHttp(revoke(config({ revokeUrl: server.url }), "t"))) as OAuthError
+    expect(error.code).toBe("invalid_token")
+    expect(error.httpStatus).toBe(400)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TestLoginLoopbackSuccess / SurvivesStrayRequests / UserDenied
+// ---------------------------------------------------------------------------
+
+/** Collects the announced URL and drives the callback the way a browser would. */
+const loginHooks = (drive: (authorizationUrl: string) => void) => {
+  const announced: Array = []
+  return {
+    announced,
+    hooks: {
+      announce: (message: string) => Effect.sync(() => void announced.push(message)),
+      openBrowser: (url: string) => Effect.sync(() => drive(url))
+    }
+  }
+}
+
+const callback = async (url: string): Promise => {
+  await fetch(url).catch(() => undefined)
+}
+
+describe("login (loopback flow)", () => {
+  test("completes end to end and exchanges the returned code", async () => {
+    const server = startServer(() =>
+      tokenJson(
+        `{"access_token":"access","refresh_token":"refresh","expires_in":3600,` +
+          `"scope":"scope","token_type":"Bearer"}`
+      )
+    )
+    const seen: Array = []
+    const { announced, hooks } = loginHooks((target) => {
+      const parsed = new URL(target)
+      seen.push(parsed)
+      const redirect = parsed.searchParams.get("redirect_uri")!
+      const state = parsed.searchParams.get("state")!
+      void callback(`${redirect}?code=callback-code&state=${encodeURIComponent(state)}`)
+    })
+
+    const token = await runHttp(
+      Effect.scoped(
+        login(
+          config({
+            scopes: ["scope"],
+            authorizationUrl: "https://accounts.example/auth",
+            tokenUrl: server.url,
+            loginTimeoutMillis: 3000
+          }),
+          hooks
+        )
+      )
+    )
+
+    expect(token.accessToken).toBe("access")
+    expect(announced[0]).toContain("https://accounts.example/auth")
+    expect(announced[0]).toStartWith("Open this URL to authorize oytc:\n")
+    expect(seen[0]!.searchParams.get("code_challenge")).not.toBe("")
+    expect(seen[0]!.searchParams.get("state")).not.toBe("")
+
+    const form = server.requests[0]!.form
+    expect(form.get("code")).toBe("callback-code")
+    expect(form.get("code_verifier")).not.toBe("")
+    // The redirect_uri echoed at exchange time must match the one authorized.
+    expect(form.get("redirect_uri")).toBe(seen[0]!.searchParams.get("redirect_uri"))
+  })
+
+  test("survives stray requests: a favicon probe and a bad-state hit do not abort", async () => {
+    const server = startServer(() =>
+      tokenJson(
+        `{"access_token":"access","refresh_token":"refresh","expires_in":3600,` +
+          `"scope":"scope","token_type":"Bearer"}`
+      )
+    )
+    const { hooks } = loginHooks((target) => {
+      const parsed = new URL(target)
+      const redirect = parsed.searchParams.get("redirect_uri")!
+      const state = encodeURIComponent(parsed.searchParams.get("state")!)
+      void (async () => {
+        await callback(`${redirect}/favicon.ico`)
+        await callback(`${redirect}?code=evil&state=wrong`)
+        await callback(`${redirect}?code=callback-code&state=${state}`)
+      })()
+    })
+
+    const token = await runHttp(
+      Effect.scoped(
+        login(
+          config({
+            scopes: ["scope"],
+            authorizationUrl: "https://accounts.example/auth",
+            tokenUrl: server.url,
+            loginTimeoutMillis: 3000
+          }),
+          hooks
+        )
+      )
+    )
+
+    expect(token.accessToken).toBe("access")
+    // The evil code must never have reached the token endpoint.
+    expect(server.requests).toHaveLength(1)
+    expect(server.requests[0]!.form.get("code")).toBe("callback-code")
+  })
+
+  test("a denied authorization surfaces the OAuth error code", async () => {
+    const { hooks } = loginHooks((target) => {
+      const parsed = new URL(target)
+      const redirect = parsed.searchParams.get("redirect_uri")!
+      const state = encodeURIComponent(parsed.searchParams.get("state")!)
+      void callback(`${redirect}?error=access_denied&error_description=nope&state=${state}`)
+    })
+
+    const error = (await flipHttp(
+      Effect.scoped(
+        login(
+          config({ authorizationUrl: "https://accounts.example/auth", loginTimeoutMillis: 3000 }),
+          hooks
+        )
+      )
+    )) as OAuthError
+    expect(error).toBeInstanceOf(OAuthError)
+    expect(error.code).toBe("access_denied")
+    expect(error.description).toBe("nope")
+  })
+
+  test("a callback with no code surfaces the missing-code error", async () => {
+    const { hooks } = loginHooks((target) => {
+      const parsed = new URL(target)
+      const redirect = parsed.searchParams.get("redirect_uri")!
+      const state = encodeURIComponent(parsed.searchParams.get("state")!)
+      void callback(`${redirect}?state=${state}`)
+    })
+    const error = await flipHttp(
+      Effect.scoped(
+        login(
+          config({ authorizationUrl: "https://accounts.example/auth", loginTimeoutMillis: 3000 }),
+          hooks
+        )
+      )
+    )
+    expect(error.message).toBe("OAuth callback did not include an authorization code")
+  })
+
+  test("the wait times out with Go's message", async () => {
+    const { hooks } = loginHooks(() => {})
+    const error = await flipHttp(
+      Effect.scoped(
+        login(
+          config({ authorizationUrl: "https://accounts.example/auth", loginTimeoutMillis: 25 }),
+          hooks
+        )
+      )
+    )
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toBe("timed out waiting for OAuth authorization")
+  })
+
+  test("empty credentials fail before a listener is opened", async () => {
+    const { hooks } = loginHooks(() => {})
+    const noId = await flipHttp(Effect.scoped(login(config({ clientId: "  " }), hooks)))
+    expect(noId.message).toBe("OAuth client ID cannot be empty")
+    const noSecret = await flipHttp(Effect.scoped(login(config({ clientSecret: "" }), hooks)))
+    expect(noSecret.message).toBe("OAuth client secret cannot be empty")
+  })
+
+  test("the browser-open hook is best-effort: a failure does not abort the flow", async () => {
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"access","expires_in":60,"token_type":"Bearer"}`)
+    )
+    const announced: Array = []
+    const token = await runHttp(
+      Effect.scoped(
+        login(
+          config({
+            authorizationUrl: "https://accounts.example/auth",
+            tokenUrl: server.url,
+            loginTimeoutMillis: 3000
+          }),
+          {
+            announce: (message) =>
+              Effect.sync(() => {
+                announced.push(message)
+                const parsed = new URL(message.split("\n")[1]!)
+                const redirect = parsed.searchParams.get("redirect_uri")!
+                const state = encodeURIComponent(parsed.searchParams.get("state")!)
+                void callback(`${redirect}?code=c&state=${state}`)
+              }),
+            // BrowserOpenerShape.open cannot fail; a launch failure is already a
+            // warning by the time it reaches here, so this models the no-op.
+            openBrowser: () => Effect.void
+          }
+        )
+      )
+    )
+    expect(token.accessToken).toBe("access")
+    expect(announced).toHaveLength(1)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Expiry serialization
+// ---------------------------------------------------------------------------
+
+describe("expiry serialization", () => {
+  test("blank parses to the zero time without an error", async () => {
+    expect(await run(parseExpiry(""))).toBe(0)
+    expect(await run(parseExpiry("   "))).toBe(0)
+  })
+
+  test("round-trips an RFC 3339 UTC instant", async () => {
+    const millis = await run(parseExpiry("2026-01-02T15:04:05Z"))
+    expect(formatExpiry(millis)).toBe("2026-01-02T15:04:05Z")
+  })
+
+  test("normalizes an offset instant to UTC", async () => {
+    const millis = await run(parseExpiry("2026-01-02T15:04:05+02:00"))
+    expect(formatExpiry(millis)).toBe("2026-01-02T13:04:05Z")
+  })
+
+  test("drops sub-second precision, as Go's second-precision RFC3339 does", async () => {
+    const millis = await run(parseExpiry("2026-01-02T15:04:05.750Z"))
+    expect(formatExpiry(millis)).toBe("2026-01-02T15:04:05Z")
+  })
+
+  test("the zero time formats as the empty string", () => {
+    expect(formatExpiry(0)).toBe("")
+  })
+
+  test.each([
+    ["2026-01-02t15:04:05z", "lowercase t/z"],
+    ["2026-01-02 15:04:05Z", "space separator"],
+    ["2026-01-02T15:04:05", "no zone"],
+    ["not-a-time", "garbage"]
+  ])("rejects %s (%s)", async (value) => {
+    const error = await run(Effect.flip(parseExpiry(value)))
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toStartWith("parse OAuth token expiry: ")
+  })
+
+  /**
+   * Every expectation below is a GOLDEN captured from `time.Parse(time.RFC3339,
+   * v)` on Go 1.26, then differentially re-verified over an 8000-case fuzz
+   * corpus (ASCII and non-ASCII) with zero verdict or message mismatches.
+   *
+   * They exist because both obvious shortcuts are WRONG here:
+   *   - a strict regex rejects inputs Go accepts (Go falls back to the lax
+   *     general layout parser when its RFC3339 fast path fails)
+   *   - `Date.parse` accepts inputs Go rejects (JS rolls over impossible dates
+   *     and hour 24 instead of failing)
+   */
+  test.each([
+    // Impossible calendar dates: JS rolls these into the next month, Go fails.
+    ["2026-02-30T00:00:00Z", "day out of range"],
+    ["2026-06-31T00:00:00Z", "day out of range"],
+    ["2026-02-29T00:00:00Z", "day out of range (2026 is not a leap year)"],
+    ["2026-01-00T00:00:00Z", "day out of range"],
+    ["2026-00-01T00:00:00Z", "month out of range"],
+    ["2026-13-01T00:00:00Z", "month out of range"],
+    // JS reads hour 24 as the next midnight; Go's stdHour rejects `24 <= hour`.
+    ["2026-01-02T24:00:00Z", "hour out of range"],
+    ["2026-01-02T15:60:05Z", "minute out of range"],
+    ["2026-01-02T15:04:60Z", "second out of range (no leap seconds)"],
+    // Zone offsets: Go's range tests use `>`, so 25 is the first bad hour.
+    ["2026-01-02T15:04:05+25:00", "time zone offset hour out of range"],
+    ["2026-01-02T15:04:05+00:99", "time zone offset minute out of range"]
+  ])("rejects %s (%s), matching Go", async (value) => {
+    const error = await run(Effect.flip(parseExpiry(value)))
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toStartWith("parse OAuth token expiry: ")
+  })
+
+  test.each([
+    // Go's general parser is LAXER than its RFC3339 fast path. A strict regex
+    // would wrongly reject all four of these.
+    ["2026-01-02T5:04:05Z", 1767330245000, "one-digit hour (getnum is non-fixed for 15)"],
+    ["2026-01-02T15:04:05,5Z", 1767366245500, "comma sub-second separator"],
+    ["2026-01-02T15:04:05+24:00", 1767279845000, "offset hour 24 (Go tests `> 24`)"],
+    ["2026-01-02T15:04:05+12:60", 1767319445000, "offset minute 60 (Go tests `> 60`)"],
+    ["2024-02-29T00:00:00Z", 1709164800000, "a real leap day"],
+    ["0000-01-01T00:00:00Z", -62167219200000, "year 0 is not shifted into 1900"],
+    ["2026-01-02T15:04:05.123456789Z", 1767366245123, "nanoseconds truncate to millis"]
+  ])("accepts %s -> %d (%s), matching Go", async (value, expected) => {
+    expect(await run(parseExpiry(value))).toBe(expected)
+  })
+
+  test("the failure message is byte-identical to Go's ParseError", async () => {
+    const error = await run(Effect.flip(parseExpiry("yesterday")))
+    expect(error.message).toBe(
+      'parse OAuth token expiry: parsing time "yesterday" as ' +
+        '"2006-01-02T15:04:05Z07:00": cannot parse "yesterday" as "2006"'
+    )
+  })
+
+  test("range failures use Go's short ParseError form, with no layout echo", async () => {
+    const error = await run(Effect.flip(parseExpiry("2026-02-30T00:00:00Z")))
+    expect(error.message).toBe(
+      'parse OAuth token expiry: parsing time "2026-02-30T00:00:00Z": day out of range'
+    )
+  })
+
+  test("trailing junk is reported as Go's `extra text`", async () => {
+    const error = await run(Effect.flip(parseExpiry("2026-01-02T15:04:05Zextra")))
+    expect(error.message).toBe(
+      'parse OAuth token expiry: parsing time "2026-01-02T15:04:05Zextra": extra text: "extra"'
+    )
+  })
+
+  test("truncated input reports the element that ran off the end", async () => {
+    // Go walks the layout, so the empty remainder fails against the next verb.
+    expect((await run(Effect.flip(parseExpiry("2026-01-02")))).message).toBe(
+      'parse OAuth token expiry: parsing time "2026-01-02" as ' +
+        '"2006-01-02T15:04:05Z07:00": cannot parse "" as "T"'
+    )
+  })
+
+  test("non-ASCII is quoted as UTF-8 BYTES, Go's time.quote, not strconv.Quote", async () => {
+    // strconv.Quote would emit "café" verbatim; time.quote escapes each byte.
+    const error = await run(Effect.flip(parseExpiry("café")))
+    expect(error.message).toBe(
+      'parse OAuth token expiry: parsing time "caf\\xc3\\xa9" as ' +
+        '"2006-01-02T15:04:05Z07:00": cannot parse "caf\\xc3\\xa9" as "2006"'
+    )
+  })
+
+  test("a tab is \\x09, not \\t (time.quote has no short escapes)", async () => {
+    const error = await run(Effect.flip(parseExpiry("a\tb")))
+    expect(error.message).toContain('"a\\x09b"')
+  })
+
+  test("quotes and backslashes take a single backslash", async () => {
+    expect((await run(Effect.flip(parseExpiry('a"b')))).message).toContain('"a\\"b"')
+    expect((await run(Effect.flip(parseExpiry("a\\b")))).message).toContain('"a\\\\b"')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Config defaults
+// ---------------------------------------------------------------------------
+
+describe("withDefaults", () => {
+  test("fills the Google endpoints and the 3-minute login timeout", () => {
+    const resolved = withDefaults({})
+    expect(resolved.authorizationUrl).toBe("https://accounts.google.com/o/oauth2/v2/auth")
+    expect(resolved.tokenUrl).toBe("https://oauth2.googleapis.com/token")
+    expect(resolved.revokeUrl).toBe("https://oauth2.googleapis.com/revoke")
+    expect(resolved.loginTimeoutMillis).toBe(180_000)
+    expect(resolved.httpTimeoutMillis).toBe(20_000)
+  })
+
+  test("non-positive durations fall back, matching Go's `<= 0` guard", () => {
+    expect(withDefaults({ loginTimeoutMillis: 0 }).loginTimeoutMillis).toBe(180_000)
+    expect(withDefaults({ httpTimeoutMillis: -1 }).httpTimeoutMillis).toBe(20_000)
+  })
+
+  test("explicit overrides survive", () => {
+    expect(withDefaults({ tokenUrl: "http://local/token" }).tokenUrl).toBe("http://local/token")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Service wiring — CredentialStore is consumed BY TAG and mocked here; P4 owns
+// the real implementation.
+// ---------------------------------------------------------------------------
+
+const storedOAuth = (overrides: Partial = {}): StoredOAuth => ({
+  clientId: "client-id",
+  clientSecret: "client-secret",
+  accessToken: "stored-access",
+  refreshToken: "stored-refresh",
+  // Long past, so every call refreshes unless overridden.
+  expiry: "2020-01-01T00:00:00Z",
+  scopes: ["scope.one"],
+  ...overrides
+})
+
+interface StoreSpy {
+  readonly saves: Array<{ readonly expected: StoredOAuth | undefined; readonly next: StoredOAuth }>
+}
+
+/** Only the members this service touches are implemented; the rest die loudly. */
+const mockStore = (
+  oauth: StoredOAuth | undefined,
+  options: { readonly casResult?: boolean } = {}
+): { readonly layer: Layer.Layer; readonly spy: StoreSpy } => {
+  const spy: StoreSpy = { saves: [] }
+  const unimplemented = (name: string) =>
+    Effect.die(new Error(`CredentialStore.${name} must not be called by OAuthService`))
+  const shape: CredentialStoreShape = {
+    dir: unimplemented("dir"),
+    path: unimplemented("path"),
+    load: Effect.succeed({ key: "", source: "", oauth, path: "/tmp/auth.json" } as Credentials),
+    save: () => unimplemented("save"),
+    saveOAuth: () => unimplemented("saveOAuth"),
+    saveRefreshedOAuth: (expected, next) =>
+      Effect.sync(() => {
+        spy.saves.push({ expected, next })
+        return options.casResult ?? true
+      }),
+    clearOAuth: unimplemented("clearOAuth"),
+    remove: unimplemented("remove"),
+    fingerprint: () => "sha256:000000000000",
+    envKeySet: Effect.succeed(false),
+    oauthBootstrap: Effect.succeed(["", ""] as const)
+  }
+  return { layer: Layer.succeed(CredentialStore, shape), spy }
+}
+
+const browserLayer = (opened: Array): Layer.Layer =>
+  Layer.succeed(BrowserOpener, { open: (url) => Effect.sync(() => void opened.push(url)) })
+
+/**
+ * Wires a service instance over the mock store, the fake browser, and fetch.
+ * `use` runs `f` against the built shape, so each test drives the real service
+ * rather than the underlying free functions.
+ */
+const service = (
+  endpoints: {
+    readonly tokenUrl?: string
+    readonly revokeUrl?: string
+    readonly authorizationUrl?: string
+  },
+  stored: StoredOAuth | undefined,
+  options: { readonly casResult?: boolean; readonly opener?: BrowserOpenerShape } = {}
+) => {
+  const { layer, spy } = mockStore(stored, options)
+  const opened: Array = []
+  const use = (f: (shape: OAuthServiceShape) => Effect.Effect): Effect.Effect =>
+    Effect.flatMap(makeOAuthService(endpoints), f).pipe(
+      Effect.provide(layer),
+      Effect.provide(
+        options.opener === undefined
+          ? browserLayer(opened)
+          : Layer.succeed(BrowserOpener, options.opener)
+      ),
+      Effect.provide(FetchHttpClient.layer)
+    )
+  return { use, spy, opened }
+}
+
+describe("OAuthService.tokenSource", () => {
+  test("refreshes a stale stored token and persists it through the CAS", async () => {
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"fresh-access","expires_in":3600,"token_type":"Bearer"}`)
+    )
+    const wired = service({ tokenUrl: server.url }, storedOAuth())
+    const access = await Effect.runPromise(
+      wired.use((shape) => shape.tokenSource(false))
+    )
+    expect(Redacted.value(access)).toBe("fresh-access")
+
+    const form = server.requests[0]!.form
+    expect(form.get("grant_type")).toBe("refresh_token")
+    expect(form.get("refresh_token")).toBe("stored-refresh")
+    expect(form.get("client_id")).toBe("client-id")
+    expect(form.get("client_secret")).toBe("client-secret")
+
+    expect(wired.spy.saves).toHaveLength(1)
+    expect(wired.spy.saves[0]!.expected).toEqual(storedOAuth())
+    expect(wired.spy.saves[0]!.next.accessToken).toBe("fresh-access")
+    // The response omitted both, so both are inherited.
+    expect(wired.spy.saves[0]!.next.refreshToken).toBe("stored-refresh")
+    expect(wired.spy.saves[0]!.next.scopes).toEqual(["scope.one"])
+    expect(wired.spy.saves[0]!.next.expiry).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/)
+  })
+
+  test("the source is built once: a second call reuses the cached token", async () => {
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"fresh-access","expires_in":3600,"token_type":"Bearer"}`)
+    )
+    const wired = service({ tokenUrl: server.url }, storedOAuth())
+    const tokens = await Effect.runPromise(
+      wired.use((shape) =>
+          Effect.gen(function* () {
+            const first = yield* shape.tokenSource(false)
+            const second = yield* shape.tokenSource(false)
+            return [Redacted.value(first), Redacted.value(second)] as const
+          })
+      )
+    )
+    expect(tokens).toEqual(["fresh-access", "fresh-access"])
+    expect(server.requests).toHaveLength(1)
+  })
+
+  test("force re-refreshes even when the cached token is fresh (the post-401 path)", async () => {
+    let calls = 0
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"${++calls === 1 ? "first" : "second"}","expires_in":3600}`)
+    )
+    const wired = service({ tokenUrl: server.url }, storedOAuth())
+    const access = await Effect.runPromise(
+      wired.use((shape) =>
+          Effect.gen(function* () {
+            yield* shape.tokenSource(false)
+            return Redacted.value(yield* shape.tokenSource(true))
+          })
+      )
+    )
+    expect(access).toBe("second")
+    expect(server.requests).toHaveLength(2)
+    // The second CAS expects the FIRST refresh's value, not the original.
+    expect(wired.spy.saves[1]!.expected!.accessToken).toBe("first")
+  })
+
+  test("a losing CAS (logout won the race) neither fails nor advances the snapshot", async () => {
+    let calls = 0
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"${++calls === 1 ? "first" : "second"}","expires_in":3600}`)
+    )
+    const wired = service({ tokenUrl: server.url }, storedOAuth(), { casResult: false })
+    const access = await Effect.runPromise(
+      wired.use((shape) =>
+          Effect.gen(function* () {
+            yield* shape.tokenSource(false)
+            return Redacted.value(yield* shape.tokenSource(true))
+          })
+      )
+    )
+    expect(access).toBe("second")
+    // The snapshot never advanced, so both attempts carry the ORIGINAL value.
+    expect(wired.spy.saves[0]!.expected).toEqual(storedOAuth())
+    expect(wired.spy.saves[1]!.expected).toEqual(storedOAuth())
+  })
+
+  test("no stored OAuth credentials yields MissingOAuthError", async () => {
+    const wired = service({ tokenUrl: "http://127.0.0.1:1/token" }, undefined)
+    const error = await Effect.runPromise(
+      Effect.flip(wired.use((shape) => shape.tokenSource(false)))
+    )
+    expect(error).toBeInstanceOf(MissingOAuthError)
+    expect(error.message).toBe("no OAuth credentials configured; run 'oytc login --oauth'")
+  })
+
+  test("a still-valid stored token is served without any network call", async () => {
+    const server = startServer(() => tokenJson(`{"access_token":"unused"}`))
+    const wired = service(
+      { tokenUrl: server.url },
+      storedOAuth({ expiry: formatExpiry(Date.now() + 3_600_000), accessToken: "still-good" })
+    )
+    const access = await Effect.runPromise(
+      wired.use((shape) => shape.tokenSource(false))
+    )
+    expect(Redacted.value(access)).toBe("still-good")
+    expect(server.requests).toHaveLength(0)
+  })
+
+  test("concurrent callers share one source and issue one refresh", async () => {
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"fresh","expires_in":3600,"token_type":"Bearer"}`)
+    )
+    const wired = service({ tokenUrl: server.url }, storedOAuth())
+    const tokens = await Effect.runPromise(
+      wired.use((shape) =>
+          Effect.map(
+            Effect.all([shape.tokenSource(false), shape.tokenSource(false)], {
+              concurrency: "unbounded"
+            }),
+            (values) => values.map(Redacted.value)
+          )
+      )
+    )
+    expect(tokens).toEqual(["fresh", "fresh"])
+    expect(server.requests).toHaveLength(1)
+  })
+
+  test("a corrupt stored expiry surfaces as an operational error", async () => {
+    const wired = service({ tokenUrl: "http://127.0.0.1:1" }, storedOAuth({ expiry: "yesterday" }))
+    const error = await Effect.runPromise(
+      Effect.flip(wired.use((shape) => shape.tokenSource(false)))
+    )
+    expect(error.message).toStartWith("parse OAuth token expiry: ")
+  })
+})
+
+describe("OAuthService.revoke", () => {
+  const revoking = (stored: StoredOAuth, revokeUrl: string) => {
+    const wired = service({ revokeUrl }, stored)
+    return wired.use((shape) => shape.revoke(stored))
+  }
+
+  test("prefers the refresh token", async () => {
+    const server = startServer(() => new Response("", { status: 200 }))
+    await Effect.runPromise(revoking(storedOAuth(), server.url))
+    expect(server.requests[0]!.form.get("token")).toBe("stored-refresh")
+  })
+
+  test("falls back to the access token when the refresh token is empty", async () => {
+    const server = startServer(() => new Response("", { status: 200 }))
+    await Effect.runPromise(revoking(storedOAuth({ refreshToken: "" }), server.url))
+    expect(server.requests[0]!.form.get("token")).toBe("stored-access")
+  })
+
+  test("a failing revoke endpoint is swallowed — logout must still proceed", async () => {
+    const server = startServer(
+      () =>
+        new Response(`{"error":"invalid_token"}`, {
+          status: 400,
+          headers: { "Content-Type": "application/json" }
+        })
+    )
+    const exit = await Effect.runPromiseExit(revoking(storedOAuth(), server.url))
+    expect(exit._tag).toBe("Success")
+  })
+
+  test("an unreachable revoke endpoint is also swallowed", async () => {
+    const exit = await Effect.runPromiseExit(revoking(storedOAuth(), "http://127.0.0.1:1/revoke"))
+    expect(exit._tag).toBe("Success")
+  })
+})
+
+describe("OAuthService.refresh", () => {
+  test("returns a StoredOAuth carrying the original client credentials", async () => {
+    const server = startServer(() =>
+      tokenJson(`{"access_token":"new","expires_in":3600,"scope":"a b","token_type":"Bearer"}`)
+    )
+    const stored = storedOAuth()
+    const wired = service({ tokenUrl: server.url }, stored)
+    const updated = await Effect.runPromise(
+      wired.use((shape) => shape.refresh(stored))
+    )
+    expect(updated.clientId).toBe("client-id")
+    expect(updated.clientSecret).toBe("client-secret")
+    expect(updated.accessToken).toBe("new")
+    expect(updated.refreshToken).toBe("stored-refresh")
+    expect(updated.scopes).toEqual(["a", "b"])
+  })
+})
+
+describe("OAuthService.login", () => {
+  test("drives the browser, exchanges the code, and returns a StoredOAuth", async () => {
+    const server = startServer(() =>
+      tokenJson(
+        `{"access_token":"access","refresh_token":"refresh","expires_in":3600,` +
+          `"scope":"granted.one granted.two","token_type":"Bearer"}`
+      )
+    )
+    const opened: Array = []
+    const wired = service(
+      { tokenUrl: server.url, authorizationUrl: "https://accounts.example/auth" },
+      undefined,
+      {
+        opener: {
+          open: (url) =>
+            Effect.sync(() => {
+              opened.push(url)
+              const parsed = new URL(url)
+              const redirect = parsed.searchParams.get("redirect_uri")!
+              const state = encodeURIComponent(parsed.searchParams.get("state")!)
+              void callback(`${redirect}?code=the-code&state=${state}`)
+            })
+        }
+      }
+    )
+
+    const { announced, stored } = await Effect.runPromise(
+      Effect.gen(function* () {
+        const result = yield* wired.use((shape) =>
+          shape.login({ clientId: "cli-id", clientSecret: Redacted.make("cli-secret") })
+        )
+        return { stored: result, announced: yield* TestConsole.errorLines }
+      }).pipe(Effect.provide(TestConsole.layer))
+    )
+
+    // Go prints this to cfg.Out, which the CLI wires to stderr.
+    expect(announced).toHaveLength(1)
+    expect(String(announced[0])).toStartWith("Open this URL to authorize oytc:\n")
+
+    expect(stored.clientId).toBe("cli-id")
+    expect(stored.clientSecret).toBe("cli-secret")
+    expect(stored.accessToken).toBe("access")
+    expect(stored.refreshToken).toBe("refresh")
+    expect(stored.scopes).toEqual(["granted.one", "granted.two"])
+    expect(stored.expiry).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/)
+
+    // The default scopes are requested, in order.
+    expect(new URL(opened[0]!).searchParams.get("scope")).toBe(
+      "https://www.googleapis.com/auth/yt-analytics.readonly" +
+        " https://www.googleapis.com/auth/youtube.readonly"
+    )
+    expect(server.requests[0]!.form.get("code")).toBe("the-code")
+  })
+})
diff --git a/src/impl/oauth.ts b/src/impl/oauth.ts
index ca14f9a..7f1c1b6 100644
--- a/src/impl/oauth.ts
+++ b/src/impl/oauth.ts
@@ -1,2 +1,987 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * OAuth 2.0 loopback redirect flow (authorization code + PKCE S256).
+ *
+ * The Go implementation wraps `golang.org/x/oauth2`; this port reproduces the
+ * WIRE behavior of that library rather than its API, because the wire behavior
+ * is what Google sees and what the tests assert. In particular:
+ *
+ *   - `AuthStyle` is pinned to `AuthStyleInParams`: `client_id` and
+ *     `client_secret` go in the POST body, never `Authorization: Basic`. Go
+ *     pins this to avoid the library's two-request auto-detection probe.
+ *   - Token responses are dispatched on `Content-Type` exactly as
+ *     `x/oauth2/internal.doTokenRoundTrip` does — form/text-plain bodies are
+ *     parsed as a query string, everything else as JSON — because the two
+ *     branches produce *different* error descriptions for the same body, and
+ *     `oauth_test.go` exercises both (`TestExchangeErrorWithoutContentType`
+ *     reaches the form branch because Go's httptest server content-sniffs an
+ *     unlabelled body to `text/plain`).
+ *   - Expiry is stamped from `expires_in` against the clock, and both the stamp
+ *     and the TokenSource skew check read the SAME clock. Go split these (real
+ *     clock for stamping, `cfg.Now` for checks); using one Effect `Clock` is
+ *     identical in production and strictly more coherent under a TestClock.
+ *
+ * Non-obvious invariants worth keeping:
+ *   - `redirectURI` has NO trailing slash and NO path. It is sent byte-identical
+ *     in the authorization request and the token exchange; Google compares them.
+ *   - The 3-minute login timeout covers ONLY the wait for the browser callback.
+ *     The token exchange that follows runs under the caller's timeout.
+ */
+
+import { Clock, Console, Effect, Layer, Redacted, Ref, type Scope, Semaphore } from "effect"
+import { HttpClient, HttpClientRequest } from "../effect.ts"
+import { MissingOAuthError, OAuthError, OperationalError, statusText } from "../domain/errors.ts"
+import {
+  BrowserOpener,
+  type BrowserOpenerShape,
+  CredentialStore,
+  type CredentialStoreShape,
+  OAuthService,
+  type OAuthLoginRequest,
+  type OAuthServiceShape,
+  type StoredOAuth
+} from "../services/index.ts"
+import { acquireLoopbackServer } from "./oauthServer.ts"
+import { makeTokenSource, type TokenSourceHandle } from "./tokenSource.ts"
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_AUTHORIZATION_URL = "https://accounts.google.com/o/oauth2/v2/auth"
+export const DEFAULT_TOKEN_URL = "https://oauth2.googleapis.com/token"
+export const DEFAULT_REVOKE_URL = "https://oauth2.googleapis.com/revoke"
+
+/** `DefaultLoginTimeout`; the CLI also passes 3m explicitly. */
+export const DEFAULT_LOGIN_TIMEOUT_MILLIS = 3 * 60 * 1000
+
+/** Go's default `http.Client{Timeout: 20 * time.Second}` when none is injected. */
+export const DEFAULT_HTTP_TIMEOUT_MILLIS = 20_000
+
+/** `io.ReadAll(io.LimitReader(body, 1<<20))` — both in x/oauth2 and in `Revoke`. */
+const BODY_LIMIT_BYTES = 1 << 20
+
+/**
+ * Scopes, in this exact order (internal/cli/auth.go). Analytics reports plus
+ * read-only Data API access, so an OAuth-only setup can also run every
+ * public-data command. `youtube.readonly` is classified *sensitive*: unverified
+ * apps requesting it are hard-blocked for accounts with Advanced Protection or
+ * restrictive Workspace policies.
+ */
+export const DEFAULT_SCOPES: ReadonlyArray = [
+  "https://www.googleapis.com/auth/yt-analytics.readonly",
+  "https://www.googleapis.com/auth/youtube.readonly"
+]
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface OAuthToken {
+  readonly accessToken: string
+  readonly refreshToken: string
+  /** Millis since the epoch. `0` is Go's zero `time.Time` — "no expiry known". */
+  readonly expiryMillis: number
+  readonly scopes: ReadonlyArray
+}
+
+export interface OAuthEndpoints {
+  readonly authorizationUrl: string
+  readonly tokenUrl: string
+  readonly revokeUrl: string
+}
+
+export interface OAuthConfig extends OAuthEndpoints {
+  readonly clientId: string
+  readonly clientSecret: string
+  readonly scopes: ReadonlyArray
+  readonly httpTimeoutMillis: number
+  readonly loginTimeoutMillis: number
+}
+
+export const defaultEndpoints: OAuthEndpoints = {
+  authorizationUrl: DEFAULT_AUTHORIZATION_URL,
+  tokenUrl: DEFAULT_TOKEN_URL,
+  revokeUrl: DEFAULT_REVOKE_URL
+}
+
+/** `withDefaults(cfg)` — empty strings and non-positive durations fall back. */
+export const withDefaults = (config: Partial): OAuthConfig => ({
+  clientId: config.clientId ?? "",
+  clientSecret: config.clientSecret ?? "",
+  scopes: config.scopes ?? [],
+  authorizationUrl:
+    config.authorizationUrl === undefined || config.authorizationUrl === ""
+      ? DEFAULT_AUTHORIZATION_URL
+      : config.authorizationUrl,
+  tokenUrl:
+    config.tokenUrl === undefined || config.tokenUrl === ""
+      ? DEFAULT_TOKEN_URL
+      : config.tokenUrl,
+  revokeUrl:
+    config.revokeUrl === undefined || config.revokeUrl === ""
+      ? DEFAULT_REVOKE_URL
+      : config.revokeUrl,
+  httpTimeoutMillis:
+    config.httpTimeoutMillis === undefined || config.httpTimeoutMillis <= 0
+      ? DEFAULT_HTTP_TIMEOUT_MILLIS
+      : config.httpTimeoutMillis,
+  loginTimeoutMillis:
+    config.loginTimeoutMillis === undefined || config.loginTimeoutMillis <= 0
+      ? DEFAULT_LOGIN_TIMEOUT_MILLIS
+      : config.loginTimeoutMillis
+})
+
+/**
+ * `OAuth authorization is expired or revoked; re-run 'oytc login --oauth': `.
+ *
+ * Go wraps the `*oauth.Error` with `%w`, so `main.go`'s `errors.As` still finds
+ * it and still exits 3. Subclassing keeps `_tag: "OAuthError"` and therefore the
+ * same exit-code derivation, while replacing the rendered message.
+ */
+export class ExpiredAuthorizationError extends OAuthError {
+  override get message(): string {
+    const code = this.code === "" ? "unknown" : this.code
+    const inner =
+      this.description === ""
+        ? `OAuth error (${code})`
+        : `OAuth error (${code}): ${this.description}`
+    return `OAuth authorization is expired or revoked; re-run 'oytc login --oauth': ${inner}`
+  }
+}
+
+/**
+ * `OAuth refresh token is missing; re-run 'oytc login --oauth'`.
+ *
+ * Go returns a bare `errors.New`, which `main.go` classifies as exit 3 purely by
+ * the `re-run 'oytc login --oauth'` substring rule. Modelling it as an
+ * `OAuthError` with an empty code lands on the same exit 3 through the
+ * structured path, and keeps it inside the error union `refresh` declares.
+ */
+export class MissingRefreshTokenError extends OAuthError {
+  constructor() {
+    super({ httpStatus: 0, code: "", description: "" })
+  }
+  override get message(): string {
+    return "OAuth refresh token is missing; re-run 'oytc login --oauth'"
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Randomness, PKCE
+// ---------------------------------------------------------------------------
+
+const base64UrlNoPad = (bytes: Uint8Array): string => {
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "")
+}
+
+/**
+ * `base64.RawURLEncoding.EncodeToString(rand(32))` — 43 characters.
+ * Used for both `state` and the PKCE verifier (`oauth2.GenerateVerifier`).
+ */
+export const randomUrlSafe = (byteLength: number): Effect.Effect =>
+  Effect.try({
+    try: () => base64UrlNoPad(crypto.getRandomValues(new Uint8Array(byteLength))),
+    catch: (cause) =>
+      new OperationalError({
+        message: `generate OAuth random value: ${describe(cause)}`,
+        cause
+      })
+  })
+
+/** `code_challenge = base64url_nopad(sha256(verifier))`, method `S256`. */
+export const pkceChallenge = (verifier: string): Effect.Effect =>
+  Effect.tryPromise({
+    try: async () =>
+      base64UrlNoPad(
+        new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)))
+      ),
+    catch: (cause) =>
+      new OperationalError({
+        message: `generate OAuth PKCE challenge: ${describe(cause)}`,
+        cause
+      })
+  })
+
+// ---------------------------------------------------------------------------
+// Authorization URL
+// ---------------------------------------------------------------------------
+
+/**
+ * Go's `url.Values.Encode()` sorts keys before joining. Percent-encoding is
+ * byte-identical to `URLSearchParams` for every value this flow produces
+ * (base64url state/challenge, an `https://` scope list, a loopback redirect URI,
+ * a Google client id): the two disagree only on `~ ! * ( ) '`, none of which
+ * occur. Sorting keeps the emitted URL byte-comparable with the Go binary.
+ */
+const encodeForm = (pairs: ReadonlyArray): string => {
+  const sorted = [...pairs].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  return new URLSearchParams(sorted as Array<[string, string]>).toString()
+}
+
+export const authorizationUrl = (
+  config: OAuthConfig,
+  redirectUri: string,
+  state: string,
+  challenge: string
+): string => {
+  const params: Array = [
+    ["response_type", "code"],
+    ["client_id", config.clientId]
+  ]
+  if (redirectUri !== "") params.push(["redirect_uri", redirectUri])
+  if (config.scopes.length > 0) params.push(["scope", config.scopes.join(" ")])
+  if (state !== "") params.push(["state", state])
+  params.push(["access_type", "offline"])
+  params.push(["code_challenge_method", "S256"])
+  params.push(["code_challenge", challenge])
+  // Forces the consent screen so Google ALWAYS returns a refresh token, not
+  // only on the first authorization.
+  params.push(["prompt", "consent"])
+
+  const separator = config.authorizationUrl.includes("?") ? "&" : "?"
+  return `${config.authorizationUrl}${separator}${encodeForm(params)}`
+}
+
+// ---------------------------------------------------------------------------
+// Token endpoint
+// ---------------------------------------------------------------------------
+
+const describe = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause))
+
+const decodeBody = (bytes: Uint8Array): string =>
+  new TextDecoder().decode(bytes.subarray(0, BODY_LIMIT_BYTES))
+
+/** `mime.ParseMediaType` reduced to what the dispatch needs. */
+const mediaType = (contentType: string | undefined): string =>
+  (contentType ?? "").split(";")[0]?.trim().toLowerCase() ?? ""
+
+const asString = (value: unknown): string => (typeof value === "string" ? value : "")
+
+/** `expirationTime.UnmarshalJSON` — numbers or numeric strings, clamped to int32. */
+const asExpiresIn = (value: unknown): number => {
+  const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN
+  if (!Number.isFinite(n)) return 0
+  return Math.min(Math.trunc(n), 2147483647)
+}
+
+interface TokenPayload {
+  readonly accessToken: string
+  readonly refreshToken: string
+  readonly expiresInSeconds: number
+  readonly scope: string
+  readonly errorCode: string
+  readonly errorDescription: string
+  /** The body could not be decoded in the branch its content type selected. */
+  readonly undecodable: boolean
+}
+
+const parseFormPayload = (body: string): TokenPayload => {
+  const values = new URLSearchParams(body)
+  return {
+    accessToken: values.get("access_token") ?? "",
+    refreshToken: values.get("refresh_token") ?? "",
+    expiresInSeconds: asExpiresIn(values.get("expires_in") ?? ""),
+    scope: values.get("scope") ?? "",
+    errorCode: values.get("error") ?? "",
+    errorDescription: values.get("error_description") ?? "",
+    undecodable: false
+  }
+}
+
+const parseJsonPayload = (body: string): TokenPayload => {
+  let decoded: unknown
+  try {
+    decoded = JSON.parse(body)
+  } catch {
+    return {
+      accessToken: "",
+      refreshToken: "",
+      expiresInSeconds: 0,
+      scope: "",
+      errorCode: "",
+      errorDescription: "",
+      undecodable: true
+    }
+  }
+  const record = (
+    typeof decoded === "object" && decoded !== null ? decoded : {}
+  ) as Record
+  return {
+    accessToken: asString(record["access_token"]),
+    refreshToken: asString(record["refresh_token"]),
+    expiresInSeconds: asExpiresIn(record["expires_in"]),
+    scope: asString(record["scope"]),
+    errorCode: asString(record["error"]),
+    errorDescription: asString(record["error_description"]),
+    undecodable: false
+  }
+}
+
+/**
+ * `doTokenRoundTrip`'s content-type dispatch. Form/text-plain bodies are read as
+ * a query string — which is why an unlabelled JSON error body yields an EMPTY
+ * error code there and has to be re-parsed by {@link parseErrorBody}.
+ */
+const parseTokenPayload = (contentType: string | undefined, body: string): TokenPayload => {
+  const type = mediaType(contentType)
+  return type === "application/x-www-form-urlencoded" || type === "text/plain"
+    ? parseFormPayload(body)
+    : parseJsonPayload(body)
+}
+
+/**
+ * `parseError(status, body)`: JSON-decode `{error, error_description}`; an empty
+ * code falls back to the HTTP status text, an empty description to the trimmed
+ * raw body.
+ */
+export const parseErrorBody = (status: number, body: string): OAuthError => {
+  const payload = parseJsonPayload(body)
+  return new OAuthError({
+    httpStatus: status,
+    code: payload.errorCode === "" ? statusText(status) : payload.errorCode,
+    description: payload.errorDescription === "" ? body.trim() : payload.errorDescription
+  })
+}
+
+interface RetrievedToken {
+  readonly accessToken: string
+  readonly refreshToken: string
+  readonly expiryMillis: number
+  readonly scope: string
+}
+
+const postForm = (
+  action: string,
+  url: string,
+  form: ReadonlyArray,
+  headers: ReadonlyArray,
+  timeoutMillis: number
+): Effect.Effect<
+  { readonly status: number; readonly contentType: string | undefined; readonly body: string },
+  OperationalError,
+  HttpClient.HttpClient
+> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    // Sorted, so the emitted body is byte-identical to Go's url.Values.Encode.
+    let request = HttpClientRequest.post(url).pipe(
+      HttpClientRequest.bodyText(encodeForm(form), "application/x-www-form-urlencoded")
+    )
+    for (const [name, value] of headers) {
+      request = HttpClientRequest.setHeader(request, name, value)
+    }
+    const response = yield* client.execute(request)
+    const buffer = yield* response.arrayBuffer
+    return {
+      status: response.status,
+      contentType: response.headers["content-type"],
+      body: decodeBody(new Uint8Array(buffer))
+    }
+  }).pipe(
+    Effect.timeoutOrElse({
+      duration: timeoutMillis,
+      orElse: () =>
+        Effect.fail(
+          new OperationalError({
+            message: `${action}: Client.Timeout exceeded while awaiting headers`
+          })
+        )
+    }),
+    // translateError: a *url.Error is unwrapped to `: `.
+    Effect.catch((cause) =>
+      cause instanceof OperationalError
+        ? Effect.fail(cause)
+        : Effect.fail(
+            new OperationalError({ message: `${action}: ${describe(cause)}`, cause })
+          )
+    )
+  )
+
+/** `retrieveToken` + `translateError`, collapsed. */
+const retrieveToken = (
+  action: string,
+  config: OAuthConfig,
+  form: ReadonlyArray
+): Effect.Effect =>
+  Effect.gen(function* () {
+    // AuthStyleInParams: credentials in the POST body, never Basic auth.
+    const body: Array = [...form]
+    if (config.clientId !== "") body.push(["client_id", config.clientId])
+    if (config.clientSecret !== "") body.push(["client_secret", config.clientSecret])
+
+    const response = yield* postForm(action, config.tokenUrl, body, [], config.httpTimeoutMillis)
+    const failureStatus = response.status < 200 || response.status > 299
+    const payload = parseTokenPayload(response.contentType, response.body)
+
+    if (payload.undecodable) {
+      return yield* Effect.fail(
+        failureStatus
+          ? parseErrorBody(response.status, response.body)
+          : new OperationalError({ message: `oauth2: cannot parse json: ${response.body}` })
+      )
+    }
+
+    if (failureStatus || payload.errorCode !== "") {
+      return yield* Effect.fail(
+        payload.errorCode === ""
+          ? parseErrorBody(response.status, response.body)
+          : new OAuthError({
+              httpStatus: response.status,
+              code: payload.errorCode,
+              description: payload.errorDescription
+            })
+      )
+    }
+
+    if (payload.accessToken === "") {
+      return yield* Effect.fail(
+        new OperationalError({ message: "oauth2: server response missing access_token" })
+      )
+    }
+
+    const now = yield* Clock.currentTimeMillis
+    // Don't overwrite an empty RefreshToken on a refresh_token grant.
+    const requested = body.find(([key]) => key === "refresh_token")?.[1] ?? ""
+    return {
+      accessToken: payload.accessToken,
+      refreshToken: payload.refreshToken === "" ? requested : payload.refreshToken,
+      expiryMillis:
+        payload.expiresInSeconds === 0 ? 0 : now + payload.expiresInSeconds * 1000,
+      scope: payload.scope
+    }
+  })
+
+/**
+ * `fromLibrary`: inherit the refresh token and the scopes when the response
+ * omits them, falling back to the configured scopes only as a last resort.
+ */
+const normalizeToken = (
+  retrieved: RetrievedToken,
+  config: OAuthConfig,
+  current: OAuthToken
+): OAuthToken => {
+  // strings.Fields: split on any whitespace run, no empty elements.
+  const granted = retrieved.scope.split(/\s+/).filter((part) => part !== "")
+  const scopes =
+    granted.length > 0 ? granted : current.scopes.length > 0 ? [...current.scopes] : [...config.scopes]
+  return {
+    accessToken: retrieved.accessToken,
+    refreshToken: retrieved.refreshToken === "" ? current.refreshToken : retrieved.refreshToken,
+    expiryMillis: retrieved.expiryMillis,
+    scopes
+  }
+}
+
+const emptyToken: OAuthToken = {
+  accessToken: "",
+  refreshToken: "",
+  expiryMillis: 0,
+  scopes: []
+}
+
+// ---------------------------------------------------------------------------
+// Exchange / refresh / revoke
+// ---------------------------------------------------------------------------
+
+export const exchange = (
+  config: OAuthConfig,
+  code: string,
+  redirectUri: string,
+  verifier: string
+): Effect.Effect => {
+  const form: Array = [
+    ["grant_type", "authorization_code"],
+    ["code", code]
+  ]
+  if (redirectUri !== "") form.push(["redirect_uri", redirectUri])
+  form.push(["code_verifier", verifier])
+  return Effect.map(retrieveToken("request OAuth token", config, form), (retrieved) =>
+    normalizeToken(retrieved, config, emptyToken)
+  )
+}
+
+export const refresh = (
+  config: OAuthConfig,
+  current: OAuthToken
+): Effect.Effect =>
+  Effect.gen(function* () {
+    if (current.refreshToken.trim() === "") {
+      return yield* Effect.fail(new MissingRefreshTokenError())
+    }
+    const retrieved = yield* retrieveToken("refresh OAuth token", config, [
+      ["grant_type", "refresh_token"],
+      ["refresh_token", current.refreshToken]
+    ])
+    return normalizeToken(retrieved, config, current)
+  })
+
+/**
+ * Best-effort revocation. An empty/whitespace token is a no-op that succeeds,
+ * matching Go; a non-2xx response becomes a structured `OAuthError` that the
+ * caller downgrades to a warning.
+ */
+export const revoke = (
+  config: OAuthConfig,
+  token: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    if (token.trim() === "") return
+    const response = yield* postForm(
+      "revoke OAuth token",
+      config.revokeUrl,
+      [["token", token]],
+      [
+        ["Content-Type", "application/x-www-form-urlencoded"],
+        ["Accept", "application/json"]
+      ],
+      config.httpTimeoutMillis
+    )
+    if (response.status < 200 || response.status >= 300) {
+      return yield* Effect.fail(parseErrorBody(response.status, response.body))
+    }
+  })
+
+// ---------------------------------------------------------------------------
+// Login
+// ---------------------------------------------------------------------------
+
+export interface LoginHooks {
+  /** Receives the authorization URL; stderr in production. */
+  readonly announce: (message: string) => Effect.Effect
+  /** Best-effort browser launch; failures are reported by the opener itself. */
+  readonly openBrowser: (url: string) => Effect.Effect
+}
+
+/**
+ * The full loopback flow. The 3-minute timeout wraps ONLY the wait for the
+ * callback — the exchange that follows inherits the caller's deadline, so a
+ * user who authorizes at 2m59s still gets a token.
+ */
+export const login = (
+  config: OAuthConfig,
+  hooks: LoginHooks
+): Effect.Effect<
+  OAuthToken,
+  OAuthError | OperationalError,
+  HttpClient.HttpClient | Scope.Scope
+> =>
+  Effect.gen(function* () {
+    if (config.clientId.trim() === "") {
+      return yield* Effect.fail(new OperationalError({ message: "OAuth client ID cannot be empty" }))
+    }
+    if (config.clientSecret.trim() === "") {
+      return yield* Effect.fail(
+        new OperationalError({ message: "OAuth client secret cannot be empty" })
+      )
+    }
+
+    const state = yield* randomUrlSafe(32)
+    const verifier = yield* randomUrlSafe(32)
+    const challenge = yield* pkceChallenge(verifier)
+
+    const server = yield* acquireLoopbackServer(state)
+    const target = authorizationUrl(config, server.redirectUri, state, challenge)
+
+    yield* hooks.announce(`Open this URL to authorize oytc:\n${target}`)
+    yield* hooks.openBrowser(target)
+
+    const code = yield* server.awaitCode.pipe(
+      Effect.timeoutOrElse({
+        duration: config.loginTimeoutMillis,
+        orElse: () =>
+          Effect.fail(
+            new OperationalError({ message: "timed out waiting for OAuth authorization" })
+          )
+      })
+    )
+
+    return yield* exchange(config, code, server.redirectUri, verifier)
+  })
+
+// ---------------------------------------------------------------------------
+// Expiry serialization
+// ---------------------------------------------------------------------------
+
+/** The layout string Go names `time.RFC3339`; it appears verbatim in errors. */
+const RFC3339_LAYOUT = "2006-01-02T15:04:05Z07:00"
+
+/**
+ * Go's `time` package has its OWN quoting, which is NOT `strconv.Quote` (and so
+ * NOT `goQuote` from resolveChannel.ts), and is not the JS JSON string encoder
+ * either. Per `time/format.go`'s `quote`, every byte `>= 0x80` or
+ * `< 0x20` is emitted as `\xNN` over its UTF-8 BYTES — so `café` renders as
+ * `caf\xc3\xa9`, a tab as `\x09` (not `\t`), and 🎉 as four `\xNN` escapes.
+ * Only `"` and `\` get a backslash; everything else printable-ASCII is literal.
+ * Verified against Go 1.26 for `café`, `日本`, `a"b`, `a\b`, `a\tb`, `a\x01b`
+ * and an emoji.
+ */
+const timeQuote = (value: string): string => {
+  const bytes = new TextEncoder().encode(value)
+  let out = '"'
+  for (const byte of bytes) {
+    if (byte >= 0x80 || byte < 0x20) {
+      out += `\\x${byte.toString(16).padStart(2, "0")}`
+    } else {
+      if (byte === 0x22 || byte === 0x5c) out += "\\"
+      out += String.fromCharCode(byte)
+    }
+  }
+  return `${out}"`
+}
+
+/** `cannot parse  as ` — ParseError with an empty Message. */
+const cannotParse = (value: string, valueElem: string, layoutElem: string): string =>
+  `parsing time ${timeQuote(value)} as ${timeQuote(RFC3339_LAYOUT)}: ` +
+  `cannot parse ${timeQuote(valueElem)} as ${timeQuote(layoutElem)}`
+
+/** `parsing time : ` — ParseError with a non-empty Message. */
+const parseMessage = (value: string, message: string): string =>
+  `parsing time ${timeQuote(value)}: ${message}`
+
+const isDigit = (s: string, i: number): boolean => {
+  const c = s.charCodeAt(i)
+  return c >= 48 && c <= 57
+}
+
+/** Days in a Gregorian month, with Go's leap rule (`isLeap`). */
+const daysIn = (month: number, year: number): number => {
+  if (month === 2 && year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)) return 29
+  return [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] ?? 0
+}
+
+/**
+ * `time.Parse(time.RFC3339, value)`, reproduced closely enough that the
+ * accept/reject verdict, the resulting instant, and the error text all match.
+ *
+ * Go tries a strict fast path (`parseRFC3339`) and, when that fails, falls back
+ * to the GENERAL layout parser, which is meaningfully laxer. That fallback is
+ * why several inputs a hand-rolled regex would reject are actually accepted:
+ *
+ *   - a ONE-digit hour: `2026-01-02T5:04:05Z` parses (only the hour is lax;
+ *     `getnum(value, false)` is non-fixed for `15`, while minute/second use the
+ *     zero-padded `04`/`05` verbs and stay fixed at two digits)
+ *   - a COMMA sub-second separator: `...05,5Z` parses (`commaOrPeriod`)
+ *   - zone offsets up to ±24:60 — Go's own comment says the range tests use `>`
+ *     rather than `>=` "as some people do write offsets of 24 hours or 60
+ *     minutes", so `+24:00` and `+12:60` are ACCEPTED and only `+25:00` /
+ *     `+00:99` are rejected
+ *
+ * And why several a `Date.parse` shortcut would accept are rejected:
+ *
+ *   - `2026-02-30`, `2026-06-31`, `2026-02-29` — JS silently rolls these over
+ *     into the next month; Go validates against `daysIn` and fails with
+ *     `day out of range`
+ *   - `2026-01-02T24:00:00Z` — JS accepts hour 24 as the next midnight; Go's
+ *     `stdHour` rejects `24 <= hour`
+ *
+ * Error precedence follows `parse`'s loop: a range error for an element beats a
+ * syntax error in a LATER element, `extra text` is reported after the whole
+ * layout is consumed, and the day-of-month check runs last of all.
+ */
+const parseRfc3339 = (value: string): { readonly millis: number } | { readonly message: string } => {
+  // Elements are consumed left to right, so a truncated input naturally fails on
+  // the first element that runs past the end and reports `cannot parse "" as X`,
+  // exactly as Go's layout walk does. No length pre-check is needed (or correct).
+
+  // --- year "2006": exactly four digits, no sign ---
+  if (!/^\d{4}$/.test(value.slice(0, 4))) {
+    return { message: cannotParse(value, value, "2006") }
+  }
+  const year = Number(value.slice(0, 4))
+  let i = 4
+
+  const literal = (ch: string, elem: string): string | undefined =>
+    value[i] === ch ? void (i += 1) : cannotParse(value, value.slice(i), elem)
+
+  let bad = literal("-", "-")
+  if (bad !== undefined) return { message: bad }
+
+  // --- month "01": FIXED two digits, range 1..12 ---
+  if (!isDigit(value, i) || !isDigit(value, i + 1)) {
+    return { message: cannotParse(value, value.slice(i), "01") }
+  }
+  const month = Number(value.slice(i, i + 2))
+  const monthElem = value.slice(i + 2)
+  i += 2
+  if (month <= 0 || month > 12) {
+    return { message: parseMessage(value, "month out of range") }
+  }
+  void monthElem
+
+  bad = literal("-", "-")
+  if (bad !== undefined) return { message: bad }
+
+  // --- day "02": FIXED two digits; the value range is validated at the end ---
+  if (!isDigit(value, i) || !isDigit(value, i + 1)) {
+    return { message: cannotParse(value, value.slice(i), "02") }
+  }
+  const day = Number(value.slice(i, i + 2))
+  i += 2
+
+  bad = literal("T", "T")
+  if (bad !== undefined) return { message: bad }
+
+  // --- hour "15": NON-fixed, so one OR two digits; range 0..23 ---
+  if (!isDigit(value, i)) {
+    return { message: cannotParse(value, value.slice(i), "15") }
+  }
+  const hourWidth = isDigit(value, i + 1) ? 2 : 1
+  const hour = Number(value.slice(i, i + hourWidth))
+  i += hourWidth
+  if (hour < 0 || hour >= 24) {
+    return { message: parseMessage(value, "hour out of range") }
+  }
+
+  bad = literal(":", ":")
+  if (bad !== undefined) return { message: bad }
+
+  // --- minute "04": FIXED two digits; range 0..59 ---
+  if (!isDigit(value, i) || !isDigit(value, i + 1)) {
+    return { message: cannotParse(value, value.slice(i), "04") }
+  }
+  const minute = Number(value.slice(i, i + 2))
+  i += 2
+  if (minute < 0 || minute >= 60) {
+    return { message: parseMessage(value, "minute out of range") }
+  }
+
+  bad = literal(":", ":")
+  if (bad !== undefined) return { message: bad }
+
+  // --- second "05": FIXED two digits; range 0..59 (no leap second) ---
+  if (!isDigit(value, i) || !isDigit(value, i + 1)) {
+    return { message: cannotParse(value, value.slice(i), "05") }
+  }
+  const second = Number(value.slice(i, i + 2))
+  i += 2
+  if (second < 0 || second >= 60) {
+    return { message: parseMessage(value, "second out of range") }
+  }
+
+  // --- fractional second: `.` OR `,` followed by at least one digit ---
+  // Only the first 9 digits contribute to nanoseconds; we need milliseconds,
+  // so the first 3 suffice and the rest are truncated (never rounded).
+  let millisFraction = 0
+  if ((value[i] === "." || value[i] === ",") && isDigit(value, i + 1)) {
+    let n = i + 1
+    while (n < value.length && isDigit(value, n)) n += 1
+    const digits = value.slice(i + 1, n)
+    millisFraction = Number(`${digits.slice(0, 3)}${"0".repeat(Math.max(0, 3 - digits.length))}`)
+    i = n
+  }
+
+  // --- zone "Z07:00": literal `Z`, or ±hh:mm with Go's LAX `>` range tests ---
+  let offsetMinutes = 0
+  if (value[i] === "Z") {
+    i += 1
+  } else {
+    const zone = value.slice(i, i + 6)
+    const sign = zone[0]
+    // Go splits the field FIRST (length and the `:` at index 3 are all it checks
+    // structurally), then reads the two numbers, then range-tests them, and only
+    // afterwards validates the sign. So a bad SIGN with an out-of-range hour —
+    // `...05x25:00` — reports "time zone offset hour out of range", not a parse
+    // error. Order matters here and is verified against Go.
+    if (zone.length !== 6 || zone[3] !== ":") {
+      return { message: cannotParse(value, value.slice(i), "Z07:00") }
+    }
+    const hourDigits = /^\d{2}$/.test(zone.slice(1, 3))
+    const minuteDigits = /^\d{2}$/.test(zone.slice(4, 6))
+    const zoneHour = hourDigits ? Number(zone.slice(1, 3)) : 0
+    const zoneMinute = minuteDigits ? Number(zone.slice(4, 6)) : 0
+    // Go: "The range test use > rather than >=, as some people do write offsets
+    // of 24 hours or 60 minutes or 60 seconds." Both tests assign to the SAME
+    // `rangeErrString`, so when both are out of range the MINUTE message wins.
+    let rangeError = ""
+    if (hourDigits && zoneHour > 24) rangeError = "time zone offset hour out of range"
+    if (minuteDigits && zoneMinute > 60) rangeError = "time zone offset minute out of range"
+    if (rangeError !== "") return { message: parseMessage(value, rangeError) }
+    if (!hourDigits || !minuteDigits || (sign !== "+" && sign !== "-")) {
+      return { message: cannotParse(value, value.slice(i), "Z07:00") }
+    }
+    offsetMinutes = (sign === "-" ? -1 : 1) * (zoneHour * 60 + zoneMinute)
+    i += 6
+  }
+
+  // --- trailing junk, reported once the layout is fully consumed ---
+  if (i !== value.length) {
+    const extra = value.slice(i)
+    return { message: parseMessage(value, `extra text: ${timeQuote(extra)}`) }
+  }
+
+  // --- day-of-month, validated last, exactly as Go does ---
+  if (day < 1 || day > daysIn(month, year)) {
+    return { message: parseMessage(value, "day out of range") }
+  }
+
+  // Date.UTC maps years 0..99 into 1900..1999; setUTCFullYear undoes that so
+  // year 0 stays year 0 (Go accepts "0000-01-01T00:00:00Z").
+  const date = new Date(0)
+  date.setUTCFullYear(year, month - 1, day)
+  date.setUTCHours(hour, minute, second, millisFraction)
+  return { millis: date.getTime() - offsetMinutes * 60_000 }
+}
+
+/** `ParseExpiry` — blank is the zero time (0 millis) and is NOT an error. */
+export const parseExpiry = (value: string): Effect.Effect =>
+  Effect.gen(function* () {
+    if (value.trim() === "") return 0
+    const parsed = parseRfc3339(value)
+    if ("message" in parsed) {
+      return yield* Effect.fail(
+        new OperationalError({ message: `parse OAuth token expiry: ${parsed.message}` })
+      )
+    }
+    return parsed.millis
+  })
+
+/** `FormatExpiry` — the zero time is `""`; otherwise UTC RFC 3339, second precision. */
+export const formatExpiry = (millis: number): string => {
+  if (millis === 0) return ""
+  return `${new Date(millis).toISOString().slice(0, 19)}Z`
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+const configFor = (
+  clientId: string,
+  clientSecret: string,
+  endpoints: Partial
+): OAuthConfig =>
+  withDefaults({
+    clientId,
+    clientSecret,
+    scopes: DEFAULT_SCOPES,
+    ...endpoints
+  })
+
+export const storedFrom = (
+  clientId: string,
+  clientSecret: string,
+  token: OAuthToken
+): StoredOAuth => ({
+  clientId,
+  clientSecret,
+  accessToken: token.accessToken,
+  refreshToken: token.refreshToken,
+  expiry: formatExpiry(token.expiryMillis),
+  scopes: [...token.scopes]
+})
+
+const tokenFrom = (stored: StoredOAuth, expiryMillis: number): OAuthToken => ({
+  accessToken: stored.accessToken,
+  refreshToken: stored.refreshToken,
+  expiryMillis,
+  scopes: [...stored.scopes]
+})
+
+/**
+ * `endpoints` exists purely so tests can point the flow at a local server, the
+ * same role `App.OAuthTokenURL` plays in Go.
+ */
+export const makeOAuthService = (
+  endpoints: Partial = {}
+): Effect.Effect<
+  OAuthServiceShape,
+  never,
+  HttpClient.HttpClient | CredentialStoreShape | BrowserOpenerShape
+> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const credentials = yield* CredentialStore
+    const browser = yield* BrowserOpener
+    const cached = yield* Ref.make(undefined)
+    // Guards construction: two concurrent requests must share ONE handle, or
+    // they would each hold their own skew cache and CAS snapshot.
+    const buildGate = yield* Semaphore.make(1)
+
+    const withClient = (effect: Effect.Effect) =>
+      Effect.provideService(effect, HttpClient.HttpClient, client)
+
+    /**
+     * Built lazily and reused: `HttpCore` asks for a token on every request and
+     * forces a refresh after a 401, so the skew cache and the CAS snapshot have
+     * to survive across calls.
+     */
+    const source = Semaphore.withPermit(
+      buildGate,
+      Effect.gen(function* () {
+        const existing = yield* Ref.get(cached)
+        if (existing !== undefined) return existing
+
+        const loaded = yield* credentials.load
+        const stored = loaded.oauth
+        if (stored === undefined) return yield* Effect.fail(new MissingOAuthError({}))
+
+        const config = configFor(stored.clientId, stored.clientSecret, endpoints)
+        const expiryMillis = yield* parseExpiry(stored.expiry)
+        // The CAS snapshot only advances when the store reports a real write, so
+        // a refresh racing a `logout` cannot resurrect removed credentials.
+        const persisted = yield* Ref.make(stored)
+        const handle = makeTokenSource({
+          token: tokenFrom(stored, expiryMillis),
+          refresh: (current) => withClient(refresh(config, current)),
+          onUpdate: (updated) =>
+            Effect.gen(function* () {
+              const expected = yield* Ref.get(persisted)
+              const next = storedFrom(stored.clientId, stored.clientSecret, updated)
+              const saved = yield* credentials.saveRefreshedOAuth(expected, next)
+              if (saved) yield* Ref.set(persisted, next)
+            }).pipe(
+              Effect.catch((cause) =>
+                Effect.fail(
+                  cause instanceof OperationalError
+                    ? cause
+                    : new OperationalError({ message: cause.message, cause })
+                )
+              )
+            )
+        })
+        yield* Ref.set(cached, handle)
+        return handle
+      })
+    )
+
+    return {
+      login: (request: OAuthLoginRequest) =>
+        Effect.gen(function* () {
+          const clientId = request.clientId
+          const clientSecret = Redacted.value(request.clientSecret)
+          const config = configFor(clientId, clientSecret, endpoints)
+          const token = yield* withClient(
+            login(config, {
+              // Go writes this to cfg.Out, which the CLI wires to stderr.
+              announce: Console.error,
+              openBrowser: browser.open
+            })
+          )
+          return storedFrom(clientId, clientSecret, token)
+        }).pipe(Effect.scoped),
+
+      refresh: (stored: StoredOAuth) =>
+        Effect.gen(function* () {
+          const config = configFor(stored.clientId, stored.clientSecret, endpoints)
+          const expiryMillis = yield* parseExpiry(stored.expiry)
+          const token = yield* withClient(refresh(config, tokenFrom(stored, expiryMillis)))
+          return storedFrom(stored.clientId, stored.clientSecret, token)
+        }),
+
+      revoke: (stored: StoredOAuth) => {
+        const config = configFor(stored.clientId, stored.clientSecret, endpoints)
+        const token = stored.refreshToken === "" ? stored.accessToken : stored.refreshToken
+        return withClient(revoke(config, token)).pipe(Effect.ignore)
+      },
+
+      tokenSource: (force: boolean) =>
+        Effect.map(
+          Effect.flatMap(source, (handle) => handle.accessToken(force)),
+          Redacted.make
+        )
+    }
+  })
+
+export const OAuthServiceLive = Layer.effect(OAuthService, makeOAuthService())
diff --git a/src/impl/oauthServer.test.ts b/src/impl/oauthServer.test.ts
new file mode 100644
index 0000000..60bab84
--- /dev/null
+++ b/src/impl/oauthServer.test.ts
@@ -0,0 +1,145 @@
+import { describe, expect, test } from "bun:test"
+import { Deferred, Effect, Exit } from "effect"
+import {
+  acquireLoopbackServer,
+  MISSING_CODE_BODY,
+  MISSING_CODE_MESSAGE,
+  NOT_GRANTED_BODY,
+  STATE_MISMATCH_BODY,
+  SUCCESS_BODY
+} from "./oauthServer.ts"
+import { OAuthError, OperationalError } from "../domain/errors.ts"
+
+const STATE = "state-value"
+
+/**
+ * Runs `body` with a live loopback server, tearing it down afterwards. The
+ * whole thing is scoped so a failing assertion still releases the port.
+ */
+const withServer = (
+  body: (server: {
+    readonly redirectUri: string
+    readonly awaitCode: Effect.Effect
+  }) => Promise
+): Promise =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      const server = yield* acquireLoopbackServer(STATE)
+      return yield* Effect.promise(() => body(server))
+    }).pipe(Effect.scoped)
+  )
+
+describe("loopback callback server", () => {
+  test("redirect URI has no trailing slash and no path", () =>
+    withServer(async (server) => {
+      expect(server.redirectUri).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/)
+    }))
+
+  test("success responds with the byte-exact HTML page and resolves the code", () =>
+    withServer(async (server) => {
+      const response = await fetch(`${server.redirectUri}/?code=callback-code&state=${STATE}`)
+      expect(response.status).toBe(200)
+      expect(response.headers.get("content-type")).toBe("text/html; charset=utf-8")
+      expect(await response.text()).toBe(SUCCESS_BODY)
+      expect(await Effect.runPromise(server.awaitCode)).toBe("callback-code")
+    }))
+
+  test("the handler answers on EVERY path, not just /", () =>
+    withServer(async (server) => {
+      const response = await fetch(`${server.redirectUri}/deep/nested/path?code=abc&state=${STATE}`)
+      expect(response.status).toBe(200)
+      expect(await Effect.runPromise(server.awaitCode)).toBe("abc")
+    }))
+
+  test("state mismatch responds 400 and does NOT resolve the flow", () =>
+    withServer(async (server) => {
+      const response = await fetch(`${server.redirectUri}/?code=evil&state=wrong`)
+      expect(response.status).toBe(400)
+      expect(response.headers.get("content-type")).toBe("text/plain; charset=utf-8")
+      expect(response.headers.get("x-content-type-options")).toBe("nosniff")
+      expect(await response.text()).toBe(STATE_MISMATCH_BODY)
+
+      // Still unresolved: a later, valid callback must be the one that wins.
+      const pending = await Effect.runPromise(
+        Effect.exit(Effect.timeout(server.awaitCode, 50))
+      )
+      expect(Exit.isFailure(pending)).toBe(true)
+
+      await fetch(`${server.redirectUri}/?code=real&state=${STATE}`)
+      expect(await Effect.runPromise(server.awaitCode)).toBe("real")
+    }))
+
+  test("a missing state also fails to match and keeps the flow alive", () =>
+    withServer(async (server) => {
+      const response = await fetch(`${server.redirectUri}/favicon.ico`)
+      expect(response.status).toBe(400)
+      expect(await response.text()).toBe(STATE_MISMATCH_BODY)
+      const pending = await Effect.runPromise(Effect.exit(Effect.timeout(server.awaitCode, 50)))
+      expect(Exit.isFailure(pending)).toBe(true)
+    }))
+
+  test("an error param resolves the flow with a structured OAuthError", () =>
+    withServer(async (server) => {
+      const response = await fetch(
+        `${server.redirectUri}/?error=access_denied&error_description=nope&state=${STATE}`
+      )
+      expect(response.status).toBe(400)
+      expect(await response.text()).toBe(NOT_GRANTED_BODY)
+
+      const error = await Effect.runPromise(Effect.flip(server.awaitCode))
+      expect(error).toBeInstanceOf(OAuthError)
+      expect((error as OAuthError).code).toBe("access_denied")
+      expect((error as OAuthError).description).toBe("nope")
+    }))
+
+  test("a blank code resolves the flow with the missing-code error", () =>
+    withServer(async (server) => {
+      const response = await fetch(`${server.redirectUri}/?code=%20%20&state=${STATE}`)
+      expect(response.status).toBe(400)
+      expect(await response.text()).toBe(MISSING_CODE_BODY)
+      const error = await Effect.runPromise(Effect.flip(server.awaitCode))
+      expect(error).toBeInstanceOf(OperationalError)
+      expect(error.message).toBe(MISSING_CODE_MESSAGE)
+    }))
+
+  test("an absent code param is treated the same as a blank one", () =>
+    withServer(async (server) => {
+      const response = await fetch(`${server.redirectUri}/?state=${STATE}`)
+      expect(response.status).toBe(400)
+      expect(await response.text()).toBe(MISSING_CODE_BODY)
+      const error = await Effect.runPromise(Effect.flip(server.awaitCode))
+      expect(error.message).toBe(MISSING_CODE_MESSAGE)
+    }))
+
+  test("only the FIRST resolution wins; later callbacks are ignored", () =>
+    withServer(async (server) => {
+      await fetch(`${server.redirectUri}/?code=first&state=${STATE}`)
+      await fetch(`${server.redirectUri}/?error=access_denied&state=${STATE}`)
+      await fetch(`${server.redirectUri}/?code=third&state=${STATE}`)
+      expect(await Effect.runPromise(server.awaitCode)).toBe("first")
+    }))
+
+  test("the code is trimmed, matching Go's strings.TrimSpace", () =>
+    withServer(async (server) => {
+      await fetch(`${server.redirectUri}/?code=%20padded%20&state=${STATE}`)
+      expect(await Effect.runPromise(server.awaitCode)).toBe("padded")
+    }))
+
+  test("the port is released when the scope closes", async () => {
+    const uri = await Effect.runPromise(
+      Effect.map(acquireLoopbackServer(STATE), (server) => server.redirectUri).pipe(Effect.scoped)
+    )
+    // A closed listener refuses connections rather than answering.
+    const result = await fetch(`${uri}/?state=${STATE}&code=x`).then(
+      () => "answered",
+      () => "refused"
+    )
+    expect(result).toBe("refused")
+  })
+
+  test("Deferred.doneUnsafe reports false on a second completion (channel semantics)", () => {
+    const deferred = Deferred.makeUnsafe()
+    expect(Deferred.doneUnsafe(deferred, Effect.succeed("a"))).toBe(true)
+    expect(Deferred.doneUnsafe(deferred, Effect.succeed("b"))).toBe(false)
+  })
+})
diff --git a/src/impl/oauthServer.ts b/src/impl/oauthServer.ts
index ca14f9a..d0e420d 100644
--- a/src/impl/oauthServer.ts
+++ b/src/impl/oauthServer.ts
@@ -1,2 +1,138 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * The ephemeral loopback callback server for the OAuth 2.0 authorization-code
+ * flow.
+ *
+ * This is the ONE sanctioned `Bun.*` import outside `main.ts`. `BunHttpServer`
+ * does not expose the OS-assigned ephemeral port ergonomically, and the port is
+ * load-bearing here: it becomes the `redirect_uri` that Google echoes back and
+ * that the token exchange must repeat byte-for-byte.
+ *
+ * Behavioral contract (internal/oauth/oauth.go, handler registered on "/"):
+ *
+ *   1. `state` mismatch -> HTTP 400, plain text, and the flow KEEPS WAITING.
+ *      This is the robustness-critical branch: a favicon probe from the browser
+ *      or a port scanner hitting the loopback port must not be able to abort a
+ *      login that is still in flight.
+ *   2. `error` param present -> 400 and the flow resolves with that OAuth error.
+ *   3. `code` missing/blank  -> 400 and the flow resolves with an operational error.
+ *   4. otherwise             -> 200 text/html and the flow resolves with the code.
+ *
+ * Go's result channel is buffered size 1 with non-blocking sends, so only the
+ * first resolution wins and later callbacks are ignored. `Deferred.doneUnsafe`
+ * has exactly that semantics (it returns `false` when already completed).
+ *
+ * The 400 bodies reproduce Go's `http.Error` byte-for-byte: the message plus a
+ * trailing newline, `Content-Type: text/plain; charset=utf-8`, and
+ * `X-Content-Type-Options: nosniff`. Verified against a real `httptest` server.
+ */
+
+import { Deferred, Effect, type Scope } from "effect"
+import { OAuthError, OperationalError } from "../domain/errors.ts"
+
+/** Go `http.Error` bodies — the trailing newline is part of the response. */
+export const STATE_MISMATCH_BODY = "OAuth state did not match. You can close this window.\n"
+export const NOT_GRANTED_BODY = "Authorization was not granted. You can close this window.\n"
+export const MISSING_CODE_BODY =
+  "The OAuth callback did not include a code. You can close this window.\n"
+
+/** The success page, byte-exact. */
+export const SUCCESS_BODY =
+  "oytc authorized" +
+  "
Authorization complete. You can close this window and return to oytc.
"
+
+export const MISSING_CODE_MESSAGE = "OAuth callback did not include an authorization code"
+
+export interface LoopbackServer {
+  readonly port: number
+  /** `http://127.0.0.1:` — NO trailing slash and NO path, exactly as Go builds it. */
+  readonly redirectUri: string
+  /** Resolves once, with the authorization code or the failure that ended the flow. */
+  readonly awaitCode: Effect.Effect
+}
+
+const goHttpError = (body: string): Response =>
+  new Response(body, {
+    status: 400,
+    headers: {
+      "Content-Type": "text/plain; charset=utf-8",
+      "X-Content-Type-Options": "nosniff"
+    }
+  })
+
+const describe = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause))
+
+/**
+ * Starts the loopback listener on an ephemeral port and stops it when the
+ * surrounding scope closes. `state` is the CSRF value the callback must echo.
+ */
+export const acquireLoopbackServer = (
+  state: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const deferred = Deferred.makeUnsafe()
+
+    const handle = (request: Request): Response => {
+      // The handler answers on EVERY path, matching Go's mux pattern "/".
+      const query = new URL(request.url).searchParams
+
+      if (query.get("state") !== state) {
+        return goHttpError(STATE_MISMATCH_BODY)
+      }
+
+      const errorCode = query.get("error") ?? ""
+      if (errorCode !== "") {
+        Deferred.doneUnsafe(
+          deferred,
+          Effect.fail(
+            new OAuthError({
+              httpStatus: 0,
+              code: errorCode,
+              description: query.get("error_description") ?? ""
+            })
+          )
+        )
+        return goHttpError(NOT_GRANTED_BODY)
+      }
+
+      const code = (query.get("code") ?? "").trim()
+      if (code === "") {
+        Deferred.doneUnsafe(
+          deferred,
+          Effect.fail(new OperationalError({ message: MISSING_CODE_MESSAGE }))
+        )
+        return goHttpError(MISSING_CODE_BODY)
+      }
+
+      Deferred.doneUnsafe(deferred, Effect.succeed(code))
+      return new Response(SUCCESS_BODY, {
+        status: 200,
+        headers: { "Content-Type": "text/html; charset=utf-8" }
+      })
+    }
+
+    const server = yield* Effect.acquireRelease(
+      Effect.try({
+        try: () =>
+          Bun.serve({
+            port: 0,
+            hostname: "127.0.0.1",
+            fetch: handle
+          }),
+        catch: (cause) =>
+          new OperationalError({
+            message: `start OAuth callback listener: ${describe(cause)}`,
+            cause
+          })
+      }),
+      (running) => Effect.promise(async () => await running.stop())
+    )
+
+    // `Bun.serve` types `port` as optional, but a listening TCP server always
+    // has one; the OS assigns it because we asked for port 0.
+    const port = server.port ?? 0
+    return {
+      port,
+      redirectUri: `http://127.0.0.1:${port}`,
+      awaitCode: Deferred.await(deferred)
+    }
+  })
diff --git a/src/impl/platformMatrix.test.ts b/src/impl/platformMatrix.test.ts
new file mode 100644
index 0000000..62de5f8
--- /dev/null
+++ b/src/impl/platformMatrix.test.ts
@@ -0,0 +1,152 @@
+import { describe, expect, test } from "bun:test"
+import {
+  archiveExtension,
+  assertBuildablePlatform,
+  assetName,
+  binaryName,
+  bunTarget,
+  bunTargets,
+  hostPlatform,
+  isSupportedPlatform,
+  SUPPORTED_PLATFORMS,
+  UnsupportedPlatformError
+} from "./platformMatrix.ts"
+
+/** Port of Go's `TestAssetName` — unchanged, byte for byte. */
+describe("TestAssetName", () => {
+  test("linux/arm64 is a tar.gz", () => {
+    expect(assetName("v0.1.0", "linux", "arm64")).toBe("oytc_v0.1.0_linux_arm64.tar.gz")
+  })
+
+  test("windows/amd64 is a zip", () => {
+    expect(assetName("v0.1.0", "windows", "amd64")).toBe("oytc_v0.1.0_windows_amd64.zip")
+  })
+})
+
+describe("assetName", () => {
+  test("windows/arm64 hard-fails — the platform was dropped in the TS port", () => {
+    expect(() => assetName("v0.1.0", "windows", "arm64")).toThrow(UnsupportedPlatformError)
+    expect(() => assetName("v0.1.0", "windows", "arm64")).toThrow(/windows\/arm64/)
+    expect(() => assetName("v0.1.0", "windows", "arm64")).toThrow(/amd64 build instead/)
+  })
+
+  test("the tag is interpolated verbatim, leading v included", () => {
+    expect(assetName("v1.2.3-rc.1", "darwin", "arm64")).toBe(
+      "oytc_v1.2.3-rc.1_darwin_arm64.tar.gz"
+    )
+  })
+
+  test("an unknown-but-not-dropped pair still formats, so the missing-asset error wins", () => {
+    // Matches Go: `TestUpdateMissingAssetForPlatform` sets GOARCH=riscv64 and
+    // expects the release lookup to fail, not the name computation.
+    expect(assetName("v0.2.0", "linux", "riscv64")).toBe("oytc_v0.2.0_linux_riscv64.tar.gz")
+  })
+
+  test("every supported platform produces the documented name", () => {
+    expect(SUPPORTED_PLATFORMS.map((p) => assetName("v0.1.0", p.goos, p.goarch))).toEqual([
+      "oytc_v0.1.0_linux_amd64.tar.gz",
+      "oytc_v0.1.0_linux_arm64.tar.gz",
+      "oytc_v0.1.0_darwin_amd64.tar.gz",
+      "oytc_v0.1.0_darwin_arm64.tar.gz",
+      "oytc_v0.1.0_windows_amd64.zip"
+    ])
+  })
+})
+
+describe("archiveExtension / binaryName", () => {
+  test("windows gets zip and oytc.exe", () => {
+    expect(archiveExtension("windows")).toBe("zip")
+    expect(binaryName("windows")).toBe("oytc.exe")
+  })
+
+  test("everything else gets tar.gz and oytc", () => {
+    for (const goos of ["linux", "darwin", "freebsd"]) {
+      expect(archiveExtension(goos)).toBe("tar.gz")
+      expect(binaryName(goos)).toBe("oytc")
+    }
+  })
+})
+
+describe("hostPlatform — process.platform/arch -> goos/goarch", () => {
+  test("maps the five published hosts", () => {
+    expect(hostPlatform("linux", "x64")).toEqual({ goos: "linux", goarch: "amd64" })
+    expect(hostPlatform("linux", "arm64")).toEqual({ goos: "linux", goarch: "arm64" })
+    expect(hostPlatform("darwin", "x64")).toEqual({ goos: "darwin", goarch: "amd64" })
+    expect(hostPlatform("darwin", "arm64")).toEqual({ goos: "darwin", goarch: "arm64" })
+    expect(hostPlatform("win32", "x64")).toEqual({ goos: "windows", goarch: "amd64" })
+  })
+
+  test("win32 + arm64 hard-fails rather than requesting a nonexistent asset", () => {
+    expect(() => hostPlatform("win32", "arm64")).toThrow(UnsupportedPlatformError)
+    expect(() => hostPlatform("win32", "arm64")).toThrow(/windows\/arm64/)
+  })
+
+  test("an unknown platform or arch names the host, not an asset", () => {
+    expect(() => hostPlatform("aix", "x64")).toThrow(/aix\/x64/)
+    expect(() => hostPlatform("linux", "riscv64")).toThrow(/linux\/riscv64/)
+    expect(() => hostPlatform("linux", "ia32")).toThrow(UnsupportedPlatformError)
+  })
+
+  test("the error carries the goos/goarch it could resolve", () => {
+    try {
+      hostPlatform("win32", "arm64")
+      throw new Error("expected a throw")
+    } catch (error) {
+      expect(error).toBeInstanceOf(UnsupportedPlatformError)
+      expect((error as UnsupportedPlatformError).goos).toBe("windows")
+      expect((error as UnsupportedPlatformError).goarch).toBe("arm64")
+    }
+  })
+})
+
+describe("assertBuildablePlatform", () => {
+  test("passes for every supported platform", () => {
+    for (const p of SUPPORTED_PLATFORMS) {
+      expect(() => assertBuildablePlatform(p.goos, p.goarch)).not.toThrow()
+    }
+  })
+
+  test("throws only for the dropped pair", () => {
+    expect(() => assertBuildablePlatform("windows", "arm64")).toThrow()
+    expect(() => assertBuildablePlatform("linux", "riscv64")).not.toThrow()
+  })
+})
+
+describe("isSupportedPlatform", () => {
+  test("windows/arm64 is not supported; windows/amd64 is", () => {
+    expect(isSupportedPlatform("windows", "arm64")).toBe(false)
+    expect(isSupportedPlatform("windows", "amd64")).toBe(true)
+  })
+})
+
+/**
+ * Mapping (b): bun tokens are BUILD-time only. If one of these ever leaks into
+ * `assetName` the release stops being self-updatable, so they are asserted to
+ * be different strings from the goarch tokens.
+ */
+describe("bunTarget — goos/goarch -> bun --target", () => {
+  test("the five compile targets", () => {
+    expect(bunTargets()).toEqual([
+      "bun-linux-x64",
+      "bun-linux-arm64",
+      "bun-darwin-x64",
+      "bun-darwin-arm64",
+      "bun-windows-x64"
+    ])
+  })
+
+  test("amd64 becomes x64 for bun but stays amd64 in asset names", () => {
+    expect(bunTarget("linux", "amd64")).toBe("bun-linux-x64")
+    expect(assetName("v1.0.0", "linux", "amd64")).toContain("_amd64.")
+    expect(assetName("v1.0.0", "linux", "amd64")).not.toContain("x64")
+  })
+
+  test("arm64 is spelled the same in both mappings", () => {
+    expect(bunTarget("darwin", "arm64")).toBe("bun-darwin-arm64")
+    expect(assetName("v1.0.0", "darwin", "arm64")).toContain("_arm64.")
+  })
+
+  test("there is no bun-windows-arm64 target in the matrix", () => {
+    expect(bunTargets()).not.toContain("bun-windows-arm64")
+  })
+})
diff --git a/src/impl/platformMatrix.ts b/src/impl/platformMatrix.ts
index ca14f9a..7ab8d3f 100644
--- a/src/impl/platformMatrix.ts
+++ b/src/impl/platformMatrix.ts
@@ -1,2 +1,162 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * THE PLATFORM MATRIX. **[MATRIX]**
+ *
+ * Two mappings live here and must never be confused:
+ *
+ *   (a) `process.platform` / `process.arch` -> Go's `GOOS` / `GOARCH` tokens.
+ *       These are the tokens baked into RELEASE ASSET NAMES. They are frozen:
+ *       every oytc already installed in the world computes its own update
+ *       asset name from them, so renaming `amd64` to `x64` would strand every
+ *       existing client. The Go binary is gone; the names it minted are not.
+ *
+ *   (b) Go's `GOOS` / `GOARCH` tokens -> `bun build --compile --target` tokens
+ *       (`bun-linux-x64`, ...). A BUILD-TIME concern only; a bun token must
+ *       never reach an asset name.
+ *
+ * `scripts/package.sh`, `site/install.sh`, `site/install.ps1` and the CI
+ * workflows hardcode the same naming; `.depot/workflows/ci.yml` greps this
+ * file for the literal `oytc_${tag}_${goos}_${goarch}` template in
+ * `assetName` below to prove the three sources still agree. Do not reformat
+ * that template literal.
+ */
+
+/** Go `GOOS` tokens the project publishes for. */
+export type Goos = "linux" | "darwin" | "windows"
+
+/** Go `GOARCH` tokens the project publishes for. */
+export type Goarch = "amd64" | "arm64"
+
+export interface Platform {
+  readonly goos: Goos
+  readonly goarch: Goarch
+}
+
+/** (a) `process.platform` -> `GOOS`. */
+const GOOS_BY_NODE_PLATFORM: Readonly> = {
+  linux: "linux",
+  darwin: "darwin",
+  win32: "windows"
+}
+
+/** (a) `process.arch` -> `GOARCH`. */
+const GOARCH_BY_NODE_ARCH: Readonly> = {
+  x64: "amd64",
+  arm64: "arm64"
+}
+
+/** (b) `GOOS` -> the OS token in a `bun --target` triple. */
+const BUN_OS_BY_GOOS: Readonly> = {
+  linux: "linux",
+  darwin: "darwin",
+  windows: "windows"
+}
+
+/** (b) `GOARCH` -> the arch token in a `bun --target` triple. */
+const BUN_ARCH_BY_GOARCH: Readonly> = {
+  amd64: "x64",
+  arm64: "arm64"
+}
+
+/**
+ * The five platforms the project builds and publishes.
+ *
+ * `windows/arm64` was published by the Go implementation and is deliberately
+ * NOT here: `bun build --compile` has no `bun-windows-arm64` target. ARM64
+ * Windows runs the `windows/amd64` build under emulation instead.
+ */
+export const SUPPORTED_PLATFORMS: ReadonlyArray = [
+  { goos: "linux", goarch: "amd64" },
+  { goos: "linux", goarch: "arm64" },
+  { goos: "darwin", goarch: "amd64" },
+  { goos: "darwin", goarch: "arm64" },
+  { goos: "windows", goarch: "amd64" }
+]
+
+/**
+ * Platform pairs the Go implementation published but this one dropped.
+ *
+ * These hard-fail with a specific remedy rather than the generic
+ * "release has no asset for this platform", because an already-installed
+ * client WILL ask for one and deserves to be told why it vanished. Any other
+ * unknown pair (say `linux/riscv64`) is formatted verbatim into an asset name
+ * and fails later with the ordinary missing-asset error, exactly as the Go
+ * updater did — `TestUpdateMissingAssetForPlatform` depends on that.
+ */
+const DROPPED: ReadonlyArray = [{ goos: "windows", goarch: "arm64" }]
+
+const isDropped = (goos: string, goarch: string): boolean =>
+  DROPPED.some((p) => p.goos === goos && p.goarch === goarch)
+
+export class UnsupportedPlatformError extends Error {
+  override readonly name = "UnsupportedPlatformError"
+  readonly goos: string
+  readonly goarch: string
+  constructor(goos: string, goarch: string, message: string) {
+    super(message)
+    this.goos = goos
+    this.goarch = goarch
+  }
+}
+
+const droppedMessage = (goos: string, goarch: string): string =>
+  `oytc is not published for ${goos}/${goarch}; install the ${goos}/amd64 build instead, which runs under emulation on ARM64 Windows`
+
+/**
+ * Throws when the pair is one this project deliberately stopped publishing.
+ * Call it early so the failure precedes any network traffic.
+ */
+export const assertBuildablePlatform = (goos: string, goarch: string): void => {
+  if (isDropped(goos, goarch)) {
+    throw new UnsupportedPlatformError(goos, goarch, droppedMessage(goos, goarch))
+  }
+}
+
+export const isSupportedPlatform = (goos: string, goarch: string): boolean =>
+  SUPPORTED_PLATFORMS.some((p) => p.goos === goos && p.goarch === goarch)
+
+/** `zip` on Windows, `tar.gz` everywhere else. */
+export const archiveExtension = (goos: string): string => (goos === "windows" ? "zip" : "tar.gz")
+
+/** The single file at the archive root. */
+export const binaryName = (goos: string): string => (goos === "windows" ? "oytc.exe" : "oytc")
+
+/**
+ * The release asset filename for a tag and platform,
+ * e.g. `oytc_v0.1.0_linux_amd64.tar.gz`. The tag INCLUDES its leading `v`.
+ *
+ * Throws `UnsupportedPlatformError` for a dropped platform (`windows/arm64`).
+ */
+export const assetName = (tag: string, goos: string, goarch: string): string => {
+  assertBuildablePlatform(goos, goarch)
+  const ext = archiveExtension(goos)
+  return `oytc_${tag}_${goos}_${goarch}.${ext}`
+}
+
+/** The `bun build --compile --target=` token for a published platform. */
+export const bunTarget = (goos: Goos, goarch: Goarch): string =>
+  `bun-${BUN_OS_BY_GOOS[goos]}-${BUN_ARCH_BY_GOARCH[goarch]}`
+
+/** Every `bun --target` token the release build must produce, in matrix order. */
+export const bunTargets = (): ReadonlyArray =>
+  SUPPORTED_PLATFORMS.map((p) => bunTarget(p.goos, p.goarch))
+
+/**
+ * Map the running process onto `GOOS`/`GOARCH`.
+ *
+ * Throws `UnsupportedPlatformError` when the host is not a platform oytc is
+ * published for, so the failure names the host rather than an asset that was
+ * never going to exist.
+ */
+export const hostPlatform = (platform: string, arch: string): Platform => {
+  const goos = GOOS_BY_NODE_PLATFORM[platform]
+  const goarch = GOARCH_BY_NODE_ARCH[arch]
+  if (goos === undefined || goarch === undefined) {
+    throw new UnsupportedPlatformError(
+      goos ?? platform,
+      goarch ?? arch,
+      `oytc does not publish a build for ${platform}/${arch}`
+    )
+  }
+  assertBuildablePlatform(goos, goarch)
+  return { goos, goarch }
+}
diff --git a/src/impl/prompts.test.ts b/src/impl/prompts.test.ts
new file mode 100644
index 0000000..c8e08b4
--- /dev/null
+++ b/src/impl/prompts.test.ts
@@ -0,0 +1,320 @@
+/**
+ * Tests for the shared stdin reader.
+ *
+ * Go has no dedicated test for `readSecret` — it is covered indirectly through
+ * `internal/cli/app_test.go`, which swaps `app.ReadSecret` for a stub. These
+ * tests therefore target the three properties the port must not regress:
+ * one shared reader, no TTY requirement, prompts on stderr.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Cause, Effect, Exit, Redacted } from "effect"
+import { makePromptsWith, testPromptIO, type PromptIO } from "./prompts.ts"
+import { OperationalError } from "../domain/errors.ts"
+
+const run = (effect: Effect.Effect): Promise => Effect.runPromise(effect)
+
+const exitOf = (effect: Effect.Effect): Promise> =>
+  Effect.runPromise(Effect.exit(effect))
+
+const messageOf = (exit: Exit.Exit): string => {
+  if (exit._tag !== "Failure") return ""
+  const error = Cause.findErrorOption(exit.cause)
+  return error._tag === "Some" && error.value instanceof OperationalError ? error.value.message : ""
+}
+
+/** Control bytes the raw-mode loop has to interpret itself. */
+const DEL = String.fromCharCode(0x7f)
+const BACKSPACE = String.fromCharCode(0x08)
+const CTRL_C = String.fromCharCode(0x03)
+const CR = String.fromCharCode(0x0d)
+
+describe("shared stdin reader", () => {
+  test("consecutive prompts see consecutive lines from one piped stream", async () => {
+    // The whole reason Go keeps one bufio.Reader: reading the client ID pulls
+    // the secret's bytes into the buffer too. A fresh reader would lose them.
+    const io = testPromptIO("client-id\nclient-secret\n")
+    const prompts = makePromptsWith(io)
+
+    const id = await run(prompts.readLine("OAuth client ID: "))
+    const secret = await run(prompts.readSecret("OAuth client secret: "))
+
+    expect(id).toBe("client-id")
+    expect(Redacted.value(secret)).toBe("client-secret")
+  })
+
+  test("three prompts in a row stay in order", async () => {
+    const io = testPromptIO("one\ntwo\nthree\n")
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("a: "))).toBe("one")
+    expect(Redacted.value(await run(prompts.readSecret("b: ")))).toBe("two")
+    expect(await run(prompts.readLine("c: "))).toBe("three")
+  })
+
+  test("a one-byte-at-a-time descriptor produces the same lines", async () => {
+    const io = testPromptIO("client-id\nclient-secret\n", { chunkSize: 1 })
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("id: "))).toBe("client-id")
+    expect(Redacted.value(await run(prompts.readSecret("secret: ")))).toBe("client-secret")
+  })
+
+  test("CRLF input has its terminator stripped", async () => {
+    const io = testPromptIO(`client-id${CR}\nsecret${CR}\n`)
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("id: "))).toBe("client-id")
+    expect(Redacted.value(await run(prompts.readSecret("s: ")))).toBe("secret")
+  })
+
+  test("a run of CR/LF is stripped, but an interior CR is kept", async () => {
+    // Verified against Go: strings.TrimRight(line, "\r\n") on "abc\r\r\n"
+    // yields "abc", and "a\rb\n" yields "a\rb".
+    const io = testPromptIO(`abc${CR}${CR}\na${CR}b\n`)
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("x: "))).toBe("abc")
+    expect(await run(prompts.readLine("y: "))).toBe(`a${CR}b`)
+  })
+
+  test("UTF-8 survives a chunk boundary mid-codepoint", async () => {
+    // Split one byte at a time, so the decoder sees partial sequences.
+    const io = testPromptIO("héllo→\n", { chunkSize: 1 })
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("x: "))).toBe("héllo→")
+  })
+})
+
+describe("readSecret", () => {
+  test("works when stdin is a pipe — no TTY required", async () => {
+    // `secret-manager | oytc login` is a documented workflow.
+    const io = testPromptIO("piped-api-key\n", { isInputTTY: false })
+    const prompts = makePromptsWith(io)
+    const secret = await run(prompts.readSecret("YouTube Data API key: "))
+    expect(Redacted.value(secret)).toBe("piped-api-key")
+  })
+
+  test("EOF without a trailing newline is not an error", async () => {
+    // Go: `if err != nil && !errors.Is(err, io.EOF) { return "", err }`.
+    const io = testPromptIO("no-newline-at-end")
+    const prompts = makePromptsWith(io)
+    expect(Redacted.value(await run(prompts.readSecret("key: ")))).toBe("no-newline-at-end")
+  })
+
+  test("an empty line at EOF yields an empty secret, not a failure", async () => {
+    // The caller turns "" into the usage error "API key cannot be empty".
+    const io = testPromptIO("")
+    const prompts = makePromptsWith(io)
+    expect(Redacted.value(await run(prompts.readSecret("key: ")))).toBe("")
+  })
+
+  test("the prompt goes to stderr and a newline follows the read", async () => {
+    const io = testPromptIO("s3cret\n")
+    const prompts = makePromptsWith(io)
+    await run(prompts.readSecret("YouTube Data API key: "))
+    expect(io.errorOutput()).toBe("YouTube Data API key: \n")
+  })
+
+  test("on a TTY, echo is suppressed and restored around the read", async () => {
+    const io = testPromptIO("hunter2\n", { isInputTTY: true, chunkSize: 1 })
+    const prompts = makePromptsWith(io)
+    expect(Redacted.value(await run(prompts.readSecret("pw: ")))).toBe("hunter2")
+    expect(io.rawModeCalls()).toEqual([true, false])
+  })
+
+  test("raw mode handles backspace, which the line driver would normally do", async () => {
+    // Raw mode clears ICANON, so DEL and BS become our job.
+    const io = testPromptIO(`abc${DEL}${BACKSPACE}d\n`, { isInputTTY: true, chunkSize: 1 })
+    const prompts = makePromptsWith(io)
+    expect(Redacted.value(await run(prompts.readSecret("pw: ")))).toBe("ad")
+  })
+
+  test("raw mode ends the line on a bare CR", async () => {
+    const io = testPromptIO(`hunter2${CR}rest\n`, { isInputTTY: true, chunkSize: 1 })
+    const prompts = makePromptsWith(io)
+    expect(Redacted.value(await run(prompts.readSecret("pw: ")))).toBe("hunter2")
+  })
+
+  test("EOF mid-secret on a TTY returns what was typed, with no error", async () => {
+    const io = testPromptIO("partial", { isInputTTY: true, chunkSize: 1 })
+    const prompts = makePromptsWith(io)
+    expect(Redacted.value(await run(prompts.readSecret("pw: ")))).toBe("partial")
+    expect(io.rawModeCalls()).toEqual([true, false])
+  })
+
+  test("Ctrl-C in raw mode interrupts rather than returning a partial secret", async () => {
+    // Raw mode also clears ISIG, which Go's termios tweak deliberately kept,
+    // so 0x03 has to be turned back into an interrupt by hand (exit 130).
+    const io = testPromptIO(`part${CTRL_C}ial\n`, { isInputTTY: true, chunkSize: 1 })
+    const prompts = makePromptsWith(io)
+    const exit = await exitOf(prompts.readSecret("pw: "))
+    expect(exit._tag).toBe("Failure")
+    if (exit._tag === "Failure") expect(Cause.hasInterrupts(exit.cause)).toBe(true)
+    // Raw mode is restored even on the way out.
+    expect(io.rawModeCalls()).toEqual([true, false])
+  })
+
+  test("a partly-buffered CRLF line does not smuggle a CR into the secret", async () => {
+    // The previous prompt's read pulled "sec\r" in but not the LF, so the raw
+    // loop starts with buffered bytes. Those must go through the same CR/LF
+    // rules as typed bytes — Go's pipe path trims with TrimRight and its TTY
+    // path drops CR in readPasswordLine, so neither yields "sec\r".
+    const io = testPromptIO(`id\nsec${CR}`, { isInputTTY: true })
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("id: "))).toBe("id")
+    expect(Redacted.value(await run(prompts.readSecret("pw: ")))).toBe("sec")
+  })
+
+  test("buffered bytes before a typed tail still edit correctly in raw mode", async () => {
+    const io = testPromptIO(`id\nabX${BACKSPACE}c\n`, { isInputTTY: true, chunkSize: 5 })
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("id: "))).toBe("id")
+    expect(Redacted.value(await run(prompts.readSecret("pw: ")))).toBe("abc")
+  })
+
+  test("a TTY still yields already-buffered bytes without entering raw mode", async () => {
+    // The previous prompt's read pulled this line in; nothing left to hide.
+    const io = testPromptIO("id\nsecret\n", { isInputTTY: true })
+    const prompts = makePromptsWith(io)
+    await run(prompts.readLine("id: "))
+    expect(Redacted.value(await run(prompts.readSecret("pw: ")))).toBe("secret")
+    expect(io.rawModeCalls()).toEqual([])
+  })
+
+  test("the secret is Redacted, so an accidental log prints ", async () => {
+    const io = testPromptIO("AIzaTOPSECRET\n")
+    const prompts = makePromptsWith(io)
+    const secret = await run(prompts.readSecret("key: "))
+    expect(String(secret)).not.toContain("AIzaTOPSECRET")
+    expect(`${secret}`).toContain("redacted")
+  })
+})
+
+describe("readLine", () => {
+  test("writes the prompt to stderr and echoes nothing itself", async () => {
+    const io = testPromptIO("value\n")
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("OAuth client ID: "))).toBe("value")
+    expect(io.errorOutput()).toBe("OAuth client ID: ")
+  })
+
+  test("a partial read at EOF is tolerated when it produced a value", async () => {
+    // Go: `if err != nil && strings.TrimSpace(clientID) == "" { return err }`.
+    const io = testPromptIO("trailing-value-no-newline")
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("id: "))).toBe("trailing-value-no-newline")
+  })
+
+  test("EOF with nothing read fails", async () => {
+    const io = testPromptIO("")
+    const prompts = makePromptsWith(io)
+    const exit = await exitOf(prompts.readLine("id: "))
+    expect(exit._tag).toBe("Failure")
+    expect(messageOf(exit)).toBe("EOF")
+  })
+
+  test("EOF with only whitespace read fails — Go trims before the check", async () => {
+    const io = testPromptIO("   ")
+    const prompts = makePromptsWith(io)
+    expect(messageOf(await exitOf(prompts.readLine("id: ")))).toBe("EOF")
+  })
+
+  test("surrounding whitespace is left to the caller to trim", async () => {
+    // Go trimmed at the call site, not in the reader.
+    const io = testPromptIO("  spaced  \n")
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("id: "))).toBe("  spaced  ")
+  })
+
+  test("a blank line before EOF is a value, not an EOF failure", async () => {
+    const io = testPromptIO("\nsecond\n")
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.readLine("id: "))).toBe("")
+    expect(await run(prompts.readLine("id: "))).toBe("second")
+  })
+})
+
+describe("confirm", () => {
+  test.each([
+    ["y\n", true],
+    ["yes\n", true],
+    ["Y\n", true],
+    ["YES\n", true],
+    ["  yes  \n", true],
+    ["n\n", false],
+    ["no\n", false],
+    ["nope\n", false],
+    ["\n", false],
+    ["yep\n", false],
+    ["ye\n", false]
+  ])("%j -> %s", async (input, expected) => {
+    const io = testPromptIO(input)
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.confirm("Continue? [y/N] "))).toBe(expected)
+  })
+
+  test("writes the block to stderr, then a newline after the read", async () => {
+    const block =
+      "Install the bundled oytc agent skill?\nDestination: /tmp/oytc\n" +
+      "Permission requested: create this directory and write SKILL.md plus references.\n" +
+      "Continue? [y/N] "
+    const io = testPromptIO("y\n")
+    const prompts = makePromptsWith(io)
+    await run(prompts.confirm(block))
+    expect(io.errorOutput()).toBe(`${block}\n`)
+  })
+
+  test("a bare EOF is a read failure, matching Go's zero-bytes check", async () => {
+    const io = testPromptIO("")
+    const prompts = makePromptsWith(io)
+    const exit = await exitOf(prompts.confirm("Continue? [y/N] "))
+    expect(exit._tag).toBe("Failure")
+    expect(messageOf(exit)).toBe("EOF")
+    // Go returned before printing the trailing newline on this path.
+    expect(io.errorOutput()).toBe("Continue? [y/N] ")
+  })
+
+  test("a lone CR at EOF cancels rather than failing — Go checks the RAW length", async () => {
+    // skills.go gates on `len(answer) == 0`, i.e. on the untrimmed string.
+    // Verified against Go: input "\r" -> cancelled (answer="\r", err=EOF).
+    // Checking the trimmed line instead would turn this into
+    // `read confirmation: EOF` and change the exit code.
+    const io = testPromptIO(CR)
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.confirm("Continue? [y/N] "))).toBe(false)
+  })
+
+  test("whitespace-only input at EOF cancels, it is not a read failure", async () => {
+    // Go: input "   " -> cancelled (answer="   ", err=EOF).
+    const io = testPromptIO("   ")
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.confirm("Continue? [y/N] "))).toBe(false)
+  })
+
+  test("'yes' with no trailing newline still confirms", async () => {
+    // Go tolerated the EOF error because bytes were read.
+    const io = testPromptIO("yes")
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.confirm("Continue? [y/N] "))).toBe(true)
+  })
+
+  test("a declined confirmation leaves the rest of stdin for the next prompt", async () => {
+    const io = testPromptIO("no\nleftover\n")
+    const prompts = makePromptsWith(io)
+    expect(await run(prompts.confirm("Continue? [y/N] "))).toBe(false)
+    expect(await run(prompts.readLine("next: "))).toBe("leftover")
+  })
+})
+
+describe("host failures", () => {
+  test("a descriptor error surfaces as an OperationalError, not a defect", async () => {
+    const io: PromptIO = {
+      read: () => {
+        throw new Error("EIO: i/o error")
+      },
+      writeError: () => {},
+      isInputTTY: false
+    }
+    const prompts = makePromptsWith(io)
+    expect(messageOf(await exitOf(prompts.readLine("id: ")))).toBe("EIO: i/o error")
+    expect(messageOf(await exitOf(prompts.readSecret("pw: ")))).toBe("EIO: i/o error")
+    expect(messageOf(await exitOf(prompts.confirm("Continue? [y/N] ")))).toBe("EIO: i/o error")
+  })
+})
diff --git a/src/impl/prompts.ts b/src/impl/prompts.ts
index ca14f9a..e8700db 100644
--- a/src/impl/prompts.ts
+++ b/src/impl/prompts.ts
@@ -1,2 +1,373 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `Prompts` — the port of `App.readSecret` / `App.stdinReader` in
+ * `internal/cli/app.go`, plus the confirmation read in `internal/cli/skills.go`.
+ *
+ * Three properties are load-bearing and each one exists because getting it
+ * wrong breaks a documented workflow:
+ *
+ * 1. **ONE shared stdin reader, for every prompt.** `login --oauth` asks for a
+ *    client ID and then a client secret. A buffered read for the first prompt
+ *    routinely pulls the second line into its buffer too; a fresh reader for
+ *    the second prompt would never see those bytes. Go's comment on
+ *    `stdinReader()` says exactly this. The module keeps one byte buffer and
+ *    every prompt drains it before touching the file descriptor.
+ *
+ * 2. **`readSecret` must not require a TTY.** `secret-manager | oytc login` is
+ *    a documented workflow. On a TTY the terminal is put in raw mode so the
+ *    secret is not echoed; on a pipe it is an ordinary line read, and EOF is
+ *    NOT an error there (Go: `if err != nil && !errors.Is(err, io.EOF)`).
+ *    Note the asymmetry with `readLine`, where a read error with an empty
+ *    result IS fatal — that difference is Go's, and it is reproduced.
+ *
+ * 3. **Prompts are written to stderr.** stdout stays clean so
+ *    `oytc ... --format json | jq` keeps working while a prompt is on screen.
+ *
+ * Ownership of the surrounding whitespace, so callers do not double up:
+ *   - `readLine` writes the prompt and nothing else (the terminal echoes the
+ *     user's Enter; a pipe produces no echo, and Go printed nothing either).
+ *   - `readSecret` writes the prompt, then a newline after the read, because
+ *     echo was suppressed and nothing else would end the line.
+ *   - `confirm` writes the block, then a newline after a *successful* read —
+ *     on a read failure Go returned before printing it.
+ *
+ * Error messages carry only the underlying reason ("EOF"), never a prefix.
+ * The command layer adds `read OAuth client ID: `, `read API key: `,
+ * `read confirmation: ` etc., matching Go's `fmt.Errorf("...: %w", err)`.
+ */
+
+import * as fs from "node:fs"
+import { Effect, Layer, Redacted } from "effect"
+import { OperationalError } from "../domain/errors.ts"
+import { Prompts, type PromptsShape } from "../services/index.ts"
+
+const LF = 0x0a
+const CR = 0x0d
+const ETX = 0x03 // Ctrl-C
+const BACKSPACE = 0x08
+const DEL = 0x7f
+
+/** Raised from the raw-mode loop when the user presses Ctrl-C. */
+const INTERRUPTED = Symbol.for("oytc/prompts/interrupted")
+
+/**
+ * The host seam. Production wires this to fds 0 and 2; tests substitute a
+ * scripted buffer so the shared-reader behaviour can be asserted without a
+ * terminal.
+ */
+export interface PromptIO {
+  /** Read up to `size` bytes. An empty result means EOF. Blocking. */
+  readonly read: (size: number) => Uint8Array
+  /** Write to stderr. */
+  readonly writeError: (text: string) => void
+  readonly isInputTTY: boolean
+  /** Present only when the input can suppress echo. */
+  readonly setRawMode?: ((enabled: boolean) => void) | undefined
+}
+
+const CHUNK = 4096
+
+const hostIO = (): PromptIO => {
+  const stdin = process.stdin as unknown as {
+    isTTY?: boolean
+    setRawMode?: (enabled: boolean) => void
+  }
+  const isInputTTY = stdin.isTTY === true
+  return {
+    read: (size) => {
+      const buffer = new Uint8Array(size)
+      for (;;) {
+        try {
+          const read = fs.readSync(0, buffer, 0, size, null)
+          return buffer.subarray(0, read)
+        } catch (error) {
+          const code = (error as { code?: string } | null)?.code
+          // A non-blocking tty has nothing ready yet: wait and ask again.
+          if (code === "EAGAIN") {
+            Bun.sleepSync(5)
+            continue
+          }
+          // Both spellings mean "the descriptor is done".
+          if (code === "EOF" || code === "ENXIO") return new Uint8Array(0)
+          throw error
+        }
+      }
+    },
+    writeError: (text) => {
+      fs.writeSync(2, text)
+    },
+    isInputTTY,
+    setRawMode:
+      isInputTTY && typeof stdin.setRawMode === "function"
+        ? (enabled: boolean) => stdin.setRawMode!(enabled)
+        : undefined
+  }
+}
+
+/** What a line read produced. `endedAtEof` mirrors bufio's trailing `io.EOF`. */
+interface LineRead {
+  /** The line without its terminator. */
+  readonly line: string
+  /**
+   * True when input ended before a `\n` was seen. Go's `bufio.ReadString`
+   * returns `io.EOF` in exactly this case, including when it read partial
+   * data first, so callers reproduce Go's "tolerate the error if we still got
+   * something" logic off this flag.
+   */
+  readonly endedAtEof: boolean
+  /**
+   * Byte count of what `ReadString` returned, terminator INCLUDED.
+   *
+   * `skills.go` gates on `len(answer) == 0`, i.e. on the raw string — so a
+   * lone `"\r"` at EOF is a *cancel* there, not a read failure, even though the
+   * trimmed line is empty. Testing `line.length` instead would turn that into
+   * `read confirmation: EOF`. Verified against Go.
+   */
+  readonly rawLength: number
+}
+
+const decoder = new TextDecoder()
+
+/**
+ * The one buffered reader. Bytes pulled from the descriptor for one prompt
+ * stay here and are handed to the next prompt, which is the entire point.
+ */
+class SharedStdin {
+  private pending: Uint8Array = new Uint8Array(0)
+  private exhausted = false
+
+  constructor(private readonly io: PromptIO) {}
+
+  private take(count: number): Uint8Array {
+    const taken = this.pending.subarray(0, count)
+    this.pending = this.pending.slice(count)
+    return taken
+  }
+
+  private append(chunk: Uint8Array): void {
+    const merged = new Uint8Array(this.pending.length + chunk.length)
+    merged.set(this.pending, 0)
+    merged.set(chunk, this.pending.length)
+    this.pending = merged
+  }
+
+  /** Whether a complete line is already buffered — no descriptor read needed. */
+  private bufferedLineEnd(): number {
+    return this.pending.indexOf(LF)
+  }
+
+  /** Go's `bufio.Reader.ReadString('\n')`, minus the delimiter. */
+  readLine(): LineRead {
+    for (;;) {
+      const end = this.bufferedLineEnd()
+      if (end >= 0) {
+        const raw = this.take(end + 1)
+        return {
+          line: stripTerminator(decoder.decode(raw)),
+          endedAtEof: false,
+          rawLength: raw.length
+        }
+      }
+      if (this.exhausted) {
+        const raw = this.take(this.pending.length)
+        return {
+          line: stripTerminator(decoder.decode(raw)),
+          endedAtEof: true,
+          rawLength: raw.length
+        }
+      }
+      const chunk = this.io.read(CHUNK)
+      if (chunk.length === 0) this.exhausted = true
+      else this.append(chunk)
+    }
+  }
+
+  /**
+   * A line read with echo suppressed.
+   *
+   * Buffered bytes win: if a full line is already in hand there is nothing to
+   * suppress and no reason to touch the terminal. Otherwise the descriptor is
+   * put in raw mode and drained a byte at a time, because raw mode also turns
+   * off the driver's line editing — backspace and Ctrl-C become our job. Go
+   * got line editing for free by clearing only `ECHO` via termios, which Node
+   * and Bun do not expose.
+   */
+  readSecretLine(): LineRead {
+    if (this.bufferedLineEnd() >= 0 || this.io.setRawMode === undefined) return this.readLine()
+
+    const setRawMode = this.io.setRawMode
+    const collected: Array = []
+    setRawMode(true)
+    try {
+      for (;;) {
+        // Bytes an earlier prompt over-read go through the SAME rules as bytes
+        // typed now. Seeding `collected` with them verbatim instead would let a
+        // trailing CR — a CRLF stream whose LF has not arrived yet — end up
+        // inside the secret, which neither Go path produces: the pipe path
+        // trims it with TrimRight and the TTY path drops CR in readPasswordLine.
+        const byte = this.pending.length > 0 ? this.take(1)[0]! : this.readByte()
+        if (byte === undefined) {
+          this.exhausted = true
+          return { line: decodeBytes(collected), endedAtEof: true, rawLength: collected.length }
+        }
+        if (byte === LF || byte === CR) {
+          return {
+            line: decodeBytes(collected),
+            endedAtEof: false,
+            rawLength: collected.length + 1
+          }
+        }
+        if (byte === DEL || byte === BACKSPACE) {
+          collected.pop()
+          continue
+        }
+        // Raw mode cleared ISIG, which Go's termios tweak deliberately kept.
+        // Surface it as an interrupt so the exit code is still 130.
+        if (byte === ETX) throw INTERRUPTED
+        collected.push(byte)
+      }
+    } finally {
+      setRawMode(false)
+    }
+  }
+
+  /** One byte from the descriptor, or `undefined` at EOF. */
+  private readByte(): number | undefined {
+    const chunk = this.io.read(1)
+    return chunk.length === 0 ? undefined : chunk[0]!
+  }
+}
+
+/**
+ * Go's `strings.TrimRight(line, "\r\n")` — it strips a *run* of CR and LF, not
+ * just one terminator, so `"abc\r\r\n"` yields `"abc"`.
+ */
+const stripTerminator = (line: string): string => line.replace(/[\r\n]+$/, "")
+
+const decodeBytes = (bytes: ReadonlyArray): string =>
+  decoder.decode(new Uint8Array(bytes))
+
+/**
+ * Build a `Prompts` implementation over `io`. Every prompt returned by one
+ * call shares a single reader; call this once per process.
+ */
+export const makePromptsWith = (io: PromptIO): PromptsShape => {
+  const stdin = new SharedStdin(io)
+
+  /** Ctrl-C in raw mode unwinds as an Effect interrupt, i.e. exit 130. */
+  const attempt = (thunk: () => A): Effect.Effect =>
+    Effect.suspend(() => {
+      try {
+        return Effect.succeed(thunk())
+      } catch (error) {
+        if (error === INTERRUPTED) return Effect.interrupt
+        return Effect.fail(
+          new OperationalError({
+            message: error instanceof Error ? error.message : String(error),
+            cause: error
+          })
+        )
+      }
+    })
+
+  return {
+    /**
+     * Go's OAuth client-ID prompt: an echoed line read where a read error is
+     * tolerated as long as something non-blank came back with it.
+     */
+    readLine: (prompt) =>
+      attempt(() => {
+        io.writeError(prompt)
+        return stdin.readLine()
+      }).pipe(
+        Effect.flatMap((read) =>
+          read.endedAtEof && read.line.trim() === ""
+            ? Effect.fail(new OperationalError({ message: "EOF" }))
+            : Effect.succeed(read.line)
+        )
+      ),
+
+    /**
+     * Go's `readSecret`: no echo on a TTY, a plain line read on a pipe, and
+     * EOF is never an error. The trailing newline is ours to print because
+     * nothing echoed the user's Enter.
+     */
+    readSecret: (prompt) =>
+      attempt(() => {
+        io.writeError(prompt)
+        const read = stdin.readSecretLine()
+        io.writeError("\n")
+        return Redacted.make(read.line)
+      }),
+
+    /**
+     * Go's `skills install` confirmation. Go built a fresh `bufio.Reader`
+     * here; the shared reader is used instead — strictly safer, and identical
+     * in behaviour because this is the command's only prompt.
+     */
+    confirm: (block) =>
+      attempt(() => {
+        io.writeError(block)
+        return stdin.readLine()
+      }).pipe(
+        Effect.flatMap((read) => {
+          // A read error with zero bytes is fatal; one that still produced
+          // bytes is tolerated. Go printed the trailing newline only after
+          // clearing that check. The check is on the RAW string, terminator
+          // included — a lone "\r" at EOF cancels rather than erroring.
+          if (read.endedAtEof && read.rawLength === 0) {
+            return Effect.fail(new OperationalError({ message: "EOF" }))
+          }
+          io.writeError("\n")
+          const answer = read.line.trim().toLowerCase()
+          return Effect.succeed(answer === "y" || answer === "yes")
+        })
+      )
+  }
+}
+
+export const makePrompts: Effect.Effect = Effect.sync(() =>
+  makePromptsWith(hostIO())
+)
+
+export const PromptsLive = Layer.effect(Prompts, makePrompts)
+
+/**
+ * A scripted `PromptIO` for tests: `input` is delivered in `chunkSize` pieces
+ * so the shared-reader invariant (bytes pulled for one prompt reaching the
+ * next) is actually exercised rather than assumed.
+ */
+export const testPromptIO = (
+  input: string,
+  options?: { readonly isInputTTY?: boolean; readonly chunkSize?: number }
+): PromptIO & {
+  readonly errorOutput: () => string
+  /** Every setRawMode call, so a test can prove echo really was suppressed. */
+  readonly rawModeCalls: () => ReadonlyArray
+} => {
+  const bytes = new TextEncoder().encode(input)
+  const chunkSize = options?.chunkSize ?? CHUNK
+  const written: Array = []
+  const rawModeCalls: Array = []
+  let offset = 0
+  const isInputTTY = options?.isInputTTY ?? false
+  return {
+    read: (size) => {
+      const take = Math.min(size, chunkSize, bytes.length - offset)
+      if (take <= 0) return new Uint8Array(0)
+      const slice = bytes.subarray(offset, offset + take)
+      offset += take
+      return slice
+    },
+    writeError: (text) => {
+      written.push(text)
+    },
+    isInputTTY,
+    setRawMode: isInputTTY
+      ? (enabled: boolean) => {
+          rawModeCalls.push(enabled)
+        }
+      : undefined,
+    errorOutput: () => written.join(""),
+    rawModeCalls: () => rawModeCalls
+  }
+}
diff --git a/src/impl/renderer.test.ts b/src/impl/renderer.test.ts
new file mode 100644
index 0000000..1679c05
--- /dev/null
+++ b/src/impl/renderer.test.ts
@@ -0,0 +1,216 @@
+import { describe, expect, test } from "bun:test"
+import { Effect, Layer, Result, Sink, Stdio } from "effect"
+import type { ListResult } from "../domain/listResult.ts"
+import { parseJson } from "../json/parse.ts"
+import type { JsonObject } from "../json/value.ts"
+import { Renderer, type RenderOptions } from "../services/index.ts"
+import { statusColumns, versionColumns } from "../output/columns.ts"
+import { makeRendererWith, RendererLive, renderObjectText, renderText } from "./renderer.ts"
+
+const obj = (text: string): JsonObject => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as JsonObject
+}
+
+const items = (text: string): ReadonlyArray => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as ReadonlyArray
+}
+
+const listOf = (text: string, nextPageToken = "", requests = 0): ListResult => ({
+  items: items(text),
+  nextPageToken,
+  requests
+})
+
+const opts = (
+  format: RenderOptions["format"],
+  columns: ReadonlyArray = [],
+  noHeader = false
+): RenderOptions => ({ format, columns, noHeader })
+
+/**
+ * Drive the real `RendererLive` through a `Stdio` layer that captures writes,
+ * so the service wiring — not just the pure text builders — is under test.
+ */
+const capture = (
+  use: (renderer: {
+    readonly render: (r: ListResult, o: RenderOptions) => Effect.Effect
+    readonly renderObject: (o: JsonObject, opt: RenderOptions) => Effect.Effect
+  }) => Effect.Effect
+): Promise => {
+  const chunks: Array = []
+  const stdio = Stdio.layerTest({
+    stdout: () =>
+      Sink.forEach((input: string | Uint8Array) =>
+        Effect.sync(() => {
+          chunks.push(typeof input === "string" ? input : new TextDecoder().decode(input))
+        })
+      )
+  })
+  return Effect.gen(function* () {
+    const renderer = yield* Renderer
+    yield* use(renderer)
+    return chunks.join("")
+  }).pipe(
+    Effect.provide(RendererLive.pipe(Layer.provide(stdio))),
+    Effect.runPromise
+  )
+}
+
+describe("Renderer service over Stdio", () => {
+  test("render writes the table to stdout", async () => {
+    const out = await capture((r) =>
+      r.render(listOf('[{"id":"v","snippet":{"title":"T"}}]'), opts("table", ["id", "snippet.title"]))
+    )
+    expect(out).toBe("ID  SNIPPET.TITLE\nv   T\n")
+  })
+
+  test("render writes the json envelope to stdout", async () => {
+    const out = await capture((r) => r.render(listOf('[{"id":"a"}]', "", 2), opts("json")))
+    expect(out).toBe('{\n  "items": [\n    {\n      "id": "a"\n    }\n  ],\n  "requests": 2\n}\n')
+  })
+
+  test("an empty jsonl result writes NOTHING at all", async () => {
+    const out = await capture((r) => r.render(listOf("[]"), opts("jsonl")))
+    expect(out).toBe("")
+  })
+
+  test("an empty table with --no-header writes nothing", async () => {
+    const out = await capture((r) => r.render(listOf("[]"), opts("table", ["id"], true)))
+    expect(out).toBe("")
+  })
+
+  test("renderObject writes a bare object with no envelope", async () => {
+    const out = await capture((r) =>
+      r.renderObject(obj('{"videoId":"abc","permitted":true}'), opts("json"))
+    )
+    expect(out).toBe('{\n  "permitted": true,\n  "videoId": "abc"\n}\n')
+  })
+
+  test("renderObject in table format is a single data row", async () => {
+    const out = await capture((r) =>
+      r.renderObject(obj('{"videoId":"abc","permitted":true}'), opts("table", ["videoId", "permitted"]))
+    )
+    expect(out).toBe("VIDEOID  PERMITTED\nabc      true\n")
+  })
+
+  test("everything is emitted in ONE write (tabwriter flushes once)", async () => {
+    const chunks: Array = []
+    const stdio = Stdio.layerTest({
+      stdout: () =>
+        Sink.forEach((input: string | Uint8Array) =>
+          Effect.sync(() => {
+            chunks.push(typeof input === "string" ? input : new TextDecoder().decode(input))
+          })
+        )
+    })
+    await Effect.gen(function* () {
+      const renderer = yield* Renderer
+      yield* renderer.render(
+        listOf('[{"id":"a"},{"id":"b"},{"id":"c"}]'),
+        opts("table", ["id", "snippet.title"])
+      )
+    }).pipe(Effect.provide(RendererLive.pipe(Layer.provide(stdio))), Effect.runPromise)
+    expect(chunks.length).toBe(1)
+  })
+})
+
+describe("makeRendererWith — write failures propagate", () => {
+  test("a failing sink surfaces the error rather than being swallowed", async () => {
+    const boom = new Error("closed pipe")
+    const renderer = makeRendererWith(() => Effect.fail(boom as never))
+    const exit = await Effect.runPromiseExit(
+      renderer.render(listOf('[{"id":"a"}]'), opts("json"))
+    )
+    expect(exit._tag).toBe("Failure")
+  })
+
+  test("no write is attempted when there is nothing to emit", async () => {
+    let calls = 0
+    const renderer = makeRendererWith(() => {
+      calls++
+      return Effect.void
+    })
+    await Effect.runPromise(renderer.render(listOf("[]"), opts("jsonl")))
+    expect(calls).toBe(0)
+  })
+
+  test("exactly one write for a non-empty render", async () => {
+    let calls = 0
+    const renderer = makeRendererWith(() => {
+      calls++
+      return Effect.void
+    })
+    await Effect.runPromise(renderer.render(listOf('[{"id":"a"}]'), opts("jsonl")))
+    expect(calls).toBe(1)
+  })
+})
+
+describe("renderText dispatch", () => {
+  test.each([
+    ["json", '{\n  "items": [\n    {\n      "id": "a"\n    }\n  ],\n  "requests": 0\n}\n'],
+    ["jsonl", '{"id":"a"}\n'],
+    ["table", "ID\na\n"],
+    ["tsv", "ID\na\n"]
+  ] as const)("%s", (format, want) => {
+    expect(renderText(listOf('[{"id":"a"}]'), opts(format, ["id"]))).toBe(want)
+  })
+
+  test("table and tsv fall back to id,snippet.title when no columns are given", () => {
+    expect(renderText(listOf('[{"id":"v","snippet":{"title":"T"}}]'), opts("table"))).toBe(
+      "ID  SNIPPET.TITLE\nv   T\n"
+    )
+    expect(renderText(listOf('[{"id":"v","snippet":{"title":"T"}}]'), opts("tsv"))).toBe(
+      "ID\tSNIPPET.TITLE\nv\tT\n"
+    )
+  })
+
+  test("json and jsonl ignore --columns entirely", () => {
+    const withCols = renderText(listOf('[{"id":"a","x":"b"}]'), opts("json", ["id"]))
+    const without = renderText(listOf('[{"id":"a","x":"b"}]'), opts("json"))
+    expect(withCols).toBe(without)
+    expect(withCols).toContain('"x": "b"')
+  })
+
+  test("json and jsonl ignore --no-header entirely", () => {
+    expect(renderText(listOf('[{"id":"a"}]'), opts("jsonl", [], true))).toBe(
+      renderText(listOf('[{"id":"a"}]'), opts("jsonl", [], false))
+    )
+  })
+})
+
+describe("renderObjectText dispatch", () => {
+  test("the version payload matches the Go binary", () => {
+    const state = obj(
+      '{"version":"v0.3.3","commit":"699879f7","date":"2026-07-25T05:47:34Z","goVersion":"go1.26.5","os":"darwin","arch":"arm64"}'
+    )
+    expect(renderObjectText(state, opts("json", versionColumns))).toBe(
+      '{\n  "arch": "arm64",\n  "commit": "699879f7",\n  "date": "2026-07-25T05:47:34Z",\n  "goVersion": "go1.26.5",\n  "os": "darwin",\n  "version": "v0.3.3"\n}\n'
+    )
+    expect(renderObjectText(state, opts("tsv", versionColumns))).toBe(
+      "VERSION\tCOMMIT\tDATE\tGOVERSION\tOS\tARCH\n" +
+        "v0.3.3\t699879f7\t2026-07-25T05:47:34Z\tgo1.26.5\tdarwin\tarm64\n"
+    )
+  })
+
+  test("the status payload matches the Go binary", () => {
+    // Captured from `OYTC_CONFIG_DIR=/tmp/p3-cfg oytc status --format tsv` with
+    // no credentials present: absent keys render as empty cells.
+    const state = obj(
+      '{"api_key":{"configured":false,"source":"none"},"oauth":{"configured":false},"path":"/tmp/p3-cfg/auth.json"}'
+    )
+    expect(renderObjectText(state, opts("tsv", statusColumns))).toBe(
+      "PATH\tAPI_KEY.CONFIGURED\tAPI_KEY.SOURCE\tAPI_KEY.FINGERPRINT\tOAUTH.CONFIGURED\tOAUTH.CLIENT_ID\tOAUTH.SCOPES\tOAUTH.EXPIRY\n" +
+        "/tmp/p3-cfg/auth.json\tfalse\tnone\t\tfalse\t\t\t\n"
+    )
+  })
+
+  test("renderObject in table/tsv falls back to id,snippet.title without columns", () => {
+    expect(renderObjectText(obj('{"version":"1.2.3","id":"x"}'), opts("tsv"))).toBe(
+      "ID\tSNIPPET.TITLE\nx\t\n"
+    )
+  })
+})
diff --git a/src/impl/renderer.ts b/src/impl/renderer.ts
index ca14f9a..3d7d9f4 100644
--- a/src/impl/renderer.ts
+++ b/src/impl/renderer.ts
@@ -1,2 +1,108 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Renderer — the `internal/output/output.go` dispatch, writing to stdout.
+ *
+ * `Render` and `RenderObject` in Go both take an `io.Writer`; here the seam is
+ * the Effect `Stdio` service, so tests can capture output with
+ * `Stdio.layerTest` and production gets `BunServices.layer`.
+ *
+ * The whole render is built as one string and written once. That is not just
+ * convenient — Go's tabwriter buffers every row and emits nothing until
+ * `Flush()`, so a single terminal write is the faithful behavior.
+ *
+ * NOTE on the format check: Go's `Render` rejects an unknown format with
+ * `unsupported format %q (use table, json, jsonl, or tsv)`, which `renderResult`
+ * wraps into a UsageError (exit 2). Here `OutputFormat` is a four-member union,
+ * so that branch is unreachable by construction and the exhaustive switch has no
+ * default arm.
+ */
+
+import { Effect, Layer, Stdio, Stream } from "effect"
+import { OperationalError } from "../domain/errors.ts"
+import type { ListResult } from "../domain/listResult.ts"
+import type { JsonObject } from "../json/value.ts"
+import { Renderer, type RendererShape, type RenderOptions } from "../services/index.ts"
+import { fallbackColumns, generateRows } from "../output/columns.ts"
+import { renderJson, renderJsonl, renderObjectJson, renderObjectJsonl } from "../output/jsonOut.ts"
+import { renderTable } from "../output/table.ts"
+import { renderTsv } from "../output/tsv.ts"
+
+/** `renderRows`: the shared table/tsv path, columns fallback included. */
+const rowText = (
+  items: ReadonlyArray,
+  options: RenderOptions,
+  format: "table" | "tsv"
+): string => {
+  const columns = options.columns.length > 0 ? options.columns : fallbackColumns
+  const rows = generateRows(items, columns, options.noHeader)
+  return format === "table" ? renderTable(rows) : renderTsv(rows)
+}
+
+/** The exact bytes `Render` writes for a list result. */
+export const renderText = (result: ListResult, options: RenderOptions): string => {
+  switch (options.format) {
+    case "json":
+      return renderJson(result)
+    case "jsonl":
+      return renderJsonl(result)
+    case "table":
+    case "tsv":
+      return rowText(result.items, options, options.format)
+  }
+}
+
+/** The exact bytes `RenderObject` writes for a single object. */
+export const renderObjectText = (object: JsonObject, options: RenderOptions): string => {
+  switch (options.format) {
+    case "json":
+      return renderObjectJson(object)
+    case "jsonl":
+      return renderObjectJsonl(object)
+    case "table":
+    case "tsv":
+      return rowText([object], options, options.format)
+  }
+}
+
+/**
+ * Build a Renderer over an arbitrary sink. Exported so tests (and any future
+ * non-stdout consumer) can drive the same dispatch without a platform layer.
+ */
+export const makeRendererWith = (
+  write: (text: string) => Effect.Effect
+): RendererShape => ({
+  render: (result, options) => {
+    const text = renderText(result, options)
+    return text === "" ? Effect.void : write(text)
+  },
+  renderObject: (object, options) => {
+    const text = renderObjectText(object, options)
+    return text === "" ? Effect.void : write(text)
+  }
+})
+
+/**
+ * Renderer over the process's stdout.
+ *
+ * A write failure (a closed pipe, most plausibly) surfaces as an
+ * OperationalError / exit 6. Go would have wrapped it into a UsageError and
+ * exited 2, which is an artifact of `renderResult` funnelling every `Render`
+ * error — including I/O ones — through the "unsupported format" path. Exit 6 is
+ * the documented bucket for I/O failure and is the intentional reading here.
+ */
+export const makeRenderer: Effect.Effect = Effect.gen(
+  function* () {
+    const stdio = yield* Stdio.Stdio
+    return makeRendererWith((text) =>
+      Stream.run(Stream.make(text), stdio.stdout()).pipe(
+        Effect.catch((cause) =>
+          Effect.fail(new OperationalError({ message: "could not write output", cause }))
+        )
+      )
+    )
+  }
+)
+
+export const RendererLive: Layer.Layer = Layer.effect(
+  Renderer,
+  makeRenderer
+)
diff --git a/src/impl/resolveChannel.test.ts b/src/impl/resolveChannel.test.ts
new file mode 100644
index 0000000..68cfb8a
--- /dev/null
+++ b/src/impl/resolveChannel.test.ts
@@ -0,0 +1,481 @@
+/**
+ * Channel-resolution tests.
+ *
+ * Ported from `internal/youtube/client_test.go`:
+ *   TestResolveChannelHandleAndURL
+ *
+ * The classification table below is a GOLDEN CORPUS captured by running each
+ * input through the real Go `parseChannelReference` (Go 1.26.5, `go run`), not
+ * from reading the spec. The full corpus — 4,497 structured combinations plus
+ * 11,398 random fuzz strings — was diffed against this implementation and
+ * matched on every row; these are the readable representatives.
+ *
+ * That exercise found one real bug: Go's `url.Parse` rejects a `%XX` escape in
+ * the HOST whose high nibble is `< 8` (unless it is literally `%25`), so
+ * `//youtube%2ecom/@x` is a parse error and classifies as a keyword search. A
+ * naive decoder sees `youtube.com` and calls it a handle. 100 corpus rows
+ * hinged on it.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Cause, Effect, Exit, Option } from "effect"
+import { NotFoundError, OperationalError } from "../domain/errors.ts"
+import { parseJson } from "../json/parse.ts"
+import type { JsonValue } from "../json/value.ts"
+import type { DataApiResponse } from "../schema/dataapi.ts"
+import type { Params } from "../services/index.ts"
+import {
+  CHANNEL_ID_PATTERN,
+  goQuote,
+  goUrlParse,
+  parseChannelReference,
+  resolveChannelWith,
+  type ChannelReferenceKind
+} from "./resolveChannel.ts"
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+interface SeenGet {
+  readonly resource: string
+  readonly params: Params
+}
+
+const response = (text: string): DataApiResponse => {
+  const parsed = parseJson(text)
+  if (parsed._tag === "Failure") throw new Error("bad fixture")
+  return parsed.success as unknown as DataApiResponse
+}
+
+const harness = (bodies: ReadonlyArray) => {
+  const seen: Array = []
+  const get = (resource: string, params: Params) => {
+    seen.push({ resource, params })
+    return Effect.succeed(response(bodies[Math.min(seen.length - 1, bodies.length - 1)] ?? "{}"))
+  }
+  const resolve = resolveChannelWith(get)
+  return {
+    seen,
+    run: (reference: string) => Effect.runPromise(Effect.exit(resolve(reference)))
+  }
+}
+
+const okOf = (exit: Exit.Exit): A => {
+  if (!Exit.isSuccess(exit)) throw new Error(`expected success: ${Cause.pretty(exit.cause)}`)
+  return exit.value
+}
+
+const errOf = (exit: Exit.Exit): E => {
+  if (!Exit.isFailure(exit)) throw new Error("expected failure")
+  const found = Cause.findErrorOption(exit.cause)
+  if (!Option.isSome(found)) throw new Error("no error in cause")
+  return found.value
+}
+
+const param = (params: Params, key: string): string | undefined =>
+  params.find(([k]) => k === key)?.[1]
+
+// ---------------------------------------------------------------------------
+// goQuote
+// ---------------------------------------------------------------------------
+
+describe("goQuote", () => {
+  // Verified against Go 1.26.5 strconv.Quote.
+  test.each([
+    ["@example", '"@example"'],
+    ["Some Channel", '"Some Channel"'],
+    ['a"b', '"a\\"b"'],
+    ["a\\b", '"a\\\\b"'],
+    ["a\nb", '"a\\nb"'],
+    ["a\tb", '"a\\tb"'],
+    ["a\x00b", '"a\\x00b"'],
+    ["a\x1bb", '"a\\x1bb"'],
+    ["a\x7fb", '"a\\x7fb"'],
+    ["a'b", "\"a'b\""],
+    ["\x07\b\f\v", '"\\a\\b\\f\\v"'],
+    ["café", '"café"'],
+    ["日本", '"日本"'],
+    ["emoji \u{1F389}", '"emoji \u{1F389}"'],
+    ["nbsp x", '"nbsp\\u00a0x"'],
+    ["zwsp​x", '"zwsp\\u200bx"'],
+    ["bomx", '"bom\\ufeffx"'],
+    ["line
sep", '"line\\u2028sep"'],
+    ["…next", '"\\u0085next"'],
+    ["　ideographic", '"\\u3000ideographic"'],
+    ["unassigned\u{e0000}x", '"unassigned\\U000e0000x"']
+  ])("quotes %j", (input, expected) => {
+    expect(goQuote(input)).toBe(expected)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// goUrlParse
+// ---------------------------------------------------------------------------
+
+describe("goUrlParse", () => {
+  test("does not lowercase the host, unlike new URL", () => {
+    expect(goUrlParse("https://WWW.YOUTUBE.COM/@Foo")?.hostname).toBe("WWW.YOUTUBE.COM")
+    expect(new URL("https://WWW.YOUTUBE.COM/@Foo").hostname).toBe("www.youtube.com")
+  })
+
+  test("percent-decodes the path, unlike new URL", () => {
+    expect(goUrlParse("https://youtube.com/%40handle")?.path).toBe("/@handle")
+    expect(new URL("https://youtube.com/%40handle").pathname).toBe("/%40handle")
+  })
+
+  test("a scheme-relative //host DOES yield an authority", () => {
+    // Verified in Go: url.Parse("//youtube.com/@x").Host == "youtube.com".
+    // The classifier still calls it a search, because the "://" test fails and
+    // no "https://" prefix is prepended — so the reference reaches parse with a
+    // host but is not what the caller typed. See the golden corpus.
+    expect(goUrlParse("//youtube.com/@x")?.host).toBe("youtube.com")
+  })
+
+  test("three slashes after a scheme leave no authority", () => {
+    // url.Parse("https:////youtube.com/@x").Host == "" — verified in Go.
+    expect(goUrlParse("https:////youtube.com/@x")?.host).toBe("")
+  })
+
+  test("strips userinfo from the authority", () => {
+    expect(goUrlParse("https://user:pass@youtube.com/@x")?.hostname).toBe("youtube.com")
+  })
+
+  test("Hostname drops the port and unwraps IPv6 brackets", () => {
+    expect(goUrlParse("https://youtube.com:8080/@x")?.hostname).toBe("youtube.com")
+    expect(goUrlParse("https://[::1]/@x")?.hostname).toBe("::1")
+  })
+
+  test.each([
+    ["a control byte", "https://youtube.com/@x\ty"],
+    ["a truncated escape", "https://youtube.com/@x%"],
+    ["a bad escape", "https://youtube.com/@x%2G"],
+    ["a space in the host", "https://yout ube.com/@x"],
+    ["a bad escape in the fragment", "https://youtube.com/@x#f%zz"],
+    ["a low escape in the host", "https://youtube%2ecom/@x"]
+  ])("rejects %s", (_label, input) => {
+    expect(goUrlParse(input)).toBeUndefined()
+  })
+
+  test("does NOT validate query escapes", () => {
+    expect(goUrlParse("https://youtube.com/@x?q=%zz")?.path).toBe("/@x")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// parseChannelReference — golden corpus
+// ---------------------------------------------------------------------------
+
+describe("parseChannelReference (golden, captured from Go 1.26.5)", () => {
+  const golden: ReadonlyArray = [
+    // Bare handles.
+    ["@example", "handle", "@example"],
+    ["@", "handle", "@"],
+    [" @x", "search", " @x"],
+
+    // Canonical URL forms.
+    ["https://youtube.com/@example/videos", "handle", "@example"],
+    ["youtube.com/@example", "handle", "@example"],
+    ["https://www.youtube.com/@x", "handle", "@x"],
+    ["www.youtube.com/channel/UC1234567890123456789012", "id", "UC1234567890123456789012"],
+    [
+      "https://youtube.com/channel/UC1234567890123456789012/videos",
+      "id",
+      "UC1234567890123456789012"
+    ],
+    ["https://m.youtube.com/user/someuser", "username", "someuser"],
+    ["https://youtube.com/c/SomeName", "search", "SomeName"],
+    ["https://m.youtube.com/@x", "handle", "@x"],
+
+    // Host casing: TrimPrefix("www.") runs BEFORE ToLower, so an uppercase
+    // "WWW." survives and the host test fails.
+    ["https://WWW.YOUTUBE.COM/@Foo", "search", "https://WWW.YOUTUBE.COM/@Foo"],
+    ["WWW.youtube.com/@x", "search", "WWW.youtube.com/@x"],
+    // ...but a host with no "www." prefix lowercases fine.
+    ["https://M.YOUTUBE.COM/@x", "handle", "@x"],
+    ["M.Youtube.com/@x", "search", "M.Youtube.com/@x"],
+    ["https://www.m.youtube.com/@x", "handle", "@x"],
+
+    // The scheme is never checked.
+    ["ftp://youtube.com/@x", "handle", "@x"],
+    ["HTTPS://youtube.com/@x", "handle", "@x"],
+
+    // Non-YouTube and near-miss hosts.
+    ["https://youtu.be/@x", "search", "https://youtu.be/@x"],
+    ["youtu.be/@x", "search", "youtu.be/@x"],
+    ["https://music.youtube.com/@x", "search", "https://music.youtube.com/@x"],
+    ["https://youtube.com./@x", "search", "https://youtube.com./@x"],
+    ["xyoutube.com/@z", "search", "xyoutube.com/@z"],
+    ["https://[::1]/@x", "search", "https://[::1]/@x"],
+
+    // A scheme-relative reference has no authority in Go.
+    ["//youtube.com/@x", "search", "//youtube.com/@x"],
+
+    // Userinfo and ports.
+    ["https://user:pass@youtube.com/@x", "handle", "@x"],
+    ["https://youtube.com:8080/@x", "handle", "@x"],
+    ["http://www.youtube.com:8080/channel/UCabc", "id", "UCabc"],
+
+    // Paths that do not resolve to a known prefix.
+    ["https://youtube.com/", "search", "https://youtube.com/"],
+    ["https://youtube.com", "search", "https://youtube.com"],
+    ["youtube.com/", "search", "youtube.com/"],
+    ["https://youtube.com/channel", "search", "https://youtube.com/channel"],
+    ["https://youtube.com/channel/", "search", "https://youtube.com/channel/"],
+    ["https://youtube.com/user", "search", "https://youtube.com/user"],
+    ["https://youtube.com/user/", "search", "https://youtube.com/user/"],
+    ["https://youtube.com/c/", "search", "https://youtube.com/c/"],
+    ["https://youtube.com/watch?v=x", "search", "https://youtube.com/watch?v=x"],
+    // The prefix match is case-sensitive.
+    ["https://youtube.com/CHANNEL/UCabc", "search", "https://youtube.com/CHANNEL/UCabc"],
+    ["https://youtube.com/C/SomeName", "search", "https://youtube.com/C/SomeName"],
+
+    // Only the FIRST two path segments matter; extras are ignored.
+    ["https://youtube.com/user/a/b/c", "username", "a"],
+    ["https://youtube.com/channel/a/b", "id", "a"],
+    ["https://youtube.com/@x/@y", "handle", "@x"],
+
+    // Slash collapsing via strings.Trim(path, "/").
+    ["https://youtube.com//@x", "handle", "@x"],
+    ["https://youtube.com///@x", "handle", "@x"],
+    // ...but "." is a real segment, not normalized away.
+    ["https://youtube.com/./@x", "search", "https://youtube.com/./@x"],
+
+    // The path is percent-DECODED before segmentation.
+    ["https://youtube.com/%40handle", "handle", "@handle"],
+    ["https://youtube.com/@%C3%A9", "handle", "@é"],
+    ["https://youtube.com/@x%20y", "handle", "@x y"],
+    ["https://youtube.com/@x%2Fy", "handle", "@x"],
+    ["https://youtube.com/a%2Fb/@x", "search", "https://youtube.com/a%2Fb/@x"],
+    ["https://youtube.com/%2540handle", "search", "https://youtube.com/%2540handle"],
+
+    // Query and fragment are split off before the path is read.
+    ["https://youtube.com/@x?q=1", "handle", "@x"],
+    ["https://youtube.com/@x?", "handle", "@x"],
+    ["https://youtube.com/@x#frag", "handle", "@x"],
+    ["https://youtube.com/@x#", "handle", "@x"],
+    // Query escapes are not validated; fragment escapes are.
+    ["https://youtube.com/@x?q=%zz", "handle", "@x"],
+    ["https://youtube.com/@x#f%zz", "search", "https://youtube.com/@x#f%zz"],
+
+    // url.Parse failures all fall through to a keyword search.
+    ["https://youtube.com/@x%", "search", "https://youtube.com/@x%"],
+    ["https://youtube.com/@x%2G", "search", "https://youtube.com/@x%2G"],
+    ["https://yout ube.com/@x", "search", "https://yout ube.com/@x"],
+    // A %XX in the host with a high nibble < 8 is rejected outright.
+    ["https://youtube%2ecom/@x", "search", "https://youtube%2ecom/@x"],
+
+    // Characters url.Parse tolerates in a path.
+    ["https://youtube.com/@x y", "handle", "@x y"],
+    ["https://youtube.com/@x|y", "handle", "@x|y"],
+    ['https://youtube.com/@x"y', "handle", '@x"y'],
+    ["https://youtube.com/@x[1]", "handle", "@x[1]"],
+    ["https://youtube.com/@café", "handle", "@café"],
+    ["https://youtube.com/@日本", "handle", "@日本"],
+    ["https://youtube.com/@", "handle", "@"],
+
+    // Plain keywords.
+    ["Some Channel", "search", "Some Channel"],
+    ["UC1234567890123456789012", "search", "UC1234567890123456789012"],
+    ["mailto:x@y.com", "search", "mailto:x@y.com"],
+    ["a:b/c", "search", "a:b/c"]
+  ]
+
+  test.each(golden)("%j -> %s %j", (input, kind, value) => {
+    expect(parseChannelReference(input)).toEqual({ kind, value })
+  })
+
+  test("the golden corpus covers every kind", () => {
+    const kinds = new Set(golden.map(([, kind]) => kind))
+    expect([...kinds].sort()).toEqual(["handle", "id", "search", "username"])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// CHANNEL_ID_PATTERN
+// ---------------------------------------------------------------------------
+
+describe("CHANNEL_ID_PATTERN", () => {
+  test("accepts exactly 24 characters starting with UC", () => {
+    expect(CHANNEL_ID_PATTERN.test("UC1234567890123456789012")).toBe(true)
+    expect("UC1234567890123456789012".length).toBe(24)
+  })
+
+  test.each([
+    ["too short", "UC123456789012345678901"],
+    ["too long", "UC12345678901234567890123"],
+    ["wrong prefix", "AB1234567890123456789012"],
+    ["lowercase prefix", "uc1234567890123456789012"],
+    ["an illegal character", "UC123456789012345678901!"],
+    ["empty", ""]
+  ])("rejects %s", (_label, input) => {
+    expect(CHANNEL_ID_PATTERN.test(input)).toBe(false)
+  })
+
+  test("accepts the URL-safe base64 alphabet", () => {
+    expect(CHANNEL_ID_PATTERN.test("UCabcXYZ012_-abcXYZ01234")).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// resolveChannel
+// ---------------------------------------------------------------------------
+
+describe("resolveChannel", () => {
+  // Go: TestResolveChannelHandleAndURL
+  test("resolves a handle URL through channels?forHandle, one request", async () => {
+    const h = harness([`{"items":[{"id":"UC1234567890123456789012"}]}`])
+    const result = okOf(await h.run("https://youtube.com/@example/videos"))
+
+    expect(result).toEqual({ id: "UC1234567890123456789012", requests: 1 })
+    expect(h.seen).toHaveLength(1)
+    expect(h.seen[0]!.resource).toBe("channels")
+    expect(param(h.seen[0]!.params, "forHandle")).toBe("example")
+    expect(param(h.seen[0]!.params, "part")).toBe("id")
+  })
+
+  // Go: the same test asserts a canonical UC… id costs zero requests.
+  test("a UC… id short-circuits with zero requests", async () => {
+    const h = harness([`{"items":[]}`])
+    expect(okOf(await h.run("UC1234567890123456789012"))).toEqual({
+      id: "UC1234567890123456789012",
+      requests: 0
+    })
+    expect(h.seen).toHaveLength(0)
+  })
+
+  test("a bare @handle strips only the leading @", async () => {
+    const h = harness([`{"items":[{"id":"UCz"}]}`])
+    okOf(await h.run("@ex@mple"))
+    expect(param(h.seen[0]!.params, "forHandle")).toBe("ex@mple")
+  })
+
+  test("a /user/ URL uses forUsername", async () => {
+    const h = harness([`{"items":[{"id":"UCu"}]}`])
+    const result = okOf(await h.run("https://m.youtube.com/user/someuser"))
+    expect(result).toEqual({ id: "UCu", requests: 1 })
+    expect(param(h.seen[0]!.params, "forUsername")).toBe("someuser")
+    expect(param(h.seen[0]!.params, "forHandle")).toBeUndefined()
+  })
+
+  test("a /channel/ URL short-circuits when the ID is valid", async () => {
+    const h = harness(["{}"])
+    expect(okOf(await h.run("https://youtube.com/channel/UC1234567890123456789012"))).toEqual({
+      id: "UC1234567890123456789012",
+      requests: 0
+    })
+    expect(h.seen).toHaveLength(0)
+  })
+
+  test("a /channel/ URL with a malformed ID is an error, not a search", async () => {
+    const h = harness(["{}"])
+    const error = errOf(await h.run("https://youtube.com/channel/UCabc"))
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toBe('invalid channel ID "UCabc"')
+    expect(h.seen).toHaveLength(0)
+  })
+
+  test("a keyword reads the NESTED id.channelId from search", async () => {
+    const h = harness([`{"items":[{"id":{"kind":"youtube#channel","channelId":"UCsearched"}}]}`])
+    const result = okOf(await h.run("Some Channel"))
+
+    expect(result).toEqual({ id: "UCsearched", requests: 1 })
+    expect(h.seen[0]!.resource).toBe("search")
+    expect(param(h.seen[0]!.params, "part")).toBe("snippet")
+    expect(param(h.seen[0]!.params, "type")).toBe("channel")
+    expect(param(h.seen[0]!.params, "q")).toBe("Some Channel")
+    expect(param(h.seen[0]!.params, "maxResults")).toBe("1")
+  })
+
+  test("a /c/ URL searches for the segment, not the whole URL", async () => {
+    const h = harness([`{"items":[{"id":{"channelId":"UCc"}}]}`])
+    okOf(await h.run("https://youtube.com/c/SomeName"))
+    expect(param(h.seen[0]!.params, "q")).toBe("SomeName")
+  })
+
+  test("the channels path reads a FLAT string id, unlike search", async () => {
+    // An object-valued id on the channels path yields "not found".
+    const h = harness([`{"items":[{"id":{"channelId":"UCnested"}}]}`])
+    expect(errOf(await h.run("@example"))).toBeInstanceOf(NotFoundError)
+  })
+
+  describe("not found", () => {
+    test("empty items on the channels path", async () => {
+      const h = harness([`{"items":[]}`])
+      const error = errOf(await h.run("@example"))
+      expect(error).toBeInstanceOf(NotFoundError)
+      expect(error.message).toBe('channel "@example" not found')
+    })
+
+    test("empty items on the search path", async () => {
+      const h = harness([`{"items":[]}`])
+      const error = errOf(await h.run("Some Channel"))
+      expect(error.message).toBe('channel "Some Channel" not found')
+    })
+
+    test("an item with no id", async () => {
+      const h = harness([`{"items":[{"snippet":{"title":"t"}}]}`])
+      expect(errOf(await h.run("@example"))).toBeInstanceOf(NotFoundError)
+    })
+
+    test("an item with an empty-string id", async () => {
+      const h = harness([`{"items":[{"id":""}]}`])
+      expect(errOf(await h.run("@example"))).toBeInstanceOf(NotFoundError)
+    })
+
+    test("a search item with no channelId", async () => {
+      const h = harness([`{"items":[{"id":{"kind":"youtube#channel"}}]}`])
+      expect(errOf(await h.run("Some Channel"))).toBeInstanceOf(NotFoundError)
+    })
+
+    test("a search item whose id is a flat string", async () => {
+      const h = harness([`{"items":[{"id":"UCflat"}]}`])
+      expect(errOf(await h.run("Some Channel"))).toBeInstanceOf(NotFoundError)
+    })
+
+    test("the message quotes the TRIMMED reference with Go's %q", async () => {
+      const h = harness([`{"items":[]}`])
+      const error = errOf(await h.run('  a"b  '))
+      expect(error.message).toBe('channel "a\\"b" not found')
+    })
+  })
+
+  describe("empty reference", () => {
+    test.each([["empty", ""], ["spaces", "   "], ["a tab", "\t"], ["a newline", "\n"]])(
+      "%s is rejected before any request",
+      async (_label, input) => {
+        const h = harness(["{}"])
+        const error = errOf(await h.run(input))
+        expect(error).toBeInstanceOf(OperationalError)
+        expect(error.message).toBe("channel reference cannot be empty")
+        expect(h.seen).toHaveLength(0)
+      }
+    )
+  })
+
+  test("the reference is trimmed before classification", async () => {
+    const h = harness(["{}"])
+    expect(okOf(await h.run("  UC1234567890123456789012  "))).toEqual({
+      id: "UC1234567890123456789012",
+      requests: 0
+    })
+  })
+
+  test("an upstream error propagates unchanged", async () => {
+    const failing = (resource: string, _params: Params) =>
+      Effect.fail(new OperationalError({ message: `boom on ${resource}` }))
+    const exit = await Effect.runPromise(
+      Effect.exit(resolveChannelWith(failing)("@example"))
+    )
+    expect(errOf(exit).message).toBe("boom on channels")
+  })
+})
+
+test("a resolved id round-trips through the JSON value model unchanged", () => {
+  // Guards against an accessor accidentally coercing a RawNumber-shaped id.
+  const parsed = parseJson(`{"items":[{"id":"UC1234567890123456789012"}]}`)
+  expect(parsed._tag).toBe("Success")
+  if (parsed._tag !== "Success") throw new Error("unreachable")
+  const value: JsonValue = parsed.success
+  expect(typeof value).toBe("object")
+})
diff --git a/src/impl/resolveChannel.ts b/src/impl/resolveChannel.ts
index ca14f9a..755c39a 100644
--- a/src/impl/resolveChannel.ts
+++ b/src/impl/resolveChannel.ts
@@ -1,2 +1,406 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Channel-reference resolution — a port of `internal/youtube/list.go`'s
+ * `ResolveChannel` / `parseChannelReference`.
+ *
+ * A reference is a `UC…` ID, an `@handle`, or a YouTube URL. The classifier is
+ * deliberately quirky and the quirks are load-bearing, so this file reproduces
+ * Go's `net/url` semantics rather than reaching for `new URL`. The two differ
+ * in ways the classifier can actually observe, all verified against Go 1.26.5:
+ *
+ *   | reference                        | Go           | `new URL`        |
+ *   |----------------------------------|--------------|------------------|
+ *   | `//youtube.com/@x`               | search       | handle `@x`      |
+ *   | `https://WWW.YOUTUBE.COM/@Foo`   | search       | handle `@Foo`    |
+ *   | `https://youtube.com/%40handle`  | handle `@handle` | (no match)   |
+ *   | `https://youtube.com/@xy`   | search (err) | handle `@xy`     |
+ *   | `https://youtube.com/@x%`        | search (err) | handle `@x%`     |
+ *
+ * The `WWW.YOUTUBE.COM` row is the important one: Go's `url.Parse` does not
+ * lowercase the host, and `strings.TrimPrefix(host, "www.")` runs BEFORE
+ * `strings.ToLower`, so an uppercase `WWW.` prefix survives and the host test
+ * fails. `new URL` lowercases eagerly and would silently "fix" it.
+ */
+
+import { Effect } from "effect"
+import { NotFoundError, OperationalError, type OytcError } from "../domain/errors.ts"
+import { searchItemChannelId, channelItemId } from "../schema/accessors.ts"
+import type { DataApiResponse } from "../schema/dataapi.ts"
+import type { JsonObject } from "../json/value.ts"
+import type { Params, ResolvedChannel } from "../services/index.ts"
+
+/** `^UC[A-Za-z0-9_-]{22}$` — exactly 24 characters. */
+export const CHANNEL_ID_PATTERN = /^UC[A-Za-z0-9_-]{22}$/
+
+// ---------------------------------------------------------------------------
+// Go string formatting
+// ---------------------------------------------------------------------------
+
+const HEX_LOWER = "0123456789abcdef"
+
+/**
+ * Go's `unicode.IsPrint`: general categories L, M, N, P, S, plus the ASCII
+ * space. Notably NOT other space separators (U+00A0, U+2000, U+3000), format
+ * characters (U+200B, U+FEFF), line/paragraph separators, private use, or
+ * unassigned code points — all of which Go escapes.
+ */
+const PRINTABLE = /^[\p{L}\p{M}\p{N}\p{P}\p{S}]$/u
+
+const SHORT_ESCAPES: Readonly> = {
+  0x07: "\\a",
+  0x08: "\\b",
+  0x0c: "\\f",
+  0x0a: "\\n",
+  0x0d: "\\r",
+  0x09: "\\t",
+  0x0b: "\\v"
+}
+
+/**
+ * Go's `strconv.Quote`, which is what `fmt.Errorf("%q")` uses for the two
+ * user-facing messages this file produces.
+ *
+ * Verified against Go 1.26.5: `\a\b\f\v` short escapes, `\x1b` for other
+ * control bytes, ` ` / `​` / `` / `
` for non-printable
+ * BMP code points, `\U000e0000` for non-printable astral ones, and literal
+ * pass-through for `café`, `日本` and emoji.
+ */
+export const goQuote = (s: string): string => {
+  let out = '"'
+  for (const char of s) {
+    const code = char.codePointAt(0)!
+    if (char === '"') {
+      out += '\\"'
+    } else if (char === "\\") {
+      out += "\\\\"
+    } else if (SHORT_ESCAPES[code] !== undefined) {
+      out += SHORT_ESCAPES[code]
+    } else if (code >= 0x20 && code < 0x7f) {
+      out += char
+    } else if (code < 0x80) {
+      out += `\\x${HEX_LOWER[(code >> 4) & 0xf]}${HEX_LOWER[code & 0xf]}`
+    } else if (PRINTABLE.test(char)) {
+      out += char
+    } else if (code < 0x10000) {
+      out += `\\u${code.toString(16).padStart(4, "0")}`
+    } else {
+      out += `\\U${code.toString(16).padStart(8, "0")}`
+    }
+  }
+  return `${out}"`
+}
+
+// ---------------------------------------------------------------------------
+// A faithful subset of Go's net/url.Parse
+// ---------------------------------------------------------------------------
+
+export interface GoUrl {
+  /** Empty when the URL has no authority component. */
+  readonly host: string
+  /** `Hostname()` — `host` without its port and without IPv6 brackets. */
+  readonly hostname: string
+  /** `Path` — percent-DECODED, so `%40` has already become `@`. */
+  readonly path: string
+}
+
+const isHexDigit = (c: string): boolean => /^[0-9A-Fa-f]$/.test(c)
+
+/** `stringContainsCTLByte` — any byte `< 0x20` or `== 0x7f`. */
+const containsControl = (s: string): boolean => {
+  for (const char of s) {
+    const code = char.codePointAt(0)!
+    if (code < 0x20 || code === 0x7f) return true
+  }
+  return false
+}
+
+/** Go's `unescape` escape validation; returns false on a malformed `%XY`. */
+const escapesValid = (s: string): boolean => {
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] !== "%") continue
+    if (i + 2 >= s.length || !isHexDigit(s[i + 1]!) || !isHexDigit(s[i + 2]!)) return false
+    i += 2
+  }
+  return true
+}
+
+/**
+ * Percent-decode. Go produces raw bytes here, which may be invalid UTF-8; a
+ * non-fatal decode turns those into U+FFFD instead. Only reachable via an
+ * exotic hand-written URL, and the resulting path segment is looked up
+ * remotely either way.
+ */
+const percentDecode = (s: string): string => {
+  if (!s.includes("%")) return s
+  const bytes: Array = []
+  const raw = new TextEncoder().encode(s)
+  for (let i = 0; i < raw.length; i++) {
+    if (raw[i] === 0x25 && i + 2 < raw.length) {
+      bytes.push(parseInt(String.fromCharCode(raw[i + 1]!, raw[i + 2]!), 16))
+      i += 2
+    } else {
+      bytes.push(raw[i]!)
+    }
+  }
+  return new TextDecoder("utf-8", { fatal: false }).decode(new Uint8Array(bytes))
+}
+
+/**
+ * Go's `shouldEscape(c, encodeHost)` inverted: the bytes allowed unescaped in a
+ * host. Anything else (notably a space) makes `parseHost` fail.
+ */
+const HOST_ALLOWED = /^[A-Za-z0-9\-._~!$&'()*+,;=:[\]<>"%]$/
+
+const validOptionalPort = (colonPort: string): boolean =>
+  colonPort === "" || /^:[0-9]*$/.test(colonPort)
+
+/**
+ * `parseHost` — validates the port suffix and every host byte.
+ *
+ * The `%2e` rule is the subtle one: `unescape(..., encodeHost)` rejects any
+ * escape whose high nibble is `< 8` unless it is literally `%25`, because
+ * "hosts can't use %-encoding for ASCII bytes". So `//youtube%2ecom/@x` is a
+ * parse ERROR in Go and classifies as a keyword search, where a naive decoder
+ * would see `youtube.com` and call it a handle. Caught by differential fuzzing
+ * against Go 1.26.5 — 100 corpus rows hinged on it.
+ */
+const parseHost = (authority: string): string | undefined => {
+  if (authority.startsWith("[")) {
+    // A bracketed IP-literal: the port, if any, follows the closing bracket.
+    // Go additionally parses the address itself (rejecting `[v7.abc]`); that is
+    // not reproduced because no bracketed host can ever equal youtube.com, so
+    // it cannot change a classification.
+    const close = authority.lastIndexOf("]")
+    if (close < 0) return undefined
+    if (!validOptionalPort(authority.slice(close + 1))) return undefined
+    return authority
+  }
+  const colon = authority.lastIndexOf(":")
+  if (colon !== -1 && !validOptionalPort(authority.slice(colon))) return undefined
+  for (const char of authority) {
+    if (char === "%") continue
+    if (char.codePointAt(0)! >= 0x80) continue
+    if (!HOST_ALLOWED.test(char)) return undefined
+  }
+  if (!escapesValid(authority)) return undefined
+  for (let i = 0; i < authority.length; i++) {
+    if (authority[i] !== "%") continue
+    if (parseInt(authority[i + 1]!, 16) < 8 && authority.slice(i, i + 3) !== "%25") return undefined
+    i += 2
+  }
+  return percentDecode(authority)
+}
+
+/** `getScheme` — a leading alpha followed by alnum/`+`/`-`/`.` up to a `:`. */
+const getScheme = (raw: string): { scheme: string; rest: string } | undefined => {
+  for (let i = 0; i < raw.length; i++) {
+    const c = raw[i]!
+    if (/[A-Za-z]/.test(c)) continue
+    if (/[0-9+\-.]/.test(c)) {
+      if (i === 0) return { scheme: "", rest: raw }
+      continue
+    }
+    if (c === ":") {
+      if (i === 0) return undefined // "missing protocol scheme"
+      return { scheme: raw.slice(0, i), rest: raw.slice(i + 1) }
+    }
+    return { scheme: "", rest: raw }
+  }
+  return { scheme: "", rest: raw }
+}
+
+/**
+ * `url.Parse`, restricted to what the channel classifier observes: control-byte
+ * rejection, fragment/query splitting, scheme detection, the relative-path
+ * colon rule, `//authority` extraction with userinfo stripping, host
+ * validation, and percent-decoded paths.
+ *
+ * Returns `undefined` where Go returns an error — the classifier treats both
+ * identically (fall through to a keyword search).
+ */
+export const goUrlParse = (raw: string): GoUrl | undefined => {
+  const hash = raw.indexOf("#")
+  const beforeFragment = hash === -1 ? raw : raw.slice(0, hash)
+  const fragment = hash === -1 ? "" : raw.slice(hash + 1)
+
+  if (containsControl(beforeFragment)) return undefined
+
+  const scheme = getScheme(beforeFragment)
+  if (scheme === undefined) return undefined
+
+  // Go splits the query off before touching the authority, and never validates
+  // its escapes — `?q=%zz` parses fine.
+  const question = scheme.rest.indexOf("?")
+  let rest = question === -1 ? scheme.rest : scheme.rest.slice(0, question)
+
+  if (!rest.startsWith("/")) {
+    // A rootless path under a scheme is opaque: no host, no path.
+    if (scheme.scheme !== "") return { host: "", hostname: "", path: "" }
+    const firstSegment = rest.includes("/") ? rest.slice(0, rest.indexOf("/")) : rest
+    if (firstSegment.includes(":")) return undefined
+  }
+
+  let host = ""
+  if ((scheme.scheme !== "" || !rest.startsWith("///")) && rest.startsWith("//")) {
+    let authority = rest.slice(2)
+    rest = ""
+    const slash = authority.indexOf("/")
+    if (slash >= 0) {
+      rest = authority.slice(slash)
+      authority = authority.slice(0, slash)
+    }
+    const at = authority.lastIndexOf("@")
+    const parsed = parseHost(at < 0 ? authority : authority.slice(at + 1))
+    if (parsed === undefined) return undefined
+    host = parsed
+  }
+
+  if (!escapesValid(rest)) return undefined
+  if (fragment !== "" && !escapesValid(fragment)) return undefined
+
+  // Hostname(): drop a valid `:port`, then unwrap IPv6 brackets.
+  let hostname = host
+  const colon = hostname.lastIndexOf(":")
+  if (colon !== -1 && validOptionalPort(hostname.slice(colon))) hostname = hostname.slice(0, colon)
+  if (hostname.startsWith("[") && hostname.endsWith("]")) hostname = hostname.slice(1, -1)
+
+  return { host, hostname, path: percentDecode(rest) }
+}
+
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+
+export type ChannelReferenceKind = "handle" | "id" | "username" | "search"
+
+export interface ChannelReference {
+  readonly kind: ChannelReferenceKind
+  readonly value: string
+}
+
+/** `strings.Trim(s, "/")` — strips ALL leading and trailing slashes. */
+const trimSlashes = (s: string): string => s.replace(/^\/+/, "").replace(/\/+$/, "")
+
+/**
+ * `parseChannelReference`. Note two deliberate Go quirks preserved verbatim:
+ *
+ *  - `strings.TrimPrefix(hostname, "www.")` runs BEFORE `strings.ToLower`, so
+ *    an uppercase `WWW.` is not stripped and the host test then fails.
+ *  - the scheme is never checked, so `ftp://youtube.com/@x` classifies as a
+ *    handle.
+ */
+export const parseChannelReference = (reference: string): ChannelReference => {
+  if (reference.startsWith("@")) return { kind: "handle", value: reference }
+
+  let candidate = reference
+  if (
+    !candidate.includes("://") &&
+    (candidate.includes("youtube.com/") || candidate.includes("youtu.be/"))
+  ) {
+    candidate = `https://${candidate}`
+  }
+
+  const parsed = goUrlParse(candidate)
+  if (parsed !== undefined && parsed.host !== "") {
+    const host = parsed.hostname.replace(/^www\./, "").toLowerCase()
+    if (host === "youtube.com" || host === "m.youtube.com") {
+      const parts = trimSlashes(parsed.path).split("/")
+      const first = parts[0]
+      if (first !== undefined && first.startsWith("@")) return { kind: "handle", value: first }
+      if (parts.length >= 2) {
+        const second = parts[1]!
+        if (first === "channel") return { kind: "id", value: second }
+        if (first === "user") return { kind: "username", value: second }
+        if (first === "c") return { kind: "search", value: second }
+      }
+    }
+  }
+
+  return { kind: "search", value: reference }
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/** The single-shot `Get` this module needs; injected to avoid a cycle. */
+export type GetResponse = (
+  resource: string,
+  params: Params
+) => Effect.Effect
+
+const firstItem = (response: DataApiResponse): JsonObject | undefined =>
+  // Safe: the decoded value came from parseJson, whose leaves are all JsonValue.
+  (response.items?.[0] as JsonObject | undefined) ?? undefined
+
+const notFound = (reference: string): NotFoundError =>
+  new NotFoundError({ message: `channel ${goQuote(reference)} not found` })
+
+/**
+ * `(channelID, requestsUsed)` where `requestsUsed` is 0 or 1.
+ *
+ * Go returns the partial request count alongside the error; every caller adds
+ * it and then discards the total by returning the error, so failing outright
+ * is equivalent.
+ */
+export const resolveChannelWith =
+  (get: GetResponse) =>
+  (reference: string): Effect.Effect =>
+    Effect.gen(function* () {
+      // Go's TrimSpace uses unicode.IsSpace, which includes U+0085 and U+00A0
+      // but excludes U+FEFF and U+200B. JS `trim` uses WhiteSpace + LineTerminator
+      // + U+FEFF — the only divergence is a BOM-padded reference, which JS
+      // trims and Go does not.
+      const trimmed = reference.trim()
+      if (trimmed === "") {
+        // Go uses errors.New here, not a UsageError, so this exits 6.
+        return yield* Effect.fail(
+          new OperationalError({ message: "channel reference cannot be empty" })
+        )
+      }
+      if (CHANNEL_ID_PATTERN.test(trimmed)) return { id: trimmed, requests: 0 }
+
+      const classified = parseChannelReference(trimmed)
+
+      if (classified.kind === "id") {
+        if (!CHANNEL_ID_PATTERN.test(classified.value)) {
+          return yield* Effect.fail(
+            new OperationalError({ message: `invalid channel ID ${goQuote(classified.value)}` })
+          )
+        }
+        return { id: classified.value, requests: 0 }
+      }
+
+      if (classified.kind === "search") {
+        const response = yield* get("search", [
+          ["part", "snippet"],
+          ["type", "channel"],
+          ["q", classified.value],
+          ["maxResults", "1"]
+        ])
+        const item = firstItem(response)
+        if (item === undefined) return yield* Effect.fail(notFound(trimmed))
+        // search returns an OBJECT-valued `id`, so the channel ID is nested.
+        const id = searchItemChannelId(item)
+        if (id._tag === "None" || id.value === "") return yield* Effect.fail(notFound(trimmed))
+        return { id: id.value, requests: 1 }
+      }
+
+      const params: Params =
+        classified.kind === "handle"
+          ? [
+              ["part", "id"],
+              ["forHandle", classified.value.replace(/^@/, "")]
+            ]
+          : [
+              ["part", "id"],
+              ["forUsername", classified.value]
+            ]
+
+      const response = yield* get("channels", params)
+      const item = firstItem(response)
+      if (item === undefined) return yield* Effect.fail(notFound(trimmed))
+      // channels returns a FLAT string `id`, unlike search.
+      const id = channelItemId(item)
+      if (id._tag === "None") return yield* Effect.fail(notFound(trimmed))
+      return { id: id.value, requests: 1 }
+    })
diff --git a/src/impl/semver.test.ts b/src/impl/semver.test.ts
new file mode 100644
index 0000000..5f7e731
--- /dev/null
+++ b/src/impl/semver.test.ts
@@ -0,0 +1,188 @@
+import { describe, expect, test } from "bun:test"
+import { compareVersions, goTrimSpace, parseVersion } from "./semver.ts"
+
+/** Port of Go's `TestCompareVersions` — the same nine rows, same order. */
+describe("TestCompareVersions", () => {
+  const cases: ReadonlyArray<{
+    readonly a: string
+    readonly b: string
+    readonly want: number
+    readonly comparable: boolean
+  }> = [
+    { a: "v1.2.3", b: "v1.2.3", want: 0, comparable: true },
+    { a: "v1.2.3", b: "1.2.3", want: 0, comparable: true },
+    { a: "v0.2.0", b: "v0.10.0", want: -1, comparable: true },
+    { a: "v2.0.0", b: "v1.9.9", want: 1, comparable: true },
+    { a: "v1.0.0-rc.1", b: "v1.0.0", want: -1, comparable: true },
+    { a: "v1.0.0", b: "v1.0.0-rc.1", want: 1, comparable: true },
+    { a: "v1.0.0-rc.1", b: "v1.0.0-rc.2", want: -1, comparable: true },
+    { a: "dev", b: "v1.0.0", want: 0, comparable: false },
+    { a: "v1.0.0", b: "unknown", want: 0, comparable: false }
+  ]
+
+  for (const { a, b, want, comparable } of cases) {
+    test(`compareVersions(${a}, ${b}) = ${want}, ${comparable}`, () => {
+      expect(compareVersions(a, b)).toEqual({ order: want as -1 | 0 | 1, comparable })
+    })
+  }
+})
+
+describe("byte-wise prerelease comparison", () => {
+  /**
+   * The behaviour the port MUST preserve: this is a plain string compare, not
+   * SemVer's dot-separated identifier compare. Under SemVer rc.10 > rc.2;
+   * here it is smaller, exactly as Go's `av.pre < bv.pre` decides.
+   */
+  test("rc.10 sorts BEFORE rc.2 (not SemVer ordering)", () => {
+    expect(compareVersions("v1.0.0-rc.10", "v1.0.0-rc.2")).toEqual({
+      order: -1,
+      comparable: true
+    })
+    expect(compareVersions("v1.0.0-rc.2", "v1.0.0-rc.10")).toEqual({
+      order: 1,
+      comparable: true
+    })
+  })
+
+  test("alpha < beta", () => {
+    expect(compareVersions("v1.0.0-alpha", "v1.0.0-beta").order).toBe(-1)
+  })
+
+  test("uppercase sorts before lowercase, as ASCII bytes do", () => {
+    expect(compareVersions("v1.0.0-RC.1", "v1.0.0-rc.1").order).toBe(-1)
+  })
+
+  test("identical prereleases are equal", () => {
+    expect(compareVersions("v1.0.0-rc.1", "1.0.0-rc.1")).toEqual({ order: 0, comparable: true })
+  })
+
+  test("a shorter prefix sorts first", () => {
+    expect(compareVersions("v1.0.0-rc", "v1.0.0-rc.1").order).toBe(-1)
+  })
+})
+
+describe("numeric ordering", () => {
+  test("compares major, then minor, then patch", () => {
+    expect(compareVersions("v1.0.0", "v0.99.99").order).toBe(1)
+    expect(compareVersions("v1.0.0", "v1.1.0").order).toBe(-1)
+    expect(compareVersions("v1.1.1", "v1.1.0").order).toBe(1)
+  })
+
+  test("numeric, not lexical: 10 > 9", () => {
+    expect(compareVersions("v0.10.0", "v0.9.0").order).toBe(1)
+  })
+
+  test("leading zeros are numeric values, as strconv.Atoi reads them", () => {
+    expect(compareVersions("v01.02.03", "v1.2.3")).toEqual({ order: 0, comparable: true })
+  })
+
+  test("counters beyond 2^32 still compare", () => {
+    expect(compareVersions("v4294967296.0.0", "v4294967295.0.0").order).toBe(1)
+  })
+})
+
+describe("parseVersion", () => {
+  test("accepts a bare or v-prefixed core", () => {
+    expect(parseVersion("1.2.3")).toEqual({ numbers: [1, 2, 3], prerelease: "" })
+    expect(parseVersion("v1.2.3")).toEqual({ numbers: [1, 2, 3], prerelease: "" })
+  })
+
+  test("strips surrounding whitespace", () => {
+    expect(parseVersion("  v1.2.3\t")).toEqual({ numbers: [1, 2, 3], prerelease: "" })
+  })
+
+  test("splits the prerelease at the FIRST dash only", () => {
+    expect(parseVersion("1.2.3-a-b")).toEqual({ numbers: [1, 2, 3], prerelease: "a-b" })
+  })
+
+  /**
+   * Verified against Go: `strings.Cut(core, "+")` runs on the CORE only, after
+   * the prerelease has already been split off, so build metadata attached to a
+   * prerelease stays part of the prerelease string.
+   */
+  test("build metadata is stripped from the core only", () => {
+    expect(parseVersion("1.2.3+build")).toEqual({ numbers: [1, 2, 3], prerelease: "" })
+    expect(parseVersion("1.2.3-rc.1+b")).toEqual({ numbers: [1, 2, 3], prerelease: "rc.1+b" })
+  })
+
+  test("a trailing dash yields an empty (release) prerelease", () => {
+    expect(parseVersion("1.2.3-")).toEqual({ numbers: [1, 2, 3], prerelease: "" })
+  })
+
+  test("rejects anything that is not exactly three dot-separated parts", () => {
+    for (const tag of ["1.2", "1.2.3.4", "1", "..", "1..3"]) {
+      expect(parseVersion(tag)).toBeUndefined()
+    }
+  })
+
+  test("rejects non-integer components, matching strconv.Atoi", () => {
+    for (const tag of ["1.2.x", "1.2.3e0", "1.2. 3", "1.2.0x3", "1.2.1_0", "1.2.٣"]) {
+      expect(parseVersion(tag)).toBeUndefined()
+    }
+  })
+
+  test("rejects negative components", () => {
+    expect(parseVersion("1.-2.3")).toBeUndefined()
+  })
+
+  /**
+   * Verified against Go: the build-metadata cut runs at the FIRST `+`, so a
+   * leading `+` empties the core and the tag is rejected before `strconv.Atoi`
+   * (which would otherwise have accepted `+1`) is ever reached.
+   */
+  test("a leading plus empties the core and is rejected", () => {
+    expect(parseVersion("+1.2.3")).toBeUndefined()
+    expect(parseVersion("1.+2.3")).toBeUndefined()
+    expect(parseVersion("1.2.+3")).toBeUndefined()
+  })
+
+  test("rejects values past int64, where Atoi reports out of range", () => {
+    expect(parseVersion("99999999999999999999.0.0")).toBeUndefined()
+  })
+
+  test("rejects the empty tag and a bare v", () => {
+    expect(parseVersion("")).toBeUndefined()
+    expect(parseVersion("v")).toBeUndefined()
+    expect(parseVersion("   ")).toBeUndefined()
+  })
+
+  test("a leading dash makes the core empty and unparseable", () => {
+    expect(parseVersion("-1.2.3")).toBeUndefined()
+  })
+
+  test("dev and unknown never parse, which is what keeps them incomparable", () => {
+    expect(parseVersion("dev")).toBeUndefined()
+    expect(parseVersion("unknown")).toBeUndefined()
+  })
+})
+
+describe("goTrimSpace", () => {
+  test("strips the Go whitespace set", () => {
+    expect(goTrimSpace("\t\n\v\f\r x \r\n")).toBe("x")
+    expect(goTrimSpace(" x ")).toBe("x")
+    expect(goTrimSpace("
x
")).toBe("x")
+  })
+
+  test("strips U+0085 (NEL), which JS trim() leaves in place", () => {
+    expect(goTrimSpace("…x…")).toBe("x")
+  })
+
+  test("does NOT strip U+FEFF, which JS trim() removes", () => {
+    expect(goTrimSpace("x")).toBe("x")
+  })
+})
+
+describe("incomparability is not equality", () => {
+  test("an unparseable current version reports comparable=false, not order=0", () => {
+    const result = compareVersions("v0.2.0", "dev")
+    expect(result.comparable).toBe(false)
+    // The updater keys off `comparable` before it looks at `order`, which is
+    // what makes a dev build always proceed to install rather than report
+    // itself up to date.
+    expect(result.order).toBe(0)
+  })
+
+  test("both sides unparseable", () => {
+    expect(compareVersions("dev", "dev")).toEqual({ order: 0, comparable: false })
+  })
+})
diff --git a/src/impl/semver.ts b/src/impl/semver.ts
index ca14f9a..80f7af6 100644
--- a/src/impl/semver.ts
+++ b/src/impl/semver.ts
@@ -1,2 +1,138 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Version tag comparison — a faithful port of `internal/update/update.go`'s
+ * `parseVersion` / `CompareVersions`.
+ *
+ * This is deliberately **not** SemVer. Two behaviours are load-bearing and
+ * must not be "fixed":
+ *
+ *   1. The prerelease tie-break is a plain **byte-wise string comparison**,
+ *      not SemVer's dot-separated identifier comparison. So `rc.10` sorts
+ *      BEFORE `rc.2`. Changing this would silently change which release the
+ *      updater considers newer. Go compares UTF-8 bytes, so `compareUtf8` is
+ *      used rather than JS `<`, which compares UTF-16 code units and disagrees
+ *      above the BMP.
+ *   2. Anything that does not parse makes the pair **incomparable**, not
+ *      "equal". A `dev` build is therefore never up to date, which is exactly
+ *      why an uninjected build always proceeds to install the latest release.
+ */
+
+import { compareUtf8 } from "../util/gostring.ts"
+
+/** Go's `unicode.IsSpace`, which is not the same set as JS `String.trim`. */
+const GO_SPACE = new Set([
+  0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x20, 0x85, 0xa0, 0x1680, 0x2028, 0x2029, 0x202f, 0x205f, 0x3000
+])
+
+/**
+ * Go's `unicode.IsSpace`. Exported because `strings.Fields` needs the same
+ * predicate, and the JS `\s` class is not it: `\s` matches U+FEFF, which Go
+ * does not, and misses U+0085, which Go does.
+ */
+export const isGoSpace = (code: number): boolean =>
+  GO_SPACE.has(code) || (code >= 0x2000 && code <= 0x200a)
+
+/**
+ * `strings.TrimSpace`. JS `trim()` differs at both ends of the table: it does
+ * not strip U+0085 (NEL) and it does strip U+FEFF, neither of which matches Go.
+ */
+export const goTrimSpace = (value: string): string => {
+  let start = 0
+  let end = value.length
+  while (start < end && isGoSpace(value.charCodeAt(start))) start++
+  while (end > start && isGoSpace(value.charCodeAt(end - 1))) end--
+  return value.slice(start, end)
+}
+
+/** `strings.Cut(s, sep)` — split at the FIRST occurrence only. */
+const cut = (value: string, separator: string): readonly [string, string] => {
+  const index = value.indexOf(separator)
+  return index < 0 ? [value, ""] : [value.slice(0, index), value.slice(index + separator.length)]
+}
+
+/**
+ * `strconv.Atoi`, including its refusal of whitespace, underscores, decimal
+ * points and exponents, and its out-of-range failure past int64. Returns
+ * `undefined` where Go returns an error.
+ */
+const atoi = (text: string): number | undefined => {
+  if (!/^[+-]?[0-9]+$/.test(text)) return undefined
+  const value = BigInt(text)
+  // Go's `int` is 64-bit on every platform oytc ships for.
+  if (value > 9223372036854775807n || value < -9223372036854775808n) return undefined
+  return Number(value)
+}
+
+export interface ParsedVersion {
+  /** major, minor, patch. */
+  readonly numbers: readonly [number, number, number]
+  /** Prerelease text after the first `-`, or `""`. */
+  readonly prerelease: string
+}
+
+/**
+ * `parseVersion`. Returns `undefined` when the tag is not a `x.y.z` core with
+ * an optional `-prerelease` and optional `+build` metadata.
+ *
+ * Faithful oddities, verified against Go:
+ *   - build metadata is stripped from the CORE only, so `1.2.3-rc.1+b` keeps a
+ *     prerelease of `rc.1+b`;
+ *   - a leading `+` does NOT parse: `strings.Cut(core, "+")` runs before
+ *     `strconv.Atoi`, so `+1.2.3` empties the core and is rejected even though
+ *     `Atoi("+1")` would have succeeded;
+ *   - `01` is 1, and `1.2.3-` has an empty (i.e. release) prerelease.
+ */
+export const parseVersion = (tag: string): ParsedVersion | undefined => {
+  let text = goTrimSpace(tag)
+  if (text.startsWith("v")) text = text.slice(1)
+  if (text === "") return undefined
+
+  const [beforeDash, prerelease] = cut(text, "-")
+  const [core] = cut(beforeDash, "+")
+
+  const parts = core.split(".")
+  if (parts.length !== 3) return undefined
+
+  const numbers: Array = []
+  for (const part of parts) {
+    const value = atoi(part)
+    if (value === undefined || value < 0) return undefined
+    numbers.push(value)
+  }
+  return { numbers: [numbers[0]!, numbers[1]!, numbers[2]!], prerelease }
+}
+
+export type VersionOrder = -1 | 0 | 1
+
+export interface VersionComparison {
+  /** `-1` when a < b, `0` when equal, `1` when a > b. `0` when incomparable. */
+  readonly order: VersionOrder
+  /** False when either side failed to parse; `order` is then meaningless. */
+  readonly comparable: boolean
+}
+
+const INCOMPARABLE: VersionComparison = { order: 0, comparable: false }
+
+/**
+ * `CompareVersions(a, b)`. Compares major/minor/patch numerically, then
+ * tie-breaks on the prerelease: a release outranks any of its prereleases,
+ * and two prereleases compare **byte-wise as strings**.
+ */
+export const compareVersions = (a: string, b: string): VersionComparison => {
+  const left = parseVersion(a)
+  const right = parseVersion(b)
+  if (left === undefined || right === undefined) return INCOMPARABLE
+
+  for (let i = 0; i < 3; i++) {
+    const x = left.numbers[i]!
+    const y = right.numbers[i]!
+    if (x !== y) return { order: x < y ? -1 : 1, comparable: true }
+  }
+
+  if (left.prerelease === right.prerelease) return { order: 0, comparable: true }
+  if (left.prerelease === "") return { order: 1, comparable: true }
+  if (right.prerelease === "") return { order: -1, comparable: true }
+  return {
+    order: compareUtf8(left.prerelease, right.prerelease) < 0 ? -1 : 1,
+    comparable: true
+  }
+}
diff --git a/src/impl/skillInstaller.test.ts b/src/impl/skillInstaller.test.ts
new file mode 100644
index 0000000..3e778bf
--- /dev/null
+++ b/src/impl/skillInstaller.test.ts
@@ -0,0 +1,326 @@
+/**
+ * Ports `internal/skill/install_test.go` (2 cases).
+ *
+ * `TestInstallFSWritesAndReplacesCompleteSkill` substituted an `fstest.MapFS`
+ * for the embedded bundle. The TS bundle is a static import, so the real
+ * content is installed and the assertions check for content that must be
+ * present rather than for fixture strings — the two properties the Go test
+ * actually guards are unchanged and asserted verbatim:
+ *
+ *   - a pre-existing `stale.md` inside the target does NOT survive the swap
+ *   - no `.oytc-*-*` directory is left behind in the parent
+ *
+ * `TestBundledSkillIsComplete` checks the three embedded files are present
+ * and non-empty.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import * as fsSync from "node:fs"
+import * as os from "node:os"
+import * as nodePath from "node:path"
+import { Cause, Effect, Exit, FileSystem, Layer, Path, PlatformError } from "effect"
+import { BunServices } from "@effect/platform-bun"
+import { bundledSkillFileNames, bundledSkillFiles } from "../skills/bundle.ts"
+import { installSkill, makeSkillInstaller } from "./skillInstaller.ts"
+import { ProcessEnv, type ProcessEnvShape } from "../services/index.ts"
+import { OperationalError } from "../domain/errors.ts"
+
+const run = (
+  effect: Effect.Effect
+): Promise => Effect.runPromise(effect.pipe(Effect.provide(BunServices.layer)))
+
+let root: string
+
+beforeEach(() => {
+  root = fsSync.mkdtempSync(nodePath.join(os.tmpdir(), "oytc-skill-test-"))
+})
+
+afterEach(() => {
+  fsSync.rmSync(root, { recursive: true, force: true })
+})
+
+const targetPath = (): string => nodePath.join(root, ".agents", "skills", "oytc")
+
+/** The Go test's `filepath.Glob(dir, ".oytc-*-*")`. */
+const strayTempDirs = (parent: string): ReadonlyArray =>
+  fsSync.existsSync(parent)
+    ? fsSync
+        .readdirSync(parent)
+        .filter((name) => /^\.oytc-.*-.*$/.test(name))
+        .sort()
+    : []
+
+/** The `OperationalError.message` inside a failed `Exit`, or "" if absent. */
+const operationalMessage = (exit: Exit.Exit): string => {
+  if (exit._tag !== "Failure") return ""
+  const error = Cause.findErrorOption(exit.cause)
+  return error._tag === "Some" && error.value instanceof OperationalError ? error.value.message : ""
+}
+
+/**
+ * The real Bun filesystem with the staging swap sabotaged, so the rollback
+ * path in step 5 is actually executed rather than argued about.
+ */
+const failingRenameLayer = (): Layer.Layer =>
+  Layer.effect(
+    FileSystem.FileSystem,
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem
+      return {
+        ...fs,
+        rename: (oldPath: string, newPath: string) =>
+          oldPath.includes(".oytc-install-")
+            ? Effect.fail(
+                PlatformError.systemError({
+                  _tag: "PermissionDenied",
+                  module: "FileSystem",
+                  method: "rename",
+                  pathOrDescriptor: newPath
+                })
+              )
+            : fs.rename(oldPath, newPath)
+      } satisfies FileSystem.FileSystem
+    })
+  ).pipe(Layer.provideMerge(BunServices.layer))
+
+describe("installSkill", () => {
+  // internal/skill/install_test.go: TestInstallFSWritesAndReplacesCompleteSkill
+  test("writes the complete skill and replaces an existing install wholesale", async () => {
+    const target = targetPath()
+    fsSync.mkdirSync(target, { recursive: true, mode: 0o755 })
+    fsSync.writeFileSync(nodePath.join(target, "stale.md"), "stale", { mode: 0o644 })
+
+    const result = await run(installSkill(target))
+    expect(result.path).toBe(target)
+    expect(result.files).toEqual(bundledSkillFileNames)
+
+    for (const file of bundledSkillFiles) {
+      const onDisk = fsSync.readFileSync(nodePath.join(target, ...file.name.split("/")), "utf8")
+      expect(onDisk).toBe(file.content)
+    }
+
+    // The whole point of the swap: user-added files are destroyed.
+    expect(fsSync.existsSync(nodePath.join(target, "stale.md"))).toBe(false)
+
+    // No staging or backup directory survives.
+    expect(strayTempDirs(nodePath.dirname(target))).toEqual([])
+  })
+
+  test("creates the skill from nothing when the target does not exist", async () => {
+    const target = targetPath()
+    expect(fsSync.existsSync(target)).toBe(false)
+
+    await run(installSkill(target))
+
+    for (const name of bundledSkillFileNames) {
+      expect(fsSync.existsSync(nodePath.join(target, ...name.split("/")))).toBe(true)
+    }
+    expect(strayTempDirs(nodePath.dirname(target))).toEqual([])
+  })
+
+  test("is idempotent — installing twice leaves the same tree and no temp dirs", async () => {
+    const target = targetPath()
+    await run(installSkill(target))
+    await run(installSkill(target))
+
+    expect(fsSync.readdirSync(target).sort()).toEqual(["SKILL.md", "references"])
+    expect(fsSync.readdirSync(nodePath.join(target, "references")).sort()).toEqual([
+      "commands.md",
+      "recipes.md"
+    ])
+    expect(strayTempDirs(nodePath.dirname(target))).toEqual([])
+  })
+
+  test("installs 0644 files inside 0755 directories, not 0600/0700", async () => {
+    const target = targetPath()
+    await run(installSkill(target))
+
+    const mode = (...segments: ReadonlyArray): number =>
+      fsSync.statSync(nodePath.join(target, ...segments)).mode & 0o777
+
+    expect(mode()).toBe(0o755)
+    expect(mode("references")).toBe(0o755)
+    expect(mode("SKILL.md")).toBe(0o644)
+    expect(mode("references", "commands.md")).toBe(0o644)
+    expect(mode("references", "recipes.md")).toBe(0o644)
+  })
+
+  test("a stale 0700/0600 install is re-hardened to 0755/0644 by the swap", async () => {
+    const target = targetPath()
+    fsSync.mkdirSync(target, { recursive: true, mode: 0o700 });
+    fsSync.chmodSync(target, 0o700)
+    fsSync.writeFileSync(nodePath.join(target, "SKILL.md"), "old", { mode: 0o600 })
+
+    await run(installSkill(target))
+
+    expect(fsSync.statSync(target).mode & 0o777).toBe(0o755)
+    expect(fsSync.statSync(nodePath.join(target, "SKILL.md")).mode & 0o777).toBe(0o644)
+  })
+
+  test("a restrictive umask does not leak into the installed tree", async () => {
+    // `mode` on create is masked by umask: under 077 the kernel would produce
+    // 0700/0600 and the skill would be unreadable by the other agents it exists
+    // to serve. Only the explicit chmods make the result stable.
+    const target = targetPath()
+    const previous = process.umask(0o077)
+    try {
+      await run(installSkill(target))
+    } finally {
+      process.umask(previous)
+    }
+
+    const mode = (...segments: ReadonlyArray): number =>
+      fsSync.statSync(nodePath.join(target, ...segments)).mode & 0o777
+
+    expect(mode()).toBe(0o755)
+    expect(mode("references")).toBe(0o755)
+    expect(mode("SKILL.md")).toBe(0o644)
+    expect(mode("references", "recipes.md")).toBe(0o644)
+  })
+
+  test("a DANGLING SYMLINK at the target is replaced, matching Go's Lstat", async () => {
+    // `stat` follows symlinks, so a broken link reports NotFound where Go's
+    // Lstat reported "exists". Skipping the backup branch would leave the link
+    // in place and `rename(stage, target)` would fail with ENOTDIR.
+    const parent = nodePath.join(root, ".agents", "skills")
+    fsSync.mkdirSync(parent, { recursive: true })
+    const target = nodePath.join(parent, "oytc")
+    fsSync.symlinkSync(nodePath.join(root, "nowhere-at-all"), target)
+
+    await run(installSkill(target))
+
+    expect(fsSync.lstatSync(target).isSymbolicLink()).toBe(false)
+    expect(fsSync.statSync(target).isDirectory()).toBe(true)
+    expect(fsSync.existsSync(nodePath.join(target, "SKILL.md"))).toBe(true)
+    expect(strayTempDirs(parent)).toEqual([])
+  })
+
+  test("creates every missing parent directory", async () => {
+    const target = nodePath.join(root, "deep", "nested", "chain", "oytc")
+    await run(installSkill(target))
+    expect(fsSync.existsSync(nodePath.join(target, "SKILL.md"))).toBe(true)
+  })
+
+  test("a plain FILE at the target is moved aside and replaced, not merged into", async () => {
+    // Go's Lstat succeeds on a file, so the backup/rename path runs and the
+    // file ends up deleted along with the backup.
+    const parent = nodePath.join(root, ".agents", "skills")
+    fsSync.mkdirSync(parent, { recursive: true })
+    const target = nodePath.join(parent, "oytc")
+    fsSync.writeFileSync(target, "not a directory")
+
+    await run(installSkill(target))
+
+    expect(fsSync.statSync(target).isDirectory()).toBe(true)
+    expect(fsSync.existsSync(nodePath.join(target, "SKILL.md"))).toBe(true)
+    expect(strayTempDirs(parent)).toEqual([])
+  })
+
+  test("rolls the previous install back and cleans up when the swap fails", async () => {
+    const target = targetPath()
+    // A complete previous install, so there is something to roll back to.
+    await run(installSkill(target))
+    fsSync.writeFileSync(nodePath.join(target, "marker.md"), "previous")
+
+    const exit = await Effect.runPromise(
+      installSkill(target).pipe(Effect.provide(failingRenameLayer()), Effect.exit)
+    )
+
+    expect(exit._tag).toBe("Failure")
+    expect(operationalMessage(exit)).toStartWith("install skill: ")
+
+    // The old install is back where it was, contents intact.
+    expect(fsSync.readFileSync(nodePath.join(target, "marker.md"), "utf8")).toBe("previous")
+    expect(fsSync.existsSync(nodePath.join(target, "SKILL.md"))).toBe(true)
+    expect(strayTempDirs(nodePath.dirname(target))).toEqual([])
+  })
+
+  test("wraps a filesystem failure in an OperationalError with Go's prefix", async () => {
+    // An unwritable parent makes step 1 (`MkdirAll`) fail.
+    const locked = nodePath.join(root, "locked")
+    fsSync.mkdirSync(locked, { mode: 0o500 })
+    const target = nodePath.join(locked, "sub", "oytc")
+
+    const exit = await Effect.runPromise(
+      installSkill(target).pipe(Effect.provide(BunServices.layer), Effect.exit)
+    )
+    expect(exit._tag).toBe("Failure")
+    expect(operationalMessage(exit)).toStartWith("create skills directory: ")
+    fsSync.chmodSync(locked, 0o700)
+  })
+})
+
+describe("bundled skill", () => {
+  // internal/skill/install_test.go: TestBundledSkillIsComplete
+  test("all three embedded files are present and non-empty", () => {
+    expect(bundledSkillFiles).toHaveLength(3)
+    for (const file of bundledSkillFiles) {
+      expect(file.content.length).toBeGreaterThan(0)
+    }
+  })
+
+  test("the file list is the hardcoded Go list, in order", () => {
+    expect(bundledSkillFileNames).toEqual([
+      "SKILL.md",
+      "references/commands.md",
+      "references/recipes.md"
+    ])
+  })
+
+  test("SKILL.md carries the frontmatter CI validates and the security clause", () => {
+    const skill = bundledSkillFiles[0]!.content
+    expect(skill).toStartWith("---\n")
+    expect(skill).toContain("name: oytc")
+    const description = /^description: (.+)$/m.exec(skill)?.[1]
+    expect(description).toBeDefined()
+    expect(description!.length).toBeGreaterThan(0)
+    expect(description!.length).toBeLessThan(1024)
+    expect(skill).toContain("Query public YouTube data")
+    expect(skill).toContain("Never print, log, or echo API keys")
+  })
+})
+
+describe("SkillInstaller service", () => {
+  const envLayer = (home: Effect.Effect) =>
+    Effect.provideService(ProcessEnv, {
+      env: () => ({ _tag: "None" }) as never,
+      platform: process.platform,
+      arch: process.arch,
+      argv: [],
+      executablePath: Effect.succeed("/bin/oytc"),
+      isOutputTTY: false,
+      homeDir: home
+    } satisfies ProcessEnvShape)
+
+  test("defaultPath is /.agents/skills/oytc", async () => {
+    const installer = await Effect.runPromise(
+      makeSkillInstaller.pipe(envLayer(Effect.succeed(root)), Effect.provide(BunServices.layer))
+    )
+    const path = await Effect.runPromise(installer.defaultPath)
+    expect(path).toBe(nodePath.join(root, ".agents", "skills", "oytc"))
+  })
+
+  test("defaultPath surfaces Go's 'find home directory' prefix", async () => {
+    const installer = await Effect.runPromise(
+      makeSkillInstaller.pipe(
+        envLayer(Effect.fail(new OperationalError({ message: "no home" }))),
+        Effect.provide(BunServices.layer)
+      )
+    )
+    const exit = await Effect.runPromise(installer.defaultPath.pipe(Effect.exit))
+    expect(exit._tag).toBe("Failure")
+    expect(operationalMessage(exit)).toBe("find home directory: no home")
+  })
+
+  test("install through the service writes the bundle", async () => {
+    const installer = await Effect.runPromise(
+      makeSkillInstaller.pipe(envLayer(Effect.succeed(root)), Effect.provide(BunServices.layer))
+    )
+    const target = targetPath()
+    const result = await Effect.runPromise(installer.install(target))
+    expect(result.path).toBe(target)
+    expect(fsSync.readFileSync(nodePath.join(target, "SKILL.md"), "utf8")).toBe(
+      bundledSkillFiles[0]!.content
+    )
+  })
+})
diff --git a/src/impl/skillInstaller.ts b/src/impl/skillInstaller.ts
index ca14f9a..edd4798 100644
--- a/src/impl/skillInstaller.ts
+++ b/src/impl/skillInstaller.ts
@@ -1,2 +1,206 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `SkillInstaller` — the port of `internal/skill/install.go`.
+ *
+ * The install is an **atomic directory swap**, not a merge:
+ *
+ *   1. `mkdir -p` the parent at 0755.
+ *   2. Build the whole new skill in a staging dir `.oytc-install-*` created in
+ *      that same parent (same filesystem, so the rename in step 5 is atomic).
+ *      `chmod 0755` the staging dir — `mkdtemp` creates it 0700.
+ *   3. Write each of the three bundled files at 0644, creating `references/`
+ *      at 0755. The list comes from `skills/bundle.ts` and is hardcoded.
+ *   4. If the target exists, reserve a free name by creating a second temp dir
+ *      `.oytc-backup-*` and immediately removing it, then rename the existing
+ *      install onto that reserved name.
+ *   5. Rename staging -> target. On failure, roll the backup back into place.
+ *   6. Delete the backup.
+ *
+ * Consequences worth stating plainly, because they are load-bearing:
+ *
+ * - **Any user-added file under the target is destroyed.** Go's test asserts
+ *   exactly this with a `stale.md` that must not survive. It is a replacement,
+ *   not a merge, so a reader never observes a half-written skill.
+ * - **No `.oytc-*-*` directory may survive.** Go used `defer os.RemoveAll(stage)`
+ *   on every path; here `Effect.onExit` does the same job, and it runs on
+ *   interruption as well as on failure. The backup name is only ever a
+ *   directory between steps 4 and 6.
+ *
+ * Permissions are 0755/0644 and NOT the 0700/0600 of the credential file: the
+ * skill is non-secret content meant to be read by other agents.
+ */
+
+import { Effect, FileSystem, Layer, Path } from "effect"
+import { OperationalError } from "../domain/errors.ts"
+import {
+  ProcessEnv,
+  SkillInstaller,
+  type ProcessEnvShape,
+  type SkillInstallerShape,
+  type SkillInstallResult
+} from "../services/index.ts"
+import { bundledSkillFileNames, bundledSkillFiles } from "../skills/bundle.ts"
+
+const DIRECTORY_MODE = 0o755
+const FILE_MODE = 0o644
+
+/** Go rendered `%w` as the wrapped error's message; PlatformError's is close enough. */
+const describe = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause)
+
+const fail = (message: string) => (cause: unknown) =>
+  Effect.fail(new OperationalError({ message: `${message}: ${describe(cause)}`, cause }))
+
+/** Ignore every failure, including defects — used for the temp-dir cleanups. */
+const bestEffort = (effect: Effect.Effect): Effect.Effect =>
+  Effect.ignoreCause(effect)
+
+/**
+ * Whether `target` exists, following Go's `os.Lstat` + `os.IsNotExist` split:
+ * a "not found" is `false`, and any *other* stat failure is fatal.
+ *
+ * Effect's `FileSystem` has no `lstat`, and `stat` follows symlinks — so a
+ * **dangling symlink** at the target would report "not found" where Go's
+ * `Lstat` reported "exists". That is not benign: skipping the backup branch
+ * leaves the broken link in place, and `rename(stage, target)` onto an
+ * existing symlink-to-nowhere fails with ENOTDIR (verified on darwin). The
+ * install would break instead of replacing the link.
+ *
+ * `readLink` succeeding is exactly "the path is a symlink", which is the one
+ * case `stat` misses, so the two together reconstruct `Lstat`'s answer.
+ */
+const targetExists = (
+  fs: FileSystem.FileSystem,
+  target: string
+): Effect.Effect =>
+  fs.stat(target).pipe(
+    Effect.as(true),
+    Effect.catch((error) =>
+      error.reason._tag === "NotFound"
+        ? // Either genuinely absent, or a symlink whose target is absent.
+          fs.readLink(target).pipe(
+            Effect.as(true),
+            Effect.catchCause(() => Effect.succeed(false))
+          )
+        : fail("inspect existing skill")(error)
+    )
+  )
+
+/**
+ * Install the bundled skill into `target`, replacing whatever is there.
+ *
+ * Exported separately from the service so tests can drive it directly, the
+ * way Go's tests called the unexported `installFS`.
+ */
+export const installSkill = (
+  target: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+    const parent = path.dirname(target)
+
+    yield* fs
+      .makeDirectory(parent, { recursive: true, mode: DIRECTORY_MODE })
+      .pipe(Effect.catch(fail("create skills directory")))
+
+    const stage = yield* fs
+      .makeTempDirectory({ directory: parent, prefix: ".oytc-install-" })
+      .pipe(Effect.catch(fail("stage skill installation")))
+
+    // Everything below runs under a guaranteed cleanup of the staging dir —
+    // Go's `defer os.RemoveAll(stage)`. After a successful swap nothing exists
+    // under that name any more, so the removal is a no-op.
+    const install = Effect.gen(function* () {
+      // mkdtemp creates 0700; the installed skill directory must be 0755.
+      yield* fs.chmod(stage, DIRECTORY_MODE).pipe(Effect.catch(fail("stage skill installation")))
+
+      for (const file of bundledSkillFiles) {
+        const destination = path.join(stage, ...file.name.split("/"))
+        const directory = path.dirname(destination)
+        yield* fs
+          .makeDirectory(directory, { recursive: true, mode: DIRECTORY_MODE })
+          .pipe(Effect.catch(fail("create skill references directory")))
+        // `mode` on create is masked by umask (022 happens to yield 0755/0644,
+        // but 077 would give 0700/0600). Go had the same hole and shipped it;
+        // the explicit chmod makes the installed tree stable regardless, which
+        // matters because these files exist to be read by *other* agents.
+        if (directory !== stage) {
+          yield* fs
+            .chmod(directory, DIRECTORY_MODE)
+            .pipe(Effect.catch(fail("create skill references directory")))
+        }
+        yield* fs
+          .writeFileString(destination, file.content, { mode: FILE_MODE })
+          .pipe(Effect.catch(fail(`write ${file.name}`)))
+        yield* fs.chmod(destination, FILE_MODE).pipe(Effect.catch(fail(`write ${file.name}`)))
+      }
+
+      // Reserve a free name for the outgoing install: create a temp dir, then
+      // remove it so only the *name* is held. Go did exactly this.
+      const exists = yield* targetExists(fs, target)
+      const backup = exists
+        ? yield* fs.makeTempDirectory({ directory: parent, prefix: ".oytc-backup-" }).pipe(
+            Effect.catch(fail("prepare existing skill backup")),
+            Effect.tap((directory) =>
+              fs
+                .remove(directory, { recursive: true })
+                .pipe(Effect.catch(fail("prepare existing skill backup")))
+            )
+          )
+        : undefined
+
+      if (backup !== undefined) {
+        yield* fs.rename(target, backup).pipe(Effect.catch(fail("move existing skill aside")))
+      }
+
+      yield* fs.rename(stage, target).pipe(
+        Effect.catch((error) =>
+          Effect.gen(function* () {
+            // Roll back: put the old install back where it was. Go ignored the
+            // rollback's own error and reported the swap failure.
+            if (backup !== undefined) yield* bestEffort(fs.rename(backup, target))
+            return yield* fail("install skill")(error)
+          })
+        )
+      )
+
+      if (backup !== undefined) {
+        yield* fs
+          .remove(backup, { recursive: true })
+          .pipe(Effect.catch(fail("remove replaced skill")))
+      }
+
+      return { path: target, files: bundledSkillFileNames } satisfies SkillInstallResult
+    })
+
+    return yield* install.pipe(
+      Effect.onExit(() => bestEffort(fs.remove(stage, { recursive: true, force: true })))
+    )
+  })
+
+export const makeSkillInstaller: Effect.Effect<
+  SkillInstallerShape,
+  never,
+  ProcessEnvShape | FileSystem.FileSystem | Path.Path
+> = Effect.gen(function* () {
+  const env = yield* ProcessEnv
+  const fs = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+
+  return {
+    /** Go's `DefaultPath()`: `/.agents/skills/oytc`. There is no env override. */
+    defaultPath: env.homeDir.pipe(
+      Effect.map((home) => path.join(home, ".agents", "skills", "oytc")),
+      Effect.mapError(
+        (error) => new OperationalError({ message: `find home directory: ${error.message}` })
+      )
+    ),
+    install: (target) =>
+      installSkill(target).pipe(
+        Effect.provideService(FileSystem.FileSystem, fs),
+        Effect.provideService(Path.Path, path)
+      )
+  } satisfies SkillInstallerShape
+})
+
+export const SkillInstallerLive = Layer.effect(SkillInstaller, makeSkillInstaller)
diff --git a/src/impl/tokenSource.test.ts b/src/impl/tokenSource.test.ts
new file mode 100644
index 0000000..ee82c42
--- /dev/null
+++ b/src/impl/tokenSource.test.ts
@@ -0,0 +1,196 @@
+/**
+ * Ports `TestTokenSourceRefreshAndOnUpdate` plus the skew/persistence/re-hint
+ * behavior the Go code specifies but does not directly test.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+// `effect/testing` is a stable subpath, so the src/effect.ts barrel rule does not
+// apply to it (that rule covers the unstable subpath only).
+import { TestClock } from "effect/testing"
+import { OAuthError, OperationalError } from "../domain/errors.ts"
+import { ExpiredAuthorizationError, type OAuthToken } from "./oauth.ts"
+import { EXPIRY_SKEW_MILLIS, makeTokenSource } from "./tokenSource.ts"
+
+const NOW = Date.UTC(2026, 0, 1, 0, 0, 0)
+
+const token = (overrides: Partial = {}): OAuthToken => ({
+  accessToken: "old-access",
+  refreshToken: "refresh",
+  expiryMillis: NOW + 3_600_000,
+  scopes: ["scope"],
+  ...overrides
+})
+
+/**
+ * Runs against a controlled clock pinned to NOW, so the 1-minute skew window is
+ * exercised at exact boundaries rather than by sleeping.
+ */
+const atNow = (effect: Effect.Effect): Promise =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      yield* TestClock.setTime(NOW)
+      return yield* effect
+    }).pipe(Effect.provide(TestClock.layer()))
+  )
+
+interface Recorder {
+  readonly refreshes: Array
+  readonly persisted: Array
+}
+
+const sourceWith = (
+  options: {
+    readonly token?: OAuthToken
+    readonly refreshed?: OAuthToken
+    readonly refreshFails?: OAuthError | OperationalError
+    readonly persistFails?: OperationalError
+  } = {}
+) => {
+  const recorder: Recorder = { refreshes: [], persisted: [] }
+  const handle = makeTokenSource({
+    token: options.token ?? token({ expiryMillis: NOW - 60_000 }),
+    refresh: (current) =>
+      Effect.gen(function* () {
+        recorder.refreshes.push(current)
+        if (options.refreshFails !== undefined) return yield* Effect.fail(options.refreshFails)
+        return (
+          options.refreshed ?? {
+            accessToken: "new-access",
+            refreshToken: current.refreshToken,
+            expiryMillis: NOW + 3_600_000,
+            scopes: current.scopes
+          }
+        )
+      }),
+    onUpdate: (updated) =>
+      Effect.gen(function* () {
+        if (options.persistFails !== undefined) return yield* Effect.fail(options.persistFails)
+        recorder.persisted.push(updated)
+      })
+  })
+  return { handle, recorder }
+}
+
+describe("TokenSource", () => {
+  test("refreshes an expired token and persists the result before returning it", async () => {
+    const { handle, recorder } = sourceWith()
+    const access = await atNow(handle.accessToken(false))
+    expect(access).toBe("new-access")
+    expect(recorder.persisted).toHaveLength(1)
+    expect(recorder.persisted[0]!.accessToken).toBe("new-access")
+    expect(recorder.persisted[0]!.refreshToken).toBe("refresh")
+    expect((await atNow(handle.current)).accessToken).toBe("new-access")
+  })
+
+  test("reuses a token that expires comfortably beyond the skew window", async () => {
+    const { handle, recorder } = sourceWith({ token: token({ expiryMillis: NOW + 600_000 }) })
+    expect(await atNow(handle.accessToken(false))).toBe("old-access")
+    expect(recorder.refreshes).toHaveLength(0)
+  })
+
+  test("refreshes proactively inside the 1-minute skew window", async () => {
+    // Go: reuse iff expiry > now + time.Minute. 30s out is inside the window.
+    const { handle, recorder } = sourceWith({ token: token({ expiryMillis: NOW + 30_000 }) })
+    expect(await atNow(handle.accessToken(false))).toBe("new-access")
+    expect(recorder.refreshes).toHaveLength(1)
+  })
+
+  test("the skew boundary is strict: exactly now+1m refreshes, one millisecond later does not", async () => {
+    const exactly = sourceWith({ token: token({ expiryMillis: NOW + EXPIRY_SKEW_MILLIS }) })
+    expect(await atNow(exactly.handle.accessToken(false))).toBe("new-access")
+
+    const beyond = sourceWith({ token: token({ expiryMillis: NOW + EXPIRY_SKEW_MILLIS + 1 }) })
+    expect(await atNow(beyond.handle.accessToken(false))).toBe("old-access")
+  })
+
+  test("an empty cached access token forces a refresh regardless of expiry", async () => {
+    const { handle, recorder } = sourceWith({
+      token: token({ accessToken: "   ", expiryMillis: NOW + 3_600_000 })
+    })
+    expect(await atNow(handle.accessToken(false))).toBe("new-access")
+    expect(recorder.refreshes).toHaveLength(1)
+  })
+
+  test("force bypasses a perfectly valid cached token (the post-401 path)", async () => {
+    const { handle, recorder } = sourceWith({ token: token({ expiryMillis: NOW + 3_600_000 }) })
+    expect(await atNow(handle.accessToken(true))).toBe("new-access")
+    expect(recorder.refreshes).toHaveLength(1)
+  })
+
+  test("persistence failure keeps the in-memory token unchanged", async () => {
+    const { handle, recorder } = sourceWith({
+      persistFails: new OperationalError({ message: "disk full" })
+    })
+    const error = await atNow(Effect.flip(handle.accessToken(false)))
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toBe("persist refreshed OAuth token: disk full")
+    // The refresh happened, but memory did NOT advance past the failed write.
+    expect(recorder.refreshes).toHaveLength(1)
+    expect((await atNow(handle.current)).accessToken).toBe("old-access")
+  })
+
+  test.each([["invalid_grant"], ["invalid_client"]])(
+    "%s is re-hinted to the re-login message",
+    async (code) => {
+      const { handle } = sourceWith({
+        refreshFails: new OAuthError({ httpStatus: 400, code, description: "revoked" })
+      })
+      const error = await atNow(Effect.flip(handle.accessToken(false)))
+      expect(error).toBeInstanceOf(ExpiredAuthorizationError)
+      expect(error.message).toBe(
+        "OAuth authorization is expired or revoked; re-run 'oytc login --oauth': " +
+          `OAuth error (${code}): revoked`
+      )
+      // Still classified as an OAuthError, so the exit code stays 3.
+      expect(error).toBeInstanceOf(OAuthError)
+    }
+  )
+
+  test("other OAuth error codes pass through unchanged", async () => {
+    const original = new OAuthError({
+      httpStatus: 500,
+      code: "server_error",
+      description: "try later"
+    })
+    const { handle } = sourceWith({ refreshFails: original })
+    const error = await atNow(Effect.flip(handle.accessToken(false)))
+    expect(error).toBe(original)
+    expect(error.message).toBe("OAuth error (server_error): try later")
+  })
+
+  test("a non-OAuth refresh failure passes through unchanged", async () => {
+    const original = new OperationalError({ message: "refresh OAuth token: connection refused" })
+    const { handle } = sourceWith({ refreshFails: original })
+    expect(await atNow(Effect.flip(handle.accessToken(false)))).toBe(original)
+  })
+
+  test("concurrent callers serialize: only one refresh is issued", async () => {
+    const { handle, recorder } = sourceWith()
+    const results = await atNow(
+      Effect.all([handle.accessToken(false), handle.accessToken(false), handle.accessToken(false)], {
+        concurrency: "unbounded"
+      })
+    )
+    expect(results).toEqual(["new-access", "new-access", "new-access"])
+    // The second and third callers find a fresh cached token behind the mutex.
+    expect(recorder.refreshes).toHaveLength(1)
+    expect(recorder.persisted).toHaveLength(1)
+  })
+
+  test("a refreshed token with a zero expiry is never cached", async () => {
+    // expiryMillis 0 is Go's zero time; 0 > now + skew is false, so every call
+    // refreshes again rather than serving a token of unknown lifetime.
+    const { handle, recorder } = sourceWith({
+      refreshed: {
+        accessToken: "new-access",
+        refreshToken: "refresh",
+        expiryMillis: 0,
+        scopes: ["scope"]
+      }
+    })
+    await atNow(handle.accessToken(false))
+    await atNow(handle.accessToken(false))
+    expect(recorder.refreshes).toHaveLength(2)
+  })
+})
diff --git a/src/impl/tokenSource.ts b/src/impl/tokenSource.ts
index ca14f9a..e609512 100644
--- a/src/impl/tokenSource.ts
+++ b/src/impl/tokenSource.ts
@@ -1,2 +1,99 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * The self-persisting access-token cache.
+ *
+ * Go's `oauth.TokenSource` is a mutex-guarded struct; this is the same state
+ * machine with a `Semaphore(1)` standing in for the mutex, so two concurrent
+ * requests cannot both fire a refresh. The three details that matter:
+ *
+ *   1. **1-minute skew.** The cached token is reused only while
+ *      `expiry > now + 1 minute`. A token expiring in 30 s is refreshed
+ *      proactively, so an in-flight request cannot be handed a token that dies
+ *      before the server sees it.
+ *   2. **`onUpdate` runs BEFORE the in-memory update.** If persisting fails, the
+ *      in-memory token is left untouched and the call fails with
+ *      `persist refreshed OAuth token: `. Advancing memory first would let
+ *      a later run read a stale file while this run believed it was current.
+ *   3. **`invalid_grant` / `invalid_client`** — the two codes Google returns for
+ *      a revoked or deleted authorization — are re-hinted to
+ *      `OAuth authorization is expired or revoked; re-run 'oytc login --oauth'`.
+ *      Any other OAuth error is passed through unchanged.
+ */
+
+import { Clock, Effect, Ref, Semaphore } from "effect"
+import { OAuthError, OperationalError } from "../domain/errors.ts"
+import { ExpiredAuthorizationError, type OAuthToken } from "./oauth.ts"
+
+/** Go's `time.Minute` skew buffer. */
+export const EXPIRY_SKEW_MILLIS = 60_000
+
+export interface TokenSourceOptions {
+  readonly token: OAuthToken
+  readonly refresh: (
+    current: OAuthToken
+  ) => Effect.Effect
+  /** Persist hook; runs before the in-memory token advances. */
+  readonly onUpdate: (updated: OAuthToken) => Effect.Effect
+}
+
+export interface TokenSourceHandle {
+  /** `force` bypasses the cache — used exactly once after a 401. */
+  readonly accessToken: (
+    force: boolean
+  ) => Effect.Effect
+  /** The current in-memory token; for tests and for `status`. */
+  readonly current: Effect.Effect
+}
+
+const isExpiredAuthorization = (error: OAuthError): boolean =>
+  error.code === "invalid_grant" || error.code === "invalid_client"
+
+export const makeTokenSource = (options: TokenSourceOptions): TokenSourceHandle => {
+  const state = Ref.makeUnsafe(options.token)
+  const gate = Semaphore.makeUnsafe(1)
+
+  const accessToken = (force: boolean): Effect.Effect =>
+    Semaphore.withPermit(
+      gate,
+      Effect.gen(function* () {
+        const current = yield* Ref.get(state)
+        const now = yield* Clock.currentTimeMillis
+        if (
+          !force &&
+          current.accessToken.trim() !== "" &&
+          current.expiryMillis > now + EXPIRY_SKEW_MILLIS
+        ) {
+          return current.accessToken
+        }
+
+        const updated = yield* options.refresh(current).pipe(
+          Effect.catch((error) =>
+            Effect.fail(
+              error instanceof OAuthError && isExpiredAuthorization(error)
+                ? new ExpiredAuthorizationError({
+                    httpStatus: error.httpStatus,
+                    code: error.code,
+                    description: error.description
+                  })
+                : error
+            )
+          )
+        )
+
+        // Persist first: a failed write must not leave memory ahead of disk.
+        yield* options.onUpdate(updated).pipe(
+          Effect.catch((cause) =>
+            Effect.fail(
+              new OperationalError({
+                message: `persist refreshed OAuth token: ${cause.message}`,
+                cause
+              })
+            )
+          )
+        )
+        yield* Ref.set(state, updated)
+        return updated.accessToken
+      })
+    )
+
+  return { accessToken, current: Ref.get(state) }
+}
diff --git a/src/impl/updater.test.ts b/src/impl/updater.test.ts
new file mode 100644
index 0000000..81df346
--- /dev/null
+++ b/src/impl/updater.test.ts
@@ -0,0 +1,1304 @@
+import { afterAll, describe, expect, test } from "bun:test"
+import { createHash } from "node:crypto"
+import { gzipSync } from "node:zlib"
+import { Effect, Exit, FileSystem, Layer, PlatformError } from "effect"
+import { BunServices } from "@effect/platform-bun"
+import { FetchHttpClient } from "../effect.ts"
+import { encodeGoStruct } from "../json/encode.ts"
+import { assetName } from "./platformMatrix.ts"
+import {
+  CHECKSUMS_NAME,
+  guardManagedInstall,
+  parseChecksums,
+  parseRelease,
+  runUpdate,
+  toUpdateResult,
+  type UpdaterConfig,
+  type UpdateRunResult
+} from "./updater.ts"
+
+// ---------------------------------------------------------------------------
+// Fixture — the TS analogue of the Go tests' httptest.Server + t.TempDir()
+// ---------------------------------------------------------------------------
+
+const encoder = new TextEncoder()
+const bytes = (text: string): Uint8Array => encoder.encode(text)
+
+const sha256Hex = (data: Uint8Array): string => createHash("sha256").update(data).digest("hex")
+
+/**
+ * A GitHub release payload. Built with the project's own encoder rather than
+ * the stock one, which CI confines to `src/json/encode.ts`.
+ */
+const releaseJson = (
+  tag: string,
+  assets: ReadonlyArray<{ readonly name: string; readonly browser_download_url: string }>
+): string =>
+  encodeGoStruct(
+    [
+      ["tag_name", tag],
+      ["prerelease", false],
+      [
+        "assets",
+        assets.map((a) => ({ name: a.name, browser_download_url: a.browser_download_url }))
+      ]
+    ],
+    { indent: "" }
+  )
+
+// Archive builders are duplicated from archive.test.ts rather than imported:
+// importing a test module would re-register its suites in this file's run.
+
+const octal = (v: number, width: number): string => v.toString(8).padStart(width - 1, "0") + "\0"
+
+const tarGzWithEntry = (name: string, content: Uint8Array): Uint8Array => {
+  const header = new Uint8Array(512)
+  const put = (offset: number, t: string) => header.set(encoder.encode(t), offset)
+  put(0, name.slice(0, 100))
+  put(100, octal(0o755, 8))
+  put(108, octal(0, 8))
+  put(116, octal(0, 8))
+  put(124, octal(content.length, 12))
+  put(136, octal(0, 12))
+  header[156] = "0".charCodeAt(0)
+  put(257, "ustar\0")
+  put(263, "00")
+  header.fill(0x20, 148, 156)
+  let sum = 0
+  for (const byte of header) sum += byte
+  put(148, `${sum.toString(8).padStart(6, "0")}\0 `)
+
+  const padding = (512 - (content.length % 512)) % 512
+  const tar = new Uint8Array(512 + content.length + padding + 1024)
+  tar.set(header, 0)
+  tar.set(content, 512)
+  return new Uint8Array(gzipSync(tar))
+}
+
+const crcTable = (() => {
+  const table = new Uint32Array(256)
+  for (let i = 0; i < 256; i++) {
+    let c = i
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    table[i] = c >>> 0
+  }
+  return table
+})()
+
+const crc32 = (data: Uint8Array): number => {
+  let c = 0xffffffff
+  for (const byte of data) c = crcTable[(c ^ byte) & 0xff]! ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+const zipWithEntry = (name: string, content: Uint8Array): Uint8Array => {
+  const nameBytes = encoder.encode(name)
+  const crc = crc32(content)
+  const size = content.length
+
+  const local = new Uint8Array(30 + nameBytes.length + size)
+  const lv = new DataView(local.buffer)
+  lv.setUint32(0, 0x04034b50, true)
+  lv.setUint16(4, 20, true)
+  lv.setUint16(8, 0, true)
+  lv.setUint32(14, crc, true)
+  lv.setUint32(18, size, true)
+  lv.setUint32(22, size, true)
+  lv.setUint16(26, nameBytes.length, true)
+  local.set(nameBytes, 30)
+  local.set(content, 30 + nameBytes.length)
+
+  const central = new Uint8Array(46 + nameBytes.length)
+  const cv = new DataView(central.buffer)
+  cv.setUint32(0, 0x02014b50, true)
+  cv.setUint16(4, 20, true)
+  cv.setUint16(6, 20, true)
+  cv.setUint16(10, 0, true)
+  cv.setUint32(16, crc, true)
+  cv.setUint32(20, size, true)
+  cv.setUint32(24, size, true)
+  cv.setUint16(28, nameBytes.length, true)
+  cv.setUint32(42, 0, true)
+  central.set(nameBytes, 46)
+
+  const eocd = new Uint8Array(22)
+  const ev = new DataView(eocd.buffer)
+  ev.setUint32(0, 0x06054b50, true)
+  ev.setUint16(8, 1, true)
+  ev.setUint16(10, 1, true)
+  ev.setUint32(12, central.length, true)
+  ev.setUint32(16, local.length, true)
+
+  const out = new Uint8Array(local.length + central.length + eocd.length)
+  out.set(local, 0)
+  out.set(central, local.length)
+  out.set(eocd, local.length + central.length)
+  return out
+}
+
+const testLayer = Layer.mergeAll(BunServices.layer, FetchHttpClient.layer)
+
+const run = (effect: Effect.Effect) =>
+  Effect.runPromiseExit(
+    effect.pipe(Effect.provide(testLayer)) as Effect.Effect
+  )
+
+const message = (exit: Exit.Exit): string => {
+  if (Exit.isSuccess(exit)) throw new Error("expected a failure, got success")
+  return String(exit.cause)
+}
+
+const value = (exit: Exit.Exit): A => {
+  if (!Exit.isSuccess(exit)) throw new Error(`expected success, got ${String(exit.cause)}`)
+  return exit.value
+}
+
+interface Fixture {
+  readonly config: UpdaterConfig
+  readonly executable: string
+  readonly assetName: string
+  /** Mutable so a test can corrupt the manifest, as the Go tests do. */
+  checksums: string
+  archive: Uint8Array
+  readonly close: () => void
+}
+
+const servers: Array<{ stop: (force?: boolean) => void }> = []
+
+afterAll(() => {
+  for (const server of servers) server.stop(true)
+})
+
+const newFixture = async (options: {
+  readonly tag: string
+  readonly goos: string
+  readonly goarch: string
+  readonly currentVersion: string
+  readonly binaryContent: string
+  /** Omit the checksums.txt asset from the release payload. */
+  readonly omitChecksumsAsset?: boolean
+  /** Omit the platform archive asset from the release payload. */
+  readonly omitPlatformAsset?: boolean
+}): Promise => {
+  const { currentVersion, goarch, goos, tag } = options
+  const entry = goos === "windows" ? "oytc.exe" : "oytc"
+  const content = bytes(options.binaryContent)
+  const archive =
+    goos === "windows" ? zipWithEntry(entry, content) : tarGzWithEntry(entry, content)
+  const asset = assetName(tag, goos, goarch)
+
+  const state: { checksums: string; archive: Uint8Array } = {
+    checksums: `${sha256Hex(archive)}  ${asset}\n`,
+    archive
+  }
+
+  const dir = `/tmp/oytc-updater-test-${Math.floor(Math.random() * 1e9)}`
+  await Bun.$`mkdir -p ${dir}`.quiet()
+  const executable = `${dir}/oytc`
+  await Bun.write(executable, "old-binary")
+  await Bun.$`chmod 755 ${executable}`.quiet()
+
+  let base = ""
+
+  const releaseBody = () => {
+    const assets: Array<{ name: string; browser_download_url: string }> = []
+    if (options.omitPlatformAsset !== true) {
+      assets.push({ name: asset, browser_download_url: `${base}/assets/${asset}` })
+    }
+    if (options.omitChecksumsAsset !== true) {
+      assets.push({
+        name: CHECKSUMS_NAME,
+        browser_download_url: `${base}/assets/${CHECKSUMS_NAME}`
+      })
+    }
+    return releaseJson(tag, assets)
+  }
+
+  const server = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    fetch(request) {
+      const path = new URL(request.url).pathname
+      if (path === "/repos/owner/repo/releases/latest") {
+        return new Response(releaseBody(), { headers: { "content-type": "application/json" } })
+      }
+      if (path.startsWith("/repos/owner/repo/releases/tags/")) {
+        const requested = path.slice("/repos/owner/repo/releases/tags/".length)
+        if (requested !== tag) return new Response("not found", { status: 404 })
+        return new Response(releaseBody(), { headers: { "content-type": "application/json" } })
+      }
+      if (path.startsWith("/assets/")) {
+        const name = path.slice("/assets/".length)
+        if (name === asset) return new Response(state.archive as BlobPart)
+        if (name === CHECKSUMS_NAME) return new Response(state.checksums)
+      }
+      return new Response("not found", { status: 404 })
+    }
+  })
+  servers.push(server)
+  base = `http://127.0.0.1:${server.port}`
+
+  return {
+    config: {
+      repo: "owner/repo",
+      apiBaseUrl: base,
+      currentVersion,
+      goos,
+      goarch,
+      executablePath: executable
+    },
+    executable,
+    assetName: asset,
+    get checksums() {
+      return state.checksums
+    },
+    set checksums(next: string) {
+      state.checksums = next
+    },
+    get archive() {
+      return state.archive
+    },
+    set archive(next: Uint8Array) {
+      state.archive = next
+    },
+    close: () => {
+      server.stop(true)
+      void Bun.$`rm -rf ${dir}`.quiet()
+    }
+  }
+}
+
+const readFile = async (path: string): Promise => await Bun.file(path).text()
+
+const noOptions = { checkOnly: false, targetVersion: "" }
+
+// ---------------------------------------------------------------------------
+// The 16 Go cases
+// ---------------------------------------------------------------------------
+
+describe("TestUpdateDownloadsVerifiesAndReplaces", () => {
+  test("downloads, verifies, and replaces the executable", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "new-binary-content"
+    })
+    try {
+      const result = value(await run(runUpdate(f.config, noOptions)))
+      expect(result.updated).toBe(true)
+      expect(result.targetVersion).toBe("v0.2.0")
+      expect(await readFile(f.executable)).toBe("new-binary-content")
+
+      const mode = (await Bun.file(f.executable).stat()).mode & 0o777
+      expect(mode & 0o111).not.toBe(0)
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("TestUpdateRefusesChecksumMismatch", () => {
+  test("refuses a mismatched digest and leaves the executable untouched", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      f.checksums = `${"0".repeat(64)}  ${f.assetName}\n`
+      const exit = await run(runUpdate(f.config, noOptions))
+      expect(message(exit)).toContain("checksum mismatch")
+      expect(await readFile(f.executable)).toBe("old-binary")
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("TestUpdateRefusesMissingChecksums", () => {
+  test("refuses when the manifest has no entry for this asset", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      f.checksums = "deadbeef  something-else.tar.gz\n"
+      const exit = await run(runUpdate(f.config, noOptions))
+      expect(message(exit)).toContain("no entry")
+      expect(await readFile(f.executable)).toBe("old-binary")
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("TestUpdateAlreadyCurrent", () => {
+  test("reports up to date and downloads nothing", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.2.0",
+      binaryContent: "payload"
+    })
+    try {
+      const result = value(await run(runUpdate(f.config, noOptions)))
+      expect(result.upToDate).toBe(true)
+      expect(result.updated).toBe(false)
+      expect(await readFile(f.executable)).toBe("old-binary")
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("TestUpdateRefusesImplicitDowngrade", () => {
+  test("refuses when the latest release is older than the current version", async () => {
+    const f = await newFixture({
+      tag: "v0.1.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.2.0",
+      binaryContent: "payload"
+    })
+    try {
+      const exit = await run(runUpdate(f.config, noOptions))
+      expect(message(exit)).toContain("refusing to downgrade")
+      expect(await readFile(f.executable)).toBe("old-binary")
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("TestUpdateExplicitVersionAllowsPinnedInstall", () => {
+  test("an explicit --version installs an older release", async () => {
+    const f = await newFixture({
+      tag: "v0.1.5",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.2.0",
+      binaryContent: "pinned"
+    })
+    try {
+      const result = value(
+        await run(runUpdate(f.config, { checkOnly: false, targetVersion: "v0.1.5" }))
+      )
+      expect(result.updated).toBe(true)
+      expect(await readFile(f.executable)).toBe("pinned")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("a tag without a leading v is prefixed before the lookup", async () => {
+    const f = await newFixture({
+      tag: "v0.1.5",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.2.0",
+      binaryContent: "pinned"
+    })
+    try {
+      const result = value(
+        await run(runUpdate(f.config, { checkOnly: false, targetVersion: "0.1.5" }))
+      )
+      expect(result.updated).toBe(true)
+    } finally {
+      f.close()
+    }
+  })
+
+  test("an unknown tag surfaces the 404 guidance", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const exit = await run(runUpdate(f.config, { checkOnly: false, targetVersion: "v9.9.9" }))
+      expect(message(exit)).toContain("has a release been published?")
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("TestUpdateCheckOnlyDoesNotModify", () => {
+  test("--check reports the target without touching anything", async () => {
+    const f = await newFixture({
+      tag: "v0.3.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const result = value(
+        await run(runUpdate(f.config, { checkOnly: true, targetVersion: "" }))
+      )
+      expect(result.updated).toBe(false)
+      expect(result.upToDate).toBe(false)
+      expect(result.targetVersion).toBe("v0.3.0")
+      expect(result.assetName).toBe("oytc_v0.3.0_linux_amd64.tar.gz")
+      expect(await readFile(f.executable)).toBe("old-binary")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("--check still refuses a Homebrew-managed install", async () => {
+    const f = await newFixture({
+      tag: "v0.3.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const config = { ...f.config, executablePath: "/opt/homebrew/Cellar/oytc/0.1.0/bin/oytc" }
+      const exit = await run(runUpdate(config, { checkOnly: true, targetVersion: "" }))
+      expect(message(exit)).toContain("Homebrew")
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("TestUpdateWindowsZipAndRenameAside", () => {
+  /**
+   * Still goos=windows + amd64: dropping windows/arm64 does not change the
+   * rename-aside path, and this is the only coverage it gets on a POSIX CI.
+   */
+  test("extracts a zip and preserves the previous binary as .old", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "windows",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "windows-binary"
+    })
+    try {
+      const result = value(await run(runUpdate(f.config, noOptions)))
+      expect(result.updated).toBe(true)
+      expect(result.assetName).toBe("oytc_v0.2.0_windows_amd64.zip")
+      expect(await readFile(f.executable)).toBe("windows-binary")
+      expect(await readFile(`${f.executable}.old`)).toBe("old-binary")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("a pre-existing .old from a previous update is replaced, not appended to", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "windows",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "windows-binary"
+    })
+    try {
+      await Bun.write(`${f.executable}.old`, "ancient-binary")
+      value(await run(runUpdate(f.config, noOptions)))
+      expect(await readFile(`${f.executable}.old`)).toBe("old-binary")
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("TestUpdateRefusesHomebrewInstall", () => {
+  for (const path of [
+    "/opt/homebrew/Cellar/oytc/0.1.0/bin/oytc",
+    "/usr/local/Cellar/oytc/0.1.0/bin/oytc",
+    "/home/linuxbrew/.linuxbrew/bin/oytc",
+    "C:\\tools\\homebrew\\bin\\oytc.exe"
+  ]) {
+    test(`refuses ${path}`, async () => {
+      const f = await newFixture({
+        tag: "v0.2.0",
+        goos: "linux",
+        goarch: "amd64",
+        currentVersion: "v0.1.0",
+        binaryContent: "payload"
+      })
+      try {
+        const exit = await run(runUpdate({ ...f.config, executablePath: path }, noOptions))
+        expect(message(exit)).toContain("Homebrew")
+        expect(message(exit)).toContain("package manager")
+      } finally {
+        f.close()
+      }
+    })
+  }
+
+  test("an ordinary path is not mistaken for a managed install", () => {
+    expect(guardManagedInstall("/usr/local/bin/oytc")).toBeUndefined()
+    expect(guardManagedInstall("/home/me/.local/bin/oytc")).toBeUndefined()
+    // A literal "brew" in a user directory must not trip the guard: only the
+    // three anchored markers count.
+    expect(guardManagedInstall("/home/brewery/bin/oytc")).toBeUndefined()
+  })
+})
+
+describe("TestUpdateMissingAssetForPlatform", () => {
+  test("an unpublished arch fails with the missing-asset error", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const exit = await run(runUpdate({ ...f.config, goarch: "riscv64" }, noOptions))
+      expect(message(exit)).toContain("no asset")
+      expect(message(exit)).toContain("oytc_v0.2.0_linux_riscv64.tar.gz")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("windows/arm64 fails earlier, with the dropped-platform message", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const exit = await run(
+        runUpdate({ ...f.config, goos: "windows", goarch: "arm64" }, noOptions)
+      )
+      expect(message(exit)).toContain("windows/arm64")
+      expect(message(exit)).toContain("amd64 build instead")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("a release without checksums.txt refuses to install an unverifiable binary", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload",
+      omitChecksumsAsset: true
+    })
+    try {
+      const exit = await run(runUpdate(f.config, noOptions))
+      expect(message(exit)).toContain("refusing to install an unverifiable binary")
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("TestParseChecksums", () => {
+  const digest = "ab".repeat(32)
+  const manifest =
+    `${digest}  oytc_v1.0.0_linux_amd64.tar.gz\n` +
+    `${digest} *oytc_v1.0.0_darwin_arm64.tar.gz\n`
+
+  test("finds both entries, stripping the binary-mode marker", () => {
+    for (const name of ["oytc_v1.0.0_linux_amd64.tar.gz", "oytc_v1.0.0_darwin_arm64.tar.gz"]) {
+      expect(parseChecksums(manifest, name)).toEqual({ digest })
+    }
+  })
+
+  test("errors for a missing entry", () => {
+    const result = parseChecksums(manifest, "missing.tar.gz")
+    expect(result).toEqual({ error: 'checksums.txt has no entry for "missing.tar.gz"' })
+  })
+
+  test("errors for a malformed digest", () => {
+    const result = parseChecksums("nothex  oytc.tar.gz\n", "oytc.tar.gz")
+    expect(result).toEqual({
+      error: 'checksums.txt contains a malformed digest for "oytc.tar.gz"'
+    })
+  })
+
+  test("skips every line that does not have exactly two fields", () => {
+    const noisy =
+      "# a comment line with many fields\n" +
+      "\n" +
+      "   \n" +
+      "only-one-field\n" +
+      "three fields here\n" +
+      `${digest}  target.tar.gz\n`
+    expect(parseChecksums(noisy, "target.tar.gz")).toEqual({ digest })
+  })
+
+  test("splits on arbitrary whitespace, not just the sha256sum double space", () => {
+    expect(parseChecksums(`${digest}\ttarget.tar.gz`, "target.tar.gz")).toEqual({ digest })
+    expect(parseChecksums(`  ${digest}   target.tar.gz  `, "target.tar.gz")).toEqual({ digest })
+  })
+
+  test("an uppercase digest is lowercased", () => {
+    expect(parseChecksums(`${"AB".repeat(32)}  t.tar.gz`, "t.tar.gz")).toEqual({ digest })
+  })
+
+  test("rejects a digest of the wrong length even when it is valid hex", () => {
+    expect(parseChecksums(`${"ab".repeat(31)}  t.tar.gz`, "t.tar.gz")).toEqual({
+      error: 'checksums.txt contains a malformed digest for "t.tar.gz"'
+    })
+    expect(parseChecksums(`${"ab".repeat(33)}  t.tar.gz`, "t.tar.gz")).toEqual({
+      error: 'checksums.txt contains a malformed digest for "t.tar.gz"'
+    })
+  })
+
+  test("rejects 64 characters that are not hex", () => {
+    expect(parseChecksums(`${"z".repeat(64)}  t.tar.gz`, "t.tar.gz")).toEqual({
+      error: 'checksums.txt contains a malformed digest for "t.tar.gz"'
+    })
+  })
+
+  test("matches the first entry for a name and stops", () => {
+    const other = "cd".repeat(32)
+    expect(parseChecksums(`${digest}  t.tar.gz\n${other}  t.tar.gz\n`, "t.tar.gz")).toEqual({
+      digest
+    })
+  })
+
+  test("the name match is exact — a suffix does not count", () => {
+    const result = parseChecksums(`${digest}  prefix-t.tar.gz\n`, "t.tar.gz")
+    expect("error" in result).toBe(true)
+  })
+
+  test("an empty manifest reports no entry", () => {
+    expect("error" in parseChecksums("", "t.tar.gz")).toBe(true)
+  })
+
+  /**
+   * Line trimming uses Go's whitespace set, not JS `trim()`. Verified against
+   * `strings.Fields(strings.TrimSpace(line))` with `go run`:
+   *   - a leading U+FEFF stays attached to the digest, so the digest is
+   *     malformed (JS `trim()` would strip it and accept the line);
+   *   - a trailing U+FEFF stays attached to the filename, so it does not match;
+   *   - a leading U+0085 IS stripped by Go (JS `trim()` leaves it, which would
+   *     have made the digest malformed instead).
+   */
+  describe("trims with Go's whitespace set, not JS trim()", () => {
+    const bom = ""
+    const nel = "…"
+
+    test("a leading U+FEFF makes the digest malformed, as Go reports", () => {
+      expect(parseChecksums(`${bom}${digest}  t.tar.gz`, "t.tar.gz")).toEqual({
+        error: 'checksums.txt contains a malformed digest for "t.tar.gz"'
+      })
+    })
+
+    test("a trailing U+FEFF stays part of the filename, so the entry is not found", () => {
+      expect(parseChecksums(`${digest}  t.tar.gz${bom}`, "t.tar.gz")).toEqual({
+        error: 'checksums.txt has no entry for "t.tar.gz"'
+      })
+    })
+
+    test("a leading U+0085 is stripped, so the entry still resolves", () => {
+      expect(parseChecksums(`${nel}${digest}  t.tar.gz`, "t.tar.gz")).toEqual({ digest })
+    })
+  })
+})
+
+describe("TestDevBuildStillUpdatesToLatest", () => {
+  test("an uninjected dev build is incomparable, so it installs the latest", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "dev",
+      binaryContent: "release-binary"
+    })
+    try {
+      const result = value(await run(runUpdate(f.config, noOptions)))
+      expect(result.updated).toBe(true)
+      expect(await readFile(f.executable)).toBe("release-binary")
+    } finally {
+      f.close()
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Additional coverage the Go suite left implicit
+// ---------------------------------------------------------------------------
+
+describe("release metadata parsing", () => {
+  test("reads tag, prerelease and assets", () => {
+    expect(
+      parseRelease(
+        '{"tag_name":"v1.0.0","prerelease":true,"assets":[{"name":"a","browser_download_url":"u"}]}'
+      )
+    ).toEqual({
+      tagName: "v1.0.0",
+      prerelease: true,
+      assets: [{ name: "a", browserDownloadUrl: "u" }]
+    })
+  })
+
+  test("missing fields become zero values, as encoding/json does", () => {
+    expect(parseRelease("{}")).toEqual({ tagName: "", prerelease: false, assets: [] })
+  })
+
+  test("unknown fields are ignored", () => {
+    const release = parseRelease('{"tag_name":"v1","body":"notes","author":{"login":"x"}}')
+    expect(release?.tagName).toBe("v1")
+  })
+
+  test("invalid JSON is rejected", () => {
+    expect(parseRelease("not json")).toBeUndefined()
+    expect(parseRelease("[1,2,3]")).toBeUndefined()
+  })
+
+  test("an empty tag_name is surfaced as a missing tag by the caller", async () => {
+    const release = parseRelease('{"tag_name":""}')
+    expect(release?.tagName).toBe("")
+  })
+})
+
+describe("HTTP failure handling", () => {
+  test("a non-200, non-404 status reports the code", async () => {
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response("boom", { status: 500 })
+    })
+    servers.push(server)
+    const config: UpdaterConfig = {
+      repo: "owner/repo",
+      apiBaseUrl: `http://127.0.0.1:${server.port}`,
+      currentVersion: "v0.1.0",
+      goos: "linux",
+      goarch: "amd64",
+      executablePath: "/tmp/does-not-matter/oytc"
+    }
+    const exit = await run(runUpdate(config, noOptions))
+    expect(message(exit)).toContain("unexpected status 500")
+    expect(message(exit)).toContain("resolve release")
+    server.stop(true)
+  })
+
+  test("a malformed body is reported as a parse failure", async () => {
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response("nope")
+    })
+    servers.push(server)
+    const config: UpdaterConfig = {
+      repo: "owner/repo",
+      apiBaseUrl: `http://127.0.0.1:${server.port}`,
+      currentVersion: "v0.1.0",
+      goos: "linux",
+      goarch: "amd64",
+      executablePath: "/tmp/does-not-matter/oytc"
+    }
+    const exit = await run(runUpdate(config, noOptions))
+    expect(message(exit)).toContain("parse release metadata")
+    server.stop(true)
+  })
+
+  test("an empty tag_name fails with the missing-tag message", async () => {
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response('{"tag_name":"","assets":[]}')
+    })
+    servers.push(server)
+    const config: UpdaterConfig = {
+      repo: "owner/repo",
+      apiBaseUrl: `http://127.0.0.1:${server.port}`,
+      currentVersion: "v0.1.0",
+      goos: "linux",
+      goarch: "amd64",
+      executablePath: "/tmp/does-not-matter/oytc"
+    }
+    const exit = await run(runUpdate(config, noOptions))
+    expect(message(exit)).toContain("release metadata is missing a tag name")
+    server.stop(true)
+  })
+
+  test("the API base URL has trailing slashes stripped", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const config = { ...f.config, apiBaseUrl: `${f.config.apiBaseUrl}///` }
+      const result = value(await run(runUpdate(config, { checkOnly: true, targetVersion: "" })))
+      expect(result.targetVersion).toBe("v0.2.0")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("every request carries the oytc-updater User-Agent and never a credential", async () => {
+    const seen: Array = []
+    const archive = tarGzWithEntry("oytc", bytes("payload"))
+    const asset = assetName("v0.2.0", "linux", "amd64")
+    let base = ""
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch(request) {
+        seen.push(request.headers)
+        const path = new URL(request.url).pathname
+        if (path.endsWith("/releases/latest")) {
+          return new Response(
+            releaseJson("v0.2.0", [
+              { name: asset, browser_download_url: `${base}/assets/${asset}` },
+              { name: CHECKSUMS_NAME, browser_download_url: `${base}/assets/${CHECKSUMS_NAME}` }
+            ])
+          )
+        }
+        if (path.endsWith(asset)) return new Response(archive as BlobPart)
+        if (path.endsWith(CHECKSUMS_NAME)) {
+          return new Response(`${sha256Hex(archive)}  ${asset}\n`)
+        }
+        return new Response("not found", { status: 404 })
+      }
+    })
+    servers.push(server)
+    base = `http://127.0.0.1:${server.port}`
+
+    const dir = `/tmp/oytc-ua-test-${Math.floor(Math.random() * 1e9)}`
+    await Bun.$`mkdir -p ${dir}`.quiet()
+    await Bun.write(`${dir}/oytc`, "old-binary")
+
+    value(
+      await run(
+        runUpdate(
+          {
+            repo: "owner/repo",
+            apiBaseUrl: base,
+            currentVersion: "v0.1.0",
+            goos: "linux",
+            goarch: "amd64",
+            executablePath: `${dir}/oytc`
+          },
+          noOptions
+        )
+      )
+    )
+
+    expect(seen.length).toBe(3)
+    for (const headers of seen) {
+      expect(headers.get("user-agent")).toBe("oytc-updater/v0.1.0")
+      // The security posture: no API key ever leaves this process.
+      expect(headers.get("authorization")).toBeNull()
+      expect(headers.get("x-goog-api-key")).toBeNull()
+    }
+    // Only the metadata request negotiates the GitHub media type.
+    expect(seen[0]?.get("accept")).toBe("application/vnd.github+json")
+
+    server.stop(true)
+    await Bun.$`rm -rf ${dir}`.quiet()
+  })
+})
+
+describe("writability probe", () => {
+  test("a non-writable directory fails before anything is downloaded", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const exit = await run(
+        runUpdate({ ...f.config, executablePath: "/proc/definitely/not/here/oytc" }, noOptions)
+      )
+      expect(Exit.isSuccess(exit)).toBe(false)
+    } finally {
+      f.close()
+    }
+  })
+
+  test("the probe leaves nothing behind on success", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      value(await run(runUpdate(f.config, noOptions)))
+      const dir = f.executable.slice(0, f.executable.lastIndexOf("/"))
+      const listing = (await Bun.$`ls -A ${dir}`.quiet()).stdout.toString().trim().split("\n")
+      expect(listing.filter((n) => n.startsWith(".oytc-"))).toEqual([])
+      expect(listing).toEqual(["oytc"])
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("archive integrity", () => {
+  test("a tampered archive fails the digest and leaves the executable alone", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      // The manifest still lists the ORIGINAL digest; the served bytes change.
+      f.archive = tarGzWithEntry("oytc", bytes("attacker-controlled"))
+      const exit = await run(runUpdate(f.config, noOptions))
+      expect(message(exit)).toContain("checksum mismatch")
+      expect(message(exit)).toContain("refusing to install")
+      expect(await readFile(f.executable)).toBe("old-binary")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("a valid digest over an archive missing the binary reports the archive, not the digest", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const decoy = tarGzWithEntry("README", bytes("nothing here"))
+      f.archive = decoy
+      f.checksums = `${sha256Hex(decoy)}  ${f.assetName}\n`
+      const exit = await run(runUpdate(f.config, noOptions))
+      expect(message(exit)).toContain('release archive does not contain "oytc"')
+      expect(await readFile(f.executable)).toBe("old-binary")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("a path-traversal entry is refused even with a valid digest", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const evil = tarGzWithEntry("../oytc", bytes("evil"))
+      f.archive = evil
+      f.checksums = `${sha256Hex(evil)}  ${f.assetName}\n`
+      const exit = await run(runUpdate(f.config, noOptions))
+      expect(message(exit)).toContain("does not contain")
+      expect(await readFile(f.executable)).toBe("old-binary")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("no temporary archive survives a successful run", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      value(await run(runUpdate(f.config, noOptions)))
+      const stale = (await Bun.$`ls -A /tmp`.quiet()).stdout
+        .toString()
+        .split("\n")
+        .filter((name) => name.startsWith("oytc-update-"))
+      expect(stale).toEqual([])
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("toUpdateResult", () => {
+  test("renames targetVersion to latestVersion for the service contract", () => {
+    const result: UpdateRunResult = {
+      currentVersion: "v0.1.0",
+      targetVersion: "v0.2.0",
+      updated: true,
+      upToDate: false,
+      assetName: "oytc_v0.2.0_linux_amd64.tar.gz",
+      executablePath: "/usr/local/bin/oytc"
+    }
+    expect(toUpdateResult(result)).toEqual({
+      currentVersion: "v0.1.0",
+      latestVersion: "v0.2.0",
+      updated: true,
+      asset: "oytc_v0.2.0_linux_amd64.tar.gz",
+      executable: "/usr/local/bin/oytc"
+    })
+  })
+})
+
+describe("executable resolution", () => {
+  test("a symlinked executable resolves to its target before the guard runs", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "resolved"
+    })
+    try {
+      const link = `${f.executable}-link`
+      await Bun.$`ln -s ${f.executable} ${link}`.quiet()
+      const result = value(await run(runUpdate({ ...f.config, executablePath: link }, noOptions)))
+      // The REAL file is replaced, not the link — otherwise the update would
+      // silently clobber the symlink and orphan the binary. Compared against a
+      // realpath of the fixture because /tmp is itself a symlink on macOS.
+      const real = (await Bun.$`readlink -f ${f.executable}`.quiet()).stdout.toString().trim()
+      expect(result.executablePath).toBe(real)
+      expect(result.executablePath).not.toBe(link)
+      expect(await readFile(f.executable)).toBe("resolved")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("a symlink pointing into a Cellar path is caught after resolution", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const dir = f.executable.slice(0, f.executable.lastIndexOf("/"))
+      await Bun.$`mkdir -p ${dir}/Cellar/oytc/bin`.quiet()
+      const real = `${dir}/Cellar/oytc/bin/oytc`
+      await Bun.write(real, "brewed")
+      const link = `${dir}/brew-link`
+      await Bun.$`ln -s ${real} ${link}`.quiet()
+
+      const exit = await run(runUpdate({ ...f.config, executablePath: link }, noOptions))
+      // The guard would miss this if it ran on the unresolved link path.
+      expect(message(exit)).toContain("Homebrew")
+    } finally {
+      f.close()
+    }
+  })
+
+  test("an unresolvable path is used as-is rather than failing", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const missing = `${f.executable}-not-created-yet`
+      const result = value(
+        await run(runUpdate({ ...f.config, executablePath: missing }, { checkOnly: true, targetVersion: "" }))
+      )
+      expect(result.executablePath).toBe(missing)
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("windows rename-aside", () => {
+  test("a failed aside-rename tells the user how to finish by hand", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "windows",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "windows-binary"
+    })
+    try {
+      // A non-empty directory at `.old` survives the pre-emptive remove
+      // (which is non-recursive) and makes `rename(exe, exe.old)` fail.
+      await Bun.$`mkdir -p ${f.executable}.old/occupied`.quiet()
+      await Bun.write(`${f.executable}.old/occupied/x`, "blocker")
+
+      const exit = await run(runUpdate(f.config, noOptions))
+      expect(message(exit)).toContain("move the running executable aside")
+      expect(message(exit)).toContain("github.com/davis7dotsh/open-yt-cli/releases")
+      // The running executable is untouched, which is the whole point.
+      expect(await readFile(f.executable)).toBe("old-binary")
+      const dir = f.executable.slice(0, f.executable.lastIndexOf("/"))
+      const listing = (await Bun.$`ls -A ${dir}`.quiet()).stdout.toString().trim().split("\n")
+      expect(listing.filter((n) => n.startsWith(".oytc-new-"))).toEqual([])
+    } finally {
+      f.close()
+    }
+  })
+
+  /**
+   * The rollback branch cannot be reached with real filesystem calls (once the
+   * aside-rename succeeds, the destination is free and the second rename
+   * cannot fail on a sane filesystem), so the FileSystem is wrapped to fail
+   * exactly that one call. Without the rollback the user would be left with no
+   * executable at all — only a `.old` file.
+   */
+  test("rolls the aside-rename back when the staged rename fails", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "windows",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "windows-binary"
+    })
+    try {
+      // The updater resolves symlinks, and /tmp is one on macOS, so the path
+      // it renames to is the realpath, not the fixture path.
+      const target = (await Bun.$`readlink -f ${f.executable}`.quiet()).stdout.toString().trim()
+      const brokenRename = Layer.effect(
+        FileSystem.FileSystem,
+        Effect.gen(function* () {
+          const fs = yield* FileSystem.FileSystem
+          return {
+            ...fs,
+            rename: (from: string, to: string) =>
+              to === target && from !== `${target}.old`
+                ? Effect.fail(
+                    PlatformError.systemError({
+                      _tag: "PermissionDenied",
+                      module: "FileSystem",
+                      method: "rename",
+                      pathOrDescriptor: to
+                    })
+                  )
+                : fs.rename(from, to)
+          }
+        })
+      ).pipe(Layer.provide(BunServices.layer))
+
+      const exit = await Effect.runPromiseExit(
+        runUpdate(f.config, noOptions).pipe(
+          Effect.provide(brokenRename),
+          Effect.provide(testLayer)
+        ) as Effect.Effect
+      )
+
+      expect(message(exit)).toContain("no permission to replace")
+      // Rolled back: the original binary is back at its own path...
+      expect(await readFile(f.executable)).toBe("old-binary")
+      // ...and the aside copy is gone rather than holding the only copy.
+      expect(await Bun.file(`${f.executable}.old`).exists()).toBe(false)
+    } finally {
+      f.close()
+    }
+  })
+
+  test("posix does NOT leave a .old file behind", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      value(await run(runUpdate(f.config, noOptions)))
+      expect(await Bun.file(`${f.executable}.old`).exists()).toBe(false)
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("streaming download", () => {
+  test("a large archive is hashed and written correctly across many chunks", async () => {
+    // Big enough to arrive in multiple stream chunks, which is the only way to
+    // catch a hasher that is fed the whole body instead of each slice.
+    const payload = new Uint8Array(3 * 1024 * 1024)
+    for (let i = 0; i < payload.length; i++) payload[i] = (i * 31) % 256
+
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "placeholder"
+    })
+    try {
+      const archive = tarGzWithEntry("oytc", payload)
+      f.archive = archive
+      f.checksums = `${sha256Hex(archive)}  ${f.assetName}\n`
+
+      value(await run(runUpdate(f.config, noOptions)))
+      const installed = new Uint8Array(await Bun.file(f.executable).arrayBuffer())
+      expect(installed.length).toBe(payload.length)
+      expect(sha256Hex(installed)).toBe(sha256Hex(payload))
+    } finally {
+      f.close()
+    }
+  })
+})
+
+describe("installPermissionError guidance", () => {
+  test("a genuinely unwritable directory gets the privileges/install-script advice", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      const locked = `/tmp/oytc-locked-${Math.floor(Math.random() * 1e9)}`
+      await Bun.$`mkdir -p ${locked}`.quiet()
+      await Bun.write(`${locked}/oytc`, "old-binary")
+      await Bun.$`chmod 500 ${locked}`.quiet()
+      try {
+        const exit = await run(
+          runUpdate({ ...f.config, executablePath: `${locked}/oytc` }, noOptions)
+        )
+        expect(message(exit)).toContain("no permission to replace")
+        expect(message(exit)).toContain("Re-run the update with sufficient privileges")
+        expect(message(exit)).toContain("https://davis7dotsh.github.io/open-yt-cli/install.sh")
+      } finally {
+        await Bun.$`chmod 700 ${locked}`.quiet()
+        await Bun.$`rm -rf ${locked}`.quiet()
+      }
+    } finally {
+      f.close()
+    }
+  })
+
+  test("a non-permission failure is NOT dressed up with the privileges advice", async () => {
+    const f = await newFixture({
+      tag: "v0.2.0",
+      goos: "linux",
+      goarch: "amd64",
+      currentVersion: "v0.1.0",
+      binaryContent: "payload"
+    })
+    try {
+      // A missing parent directory is ENOENT, not EACCES. Go returns the raw
+      // error here; telling the user to re-run as root would be wrong.
+      const exit = await run(
+        runUpdate({ ...f.config, executablePath: "/tmp/no-such-dir-xyz/oytc" }, noOptions)
+      )
+      expect(Exit.isSuccess(exit)).toBe(false)
+      expect(message(exit)).not.toContain("sufficient privileges")
+    } finally {
+      f.close()
+    }
+  })
+})
diff --git a/src/impl/updater.ts b/src/impl/updater.ts
index ca14f9a..c2b42bd 100644
--- a/src/impl/updater.ts
+++ b/src/impl/updater.ts
@@ -1,2 +1,744 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Secure self-update from GitHub Releases — the port of
+ * `internal/update/update.go`.
+ *
+ * The security posture is the point and is preserved verbatim: the updater
+ * **never reads, needs, or transmits the YouTube API key**. The only network
+ * traffic is unauthenticated GitHub release metadata and asset downloads.
+ *
+ * The chain of custody is: resolve a release -> compute the platform asset
+ * name -> fetch `checksums.txt` -> stream the archive to disk while hashing it
+ * -> compare SHA-256 -> extract with an exact-name traversal defense ->
+ * atomically rename into place. Nothing is written next to the executable
+ * until the digest matches.
+ */
+
+import { createHash } from "node:crypto"
+import { Effect, FileSystem, Layer, Path, Stream } from "effect"
+import { HttpClient, HttpClientRequest } from "../effect.ts"
+import { NotFoundError, OperationalError, type OytcError } from "../domain/errors.ts"
+import {
+  ProcessEnv,
+  Updater,
+  VersionInfo,
+  type UpdateOptions,
+  type UpdateResult,
+  type UpdaterShape
+} from "../services/index.ts"
+import { extractBinary, MAX_ARCHIVE_BYTES } from "./archive.ts"
+import { assertBuildablePlatform, assetName, binaryName, hostPlatform } from "./platformMatrix.ts"
+import { compareVersions, goTrimSpace, isGoSpace } from "./semver.ts"
+
+/** The canonical GitHub repository for oytc releases. */
+export const DEFAULT_REPO = "davis7dotsh/open-yt-cli"
+
+/** The GitHub REST API endpoint. */
+export const DEFAULT_API_BASE_URL = "https://api.github.com"
+
+/** The release checksum manifest filename. */
+export const CHECKSUMS_NAME = "checksums.txt"
+
+/** `4 << 20` — release JSON. */
+const MAX_METADATA_BYTES = 4 << 20
+/** `1 << 20` — checksums.txt. */
+const MAX_CHECKSUM_BYTES = 1 << 20
+
+const INSTALL_SCRIPT_URL = "https://davis7dotsh.github.io/open-yt-cli/install.sh"
+const RELEASES_URL = `https://github.com/${DEFAULT_REPO}/releases`
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+const operational = (message: string, cause?: unknown): OperationalError =>
+  new OperationalError({ message, ...(cause === undefined ? {} : { cause }) })
+
+const failWith = (message: string, cause?: unknown) => Effect.fail(operational(message, cause))
+
+/** Go renders a wrapped error as `outer: inner`; there is no stack, ever. */
+const describe = (cause: unknown): string => {
+  if (cause instanceof Error) return cause.message
+  if (typeof cause === "string") return cause
+  return String(cause)
+}
+
+const PERMISSION_TAGS = new Set(["PermissionDenied"])
+const PERMISSION_CODES = new Set(["EACCES", "EPERM"])
+
+/**
+ * `errors.Is(err, os.ErrPermission)`. Effect surfaces a `PlatformError` whose
+ * `reason._tag` is `"PermissionDenied"`; the raw errno is checked too because
+ * a `BadArgument` reason keeps the original `cause`.
+ */
+const isPermissionDenied = (cause: unknown): boolean => {
+  const seen = new Set()
+  let current: unknown = cause
+  while (current !== null && typeof current === "object" && !seen.has(current)) {
+    seen.add(current)
+    const record = current as Record
+    const tag = record["_tag"]
+    if (typeof tag === "string" && PERMISSION_TAGS.has(tag)) return true
+    const code = record["code"]
+    if (typeof code === "string" && PERMISSION_CODES.has(code)) return true
+    current = record["reason"] ?? record["cause"]
+  }
+  return false
+}
+
+/**
+ * `installPermissionError`. The guidance block is appended **only** when the
+ * underlying failure really was a permission error; anything else is returned
+ * unchanged, so a full disk does not tell the user to run as root.
+ */
+const installPermissionError = (executable: string, cause: unknown): OperationalError =>
+  isPermissionDenied(cause)
+    ? operational(
+        `no permission to replace ${executable}: ${describe(cause)}\n` +
+          "Re-run the update with sufficient privileges, or reinstall to a user-writable " +
+          `location with the install script (${INSTALL_SCRIPT_URL})`,
+        cause
+      )
+    : operational(describe(cause), cause)
+
+// ---------------------------------------------------------------------------
+// Release metadata
+// ---------------------------------------------------------------------------
+
+export interface ReleaseAsset {
+  readonly name: string
+  readonly browserDownloadUrl: string
+}
+
+export interface Release {
+  readonly tagName: string
+  readonly prerelease: boolean
+  readonly assets: ReadonlyArray
+}
+
+/**
+ * Parse the subset of the GitHub release payload the updater needs.
+ *
+ * Hand-rolled rather than schema-decoded because Go's `encoding/json` is
+ * lenient here: a wrong-typed or missing field becomes its zero value rather
+ * than an error, and only an empty `tag_name` is fatal. A strict schema would
+ * reject payloads the Go updater accepted.
+ */
+export const parseRelease = (body: string): Release | undefined => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(body) as unknown
+  } catch {
+    return undefined
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    // Go unmarshals a JSON array or scalar into a struct as an error.
+    return undefined
+  }
+  const record = raw as Record
+  const tagName = typeof record["tag_name"] === "string" ? record["tag_name"] : ""
+  const prerelease = record["prerelease"] === true
+  const rawAssets = Array.isArray(record["assets"]) ? (record["assets"] as ReadonlyArray) : []
+  const assets: Array = []
+  for (const entry of rawAssets) {
+    if (entry === null || typeof entry !== "object") continue
+    const asset = entry as Record
+    assets.push({
+      name: typeof asset["name"] === "string" ? asset["name"] : "",
+      browserDownloadUrl:
+        typeof asset["browser_download_url"] === "string" ? asset["browser_download_url"] : ""
+    })
+  }
+  return { tagName, prerelease, assets }
+}
+
+// ---------------------------------------------------------------------------
+// Checksums
+// ---------------------------------------------------------------------------
+
+/**
+ * Go's `strings.Fields` — split on runs of Unicode whitespace, dropping
+ * empties. Implemented against Go's `unicode.IsSpace` set rather than the JS
+ * `\s` class, because the two disagree: `\s` matches U+FEFF, Go does not.
+ */
+const goFields = (line: string): ReadonlyArray => {
+  const fields: Array = []
+  let current = ""
+  for (const char of line) {
+    if (isGoSpace(char.codePointAt(0) ?? 0)) {
+      if (current !== "") fields.push(current)
+      current = ""
+    } else {
+      current += char
+    }
+  }
+  if (current !== "") fields.push(current)
+  return fields
+}
+
+const HEX64 = /^[0-9a-f]{64}$/
+
+/**
+ * `ParseChecksums` — extract the SHA-256 digest for `name` from a
+ * sha256sum-format manifest.
+ *
+ * Only lines with **exactly two** whitespace-separated fields are considered;
+ * anything else is silently skipped, which is what lets a manifest carry
+ * comments or a GPG armor block without breaking. `*` is sha256sum's
+ * binary-mode marker and is stripped from the filename before matching.
+ *
+ * Returns an error message string on failure so the caller owns the error type.
+ */
+export const parseChecksums = (
+  manifest: string,
+  name: string
+): { readonly digest: string } | { readonly error: string } => {
+  for (const rawLine of manifest.split("\n")) {
+    // `goTrimSpace`, not JS `trim()`: the two disagree on U+FEFF (JS strips it,
+    // Go does not) and U+0085 (Go strips it, JS does not). Using `trim()` here
+    // made a manifest line carrying a BOM parse where Go rejected it, which is
+    // a divergence in the digest trust root.
+    const fields = goFields(goTrimSpace(rawLine))
+    if (fields.length !== 2) continue
+    const filename = fields[1]!.startsWith("*") ? fields[1]!.slice(1) : fields[1]!
+    if (filename !== name) continue
+    const digest = fields[0]!.toLowerCase()
+    if (!HEX64.test(digest)) {
+      return { error: `${CHECKSUMS_NAME} contains a malformed digest for "${name}"` }
+    }
+    return { digest }
+  }
+  return { error: `${CHECKSUMS_NAME} has no entry for "${name}"` }
+}
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface UpdaterConfig {
+  readonly repo: string
+  readonly apiBaseUrl: string
+  readonly currentVersion: string
+  readonly goos: string
+  readonly goarch: string
+  /** Overrides `process.execPath` resolution; the seam the Go tests used. */
+  readonly executablePath: string | undefined
+}
+
+/**
+ * The full Go `Result`.
+ *
+ * `UpdaterShape["run"]` in the frozen service contract cannot carry
+ * `targetVersion`/`upToDate` (it has `latestVersion` and no up-to-date flag),
+ * so this richer record is exported for the CLI layer, which needs `upToDate`
+ * to choose between the three table renderings in SPEC_AUTH_RELEASE §3.10.
+ */
+export interface UpdateRunResult {
+  readonly currentVersion: string
+  readonly targetVersion: string
+  readonly updated: boolean
+  readonly upToDate: boolean
+  readonly assetName: string
+  readonly executablePath: string
+}
+
+export type UpdaterServices = HttpClient.HttpClient | FileSystem.FileSystem | Path.Path
+
+// ---------------------------------------------------------------------------
+// HTTP
+// ---------------------------------------------------------------------------
+
+const userAgent = (currentVersion: string): string => `oytc-updater/${currentVersion}`
+
+/** Sentinel used to stop reading a body once it has passed its size cap. */
+const OVERSIZED = Symbol.for("oytc/updater/oversized")
+
+/**
+ * `get()` — a size-capped GET with the updater's UA. 404 is distinguished
+ * because Go's exit-code classifier keys off the literal "not found" in the
+ * message, which maps a missing release to exit 4 rather than 6.
+ */
+const get = (
+  config: UpdaterConfig,
+  url: string,
+  limit: number,
+  accept: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const request = HttpClientRequest.get(url).pipe(
+      HttpClientRequest.setHeader("User-Agent", userAgent(config.currentVersion)),
+      accept === "" ? (r) => r : HttpClientRequest.setHeader("Accept", accept)
+    )
+    const response = yield* client
+      .execute(request)
+      .pipe(Effect.catch((cause) => failWith(describe(cause), cause)))
+
+    if (response.status === 404) {
+      return yield* Effect.fail(
+        new NotFoundError({ message: `GET ${url}: not found (has a release been published?)` })
+      )
+    }
+    if (response.status !== 200) {
+      return yield* failWith(`GET ${url}: unexpected status ${response.status}`)
+    }
+
+    // Go reads at most limit+1 bytes (`io.LimitReader`) and rejects a body that
+    // filled the extra byte. Read the stream rather than `response.text` so at
+    // most limit+1 bytes are ever RETAINED: `response.text` buffers the whole
+    // body first and only then compares, so a 300 MB response was held in
+    // memory to be rejected for exceeding 4 MB. Measured: this retains ~4 MB of
+    // a 300 MB body.
+    //
+    // Note this bounds memory, not time — the underlying fetch body still
+    // drains, so a genuinely endless response hangs here exactly as it did
+    // before. A wall-clock timeout (Go used `http.Client{Timeout: 5*time.Minute}`)
+    // is the missing piece and belongs with the HttpClient layer, not here.
+    const chunks: Array = []
+    let size = 0
+    yield* Stream.runForEach(response.stream, (chunk) =>
+      Effect.gen(function* () {
+        if (size > limit) return
+        chunks.push(chunk)
+        size += chunk.length
+        // One byte past the limit is enough to decide; stop pulling the body.
+        if (size > limit) return yield* Effect.fail(OVERSIZED)
+      })
+    ).pipe(
+      Effect.catch((cause) =>
+        cause === OVERSIZED
+          ? Effect.void
+          : failWith(describe(cause), cause)
+      )
+    )
+    if (size > limit) {
+      return yield* failWith(`GET ${url}: response exceeds ${limit} bytes`)
+    }
+
+    const body = new Uint8Array(size)
+    let at = 0
+    for (const chunk of chunks) {
+      body.set(chunk, at)
+      at += chunk.length
+    }
+    return new TextDecoder().decode(body)
+  })
+
+const apiBaseUrl = (config: UpdaterConfig): string =>
+  (config.apiBaseUrl === "" ? DEFAULT_API_BASE_URL : config.apiBaseUrl).replace(/\/+$/, "")
+
+const repoOf = (config: UpdaterConfig): string => (config.repo === "" ? DEFAULT_REPO : config.repo)
+
+const resolveRelease = (
+  config: UpdaterConfig,
+  tag: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const base = apiBaseUrl(config)
+    const endpoint =
+      tag === ""
+        ? `${base}/repos/${repoOf(config)}/releases/latest`
+        : `${base}/repos/${repoOf(config)}/releases/tags/${tag.startsWith("v") ? tag : `v${tag}`}`
+
+    const body = yield* get(config, endpoint, MAX_METADATA_BYTES, "application/vnd.github+json").pipe(
+      // Go wraps with "resolve release: %w"; NotFoundError keeps its exit code
+      // and its message still contains "not found", which is what matters.
+      Effect.catchTag("OperationalError", (e) =>
+        Effect.fail(operational(`resolve release: ${e.message}`, e.cause))
+      ),
+      Effect.catchTag("NotFoundError", (e) =>
+        Effect.fail(new NotFoundError({ message: `resolve release: ${e.message}` }))
+      )
+    )
+
+    const release = parseRelease(body)
+    if (release === undefined) {
+      return yield* failWith("parse release metadata: invalid JSON in release response")
+    }
+    if (release.tagName === "") {
+      return yield* failWith("release metadata is missing a tag name")
+    }
+    return release
+  })
+
+/** Exact-name asset lookup; neither the archive nor the manifest is fuzzy-matched. */
+const findAssets = (
+  release: Release,
+  asset: string
+): Effect.Effect<{ readonly assetUrl: string; readonly checksumsUrl: string }, OytcError> =>
+  Effect.gen(function* () {
+    let assetUrl = ""
+    let checksumsUrl = ""
+    for (const entry of release.assets) {
+      if (entry.name === asset) assetUrl = entry.browserDownloadUrl
+      else if (entry.name === CHECKSUMS_NAME) checksumsUrl = entry.browserDownloadUrl
+    }
+    if (assetUrl === "") {
+      return yield* failWith(`release ${release.tagName} has no asset "${asset}" for this platform`)
+    }
+    if (checksumsUrl === "") {
+      return yield* failWith(
+        `release ${release.tagName} has no ${CHECKSUMS_NAME} asset; refusing to install an unverifiable binary`
+      )
+    }
+    return { assetUrl, checksumsUrl }
+  })
+
+const fetchChecksum = (
+  config: UpdaterConfig,
+  url: string,
+  asset: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const body = yield* get(config, url, MAX_CHECKSUM_BYTES, "").pipe(
+      Effect.catchTag("OperationalError", (e) =>
+        Effect.fail(operational(`download ${CHECKSUMS_NAME}: ${e.message}`, e.cause))
+      ),
+      Effect.catchTag("NotFoundError", (e) =>
+        Effect.fail(new NotFoundError({ message: `download ${CHECKSUMS_NAME}: ${e.message}` }))
+      )
+    )
+    const parsed = parseChecksums(body, asset)
+    if ("error" in parsed) return yield* failWith(parsed.error)
+    return parsed.digest
+  })
+
+/**
+ * Stream the archive to `destination`, computing SHA-256 as bytes arrive so
+ * the payload is never buffered whole and never hashed in a second pass.
+ *
+ * The 256 MiB cap **truncates** rather than erroring, matching Go's
+ * `io.LimitReader`: an oversized asset then fails the digest comparison, which
+ * is the same refusal by a different route.
+ */
+const downloadVerified = (
+  config: UpdaterConfig,
+  url: string,
+  expected: string,
+  destination: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const client = yield* HttpClient.HttpClient
+
+    const request = HttpClientRequest.get(url).pipe(
+      HttpClientRequest.setHeader("User-Agent", userAgent(config.currentVersion))
+    )
+    const response = yield* client
+      .execute(request)
+      .pipe(Effect.catch((cause) => failWith(`download release archive: ${describe(cause)}`, cause)))
+    if (response.status !== 200) {
+      return yield* failWith(`download release archive: unexpected status ${response.status}`)
+    }
+
+    const hasher = createHash("sha256")
+    let written = 0
+
+    yield* Effect.scoped(
+      Effect.gen(function* () {
+        const handle = yield* fs
+          .open(destination, { flag: "w", mode: 0o600 })
+          .pipe(
+            Effect.catch((cause) =>
+              failWith(`save release archive: ${describe(cause)}`, cause)
+            )
+          )
+        yield* Stream.runForEach(response.stream, (chunk) =>
+          Effect.gen(function* () {
+            if (written >= MAX_ARCHIVE_BYTES) return
+            const room = MAX_ARCHIVE_BYTES - written
+            const slice = chunk.length > room ? chunk.subarray(0, room) : chunk
+            hasher.update(slice)
+            written += slice.length
+            yield* handle.writeAll(slice)
+          })
+        ).pipe(
+          Effect.catch((cause) => failWith(`save release archive: ${describe(cause)}`, cause))
+        )
+      })
+    )
+
+    const actual = hasher.digest("hex")
+    if (actual !== expected) {
+      yield* fs.remove(destination, { force: true }).pipe(Effect.ignore)
+      return yield* failWith(
+        `checksum mismatch for downloaded archive: expected ${expected}, got ${actual}; refusing to install`
+      )
+    }
+  })
+
+// ---------------------------------------------------------------------------
+// Installation
+// ---------------------------------------------------------------------------
+
+/** Go's `os.CreateTemp(dir, "*")`: a random decimal infix. */
+const tempName = (prefix: string): string => `${prefix}${Math.floor(Math.random() * 0xffffffff)}`
+
+/**
+ * `checkWritable` — create and delete a probe file in the executable's
+ * directory. Failing here means the replacement would fail after a download,
+ * so it runs before a single archive byte is fetched.
+ */
+const checkWritable = (
+  executable: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+    const probe = path.join(path.dirname(executable), tempName(".oytc-write-probe-"))
+    yield* fs
+      .writeFileString(probe, "", { flag: "wx", mode: 0o600 })
+      .pipe(Effect.catch((cause) => Effect.fail(installPermissionError(executable, cause))))
+    yield* fs.remove(probe, { force: true }).pipe(Effect.ignore)
+  })
+
+/**
+ * `replaceExecutable` — stage next to the target so the final rename is
+ * same-filesystem and therefore atomic.
+ *
+ * On Windows a running executable cannot be overwritten but *can* be renamed,
+ * so the current binary moves aside to `.old` first. That file is
+ * deliberately **left behind** on success: it is still mapped by the running
+ * process. The PowerShell installer removes it on the next install.
+ */
+const replaceExecutable = (
+  contents: Uint8Array,
+  executable: string,
+  goos: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+    const staged = path.join(path.dirname(executable), tempName(".oytc-new-"))
+
+    yield* fs
+      .writeFile(staged, contents, { flag: "wx", mode: 0o755 })
+      .pipe(Effect.catch((cause) => Effect.fail(installPermissionError(executable, cause))))
+
+    const install = Effect.gen(function* () {
+      yield* fs
+        .chmod(staged, 0o755)
+        .pipe(
+          Effect.catch((cause) => failWith(`stage new binary: ${describe(cause)}`, cause))
+        )
+
+      if (goos === "windows") {
+        const old = `${executable}.old`
+        yield* fs.remove(old, { force: true }).pipe(Effect.ignore)
+        yield* fs
+          .rename(executable, old)
+          .pipe(
+            Effect.catch((cause) =>
+              failWith(
+                `move the running executable aside (${describe(cause)}); on Windows, download the ` +
+                  `new release manually from ${RELEASES_URL} and replace ${executable}`,
+                cause
+              )
+            )
+          )
+        yield* fs.rename(staged, executable).pipe(
+          Effect.catch((cause) =>
+            // Roll back: the user must not be left with no executable at all.
+            fs
+              .rename(old, executable)
+              .pipe(
+                Effect.ignore,
+                Effect.andThen(Effect.fail(installPermissionError(executable, cause)))
+              )
+          )
+        )
+        return
+      }
+
+      yield* fs
+        .rename(staged, executable)
+        .pipe(Effect.catch((cause) => Effect.fail(installPermissionError(executable, cause))))
+    })
+
+    // Go's `defer os.Remove(stagedName)` on every failure path; a no-op once
+    // the rename succeeded.
+    yield* install.pipe(
+      Effect.onError(() => fs.remove(staged, { force: true }).pipe(Effect.ignore))
+    )
+  })
+
+/**
+ * `guardManagedInstall` — refuse to fight a package manager for ownership of
+ * its own binary. Path separators are normalized first so the markers match on
+ * Windows too.
+ */
+export const guardManagedInstall = (executable: string): string | undefined => {
+  const normalized = executable.replaceAll("\\", "/")
+  for (const marker of ["/Cellar/", "/homebrew/", "/linuxbrew/"]) {
+    if (normalized.includes(marker)) {
+      return `${executable} looks like a Homebrew-managed install; update it with your package manager instead of the self-updater`
+    }
+  }
+  return undefined
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+/**
+ * The 12-step run sequence from SPEC_AUTH_RELEASE §3.3, in order.
+ */
+export const runUpdate = (
+  config: UpdaterConfig,
+  options: UpdateOptions
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+
+    // 1. Resolve the executable. Symlink resolution failure is not fatal.
+    const raw = config.executablePath ?? process.execPath
+    const executable = yield* fs.realPath(raw).pipe(Effect.catch(() => Effect.succeed(raw)))
+
+    const base: UpdateRunResult = {
+      currentVersion: config.currentVersion,
+      targetVersion: "",
+      updated: false,
+      upToDate: false,
+      assetName: "",
+      executablePath: executable
+    }
+
+    // 2. Guard managed installs.
+    const managed = guardManagedInstall(executable)
+    if (managed !== undefined) return yield* failWith(managed)
+
+    // Fail before any network traffic when this platform is not published for.
+    yield* Effect.try({
+      try: () => assertBuildablePlatform(config.goos, config.goarch),
+      catch: (cause) => operational(describe(cause), cause)
+    })
+
+    // 3. Resolve the release.
+    const release = yield* resolveRelease(config, options.targetVersion)
+
+    // 4. Compute the asset name.
+    const asset = yield* Effect.try({
+      try: () => assetName(release.tagName, config.goos, config.goarch),
+      catch: (cause) => operational(describe(cause), cause)
+    })
+    const resolved: UpdateRunResult = {
+      ...base,
+      targetVersion: release.tagName,
+      assetName: asset
+    }
+
+    // 5. Compare versions.
+    const comparison = compareVersions(release.tagName, config.currentVersion)
+    if (comparison.comparable && comparison.order === 0) {
+      return { ...resolved, upToDate: true }
+    }
+    if (comparison.comparable && comparison.order < 0 && options.targetVersion === "") {
+      return yield* failWith(
+        `latest release ${release.tagName} is older than the current version ${config.currentVersion}; ` +
+          "refusing to downgrade (pass an explicit version to override)"
+      )
+    }
+
+    // 6. Check-only stops here, having touched nothing.
+    if (options.checkOnly) return resolved
+
+    // 7. Writability probe.
+    yield* checkWritable(executable)
+
+    // 8. Find the assets.
+    const { assetUrl, checksumsUrl } = yield* findAssets(release, asset)
+
+    // 9. Fetch the expected digest.
+    const expected = yield* fetchChecksum(config, checksumsUrl, asset)
+
+    // 10-11. Download, verify, extract — all inside a temp directory that is
+    // removed however this ends.
+    const scratch = yield* fs
+      .makeTempDirectory({ prefix: "oytc-update-" })
+      .pipe(Effect.catch((cause) => failWith(`save release archive: ${describe(cause)}`, cause)))
+
+    const staged = yield* Effect.gen(function* () {
+      const archivePath = path.join(scratch, asset)
+      yield* downloadVerified(config, assetUrl, expected, archivePath)
+      return yield* extractBinary(archivePath, config.goos, binaryName(config.goos))
+    }).pipe(
+      Effect.onExit(() => fs.remove(scratch, { recursive: true, force: true }).pipe(Effect.ignore))
+    )
+
+    // 12. Replace the executable.
+    yield* replaceExecutable(staged, executable, config.goos)
+    return { ...resolved, updated: true }
+  })
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+/**
+ * Project the Go-shaped result onto the frozen `UpdateResult` contract, which
+ * names the remote tag `latestVersion` and has **no `upToDate` field**.
+ *
+ * The `update` command needs `upToDate` to choose between its three table
+ * renderings (SPEC_AUTH_RELEASE §3.10). Two ways to get it without changing
+ * the contract:
+ *
+ *   - preferred: call `runUpdate` directly, which returns `UpdateRunResult`
+ *     with `upToDate` and `targetVersion` intact;
+ *   - equivalent: recompute it as
+ *     `compareVersions(latestVersion, currentVersion)` being
+ *     `{ comparable: true, order: 0 }` — the exact predicate `runUpdate` uses.
+ */
+export const toUpdateResult = (result: UpdateRunResult): UpdateResult => ({
+  currentVersion: result.currentVersion,
+  latestVersion: result.targetVersion,
+  updated: result.updated,
+  asset: result.assetName,
+  executable: result.executablePath
+})
+
+/** A `UpdaterShape` bound to an explicit config — the seam the tests drive. */
+export const updaterWith = (config: UpdaterConfig) =>
+  Effect.gen(function* () {
+    const services = yield* Effect.context()
+    return {
+      run: (options: UpdateOptions) =>
+        runUpdate(config, options).pipe(Effect.map(toUpdateResult), Effect.provide(services))
+    } satisfies UpdaterShape
+  })
+
+export const makeUpdater = Effect.gen(function* () {
+  const versionInfo = yield* VersionInfo
+  const processEnv = yield* ProcessEnv
+  const details = yield* versionInfo.get
+
+  // An unmappable host is reported when the update actually runs, not at layer
+  // construction time, so every other command still works on an exotic host.
+  const platform = Effect.try({
+    try: () => hostPlatform(processEnv.platform, processEnv.arch),
+    catch: (cause) => operational(describe(cause), cause)
+  })
+
+  const services = yield* Effect.context()
+
+  return {
+    run: (options: UpdateOptions) =>
+      Effect.gen(function* () {
+        const { goarch, goos } = yield* platform
+        const result = yield* runUpdate(
+          {
+            repo: DEFAULT_REPO,
+            apiBaseUrl: DEFAULT_API_BASE_URL,
+            currentVersion: details.version,
+            goos,
+            goarch,
+            executablePath: undefined
+          },
+          options
+        )
+        return toUpdateResult(result)
+      }).pipe(Effect.provide(services))
+  } satisfies UpdaterShape
+})
+
+export const UpdaterLive = Layer.effect(Updater, makeUpdater)
diff --git a/src/impl/versionInfo.test.ts b/src/impl/versionInfo.test.ts
new file mode 100644
index 0000000..ef1faeb
--- /dev/null
+++ b/src/impl/versionInfo.test.ts
@@ -0,0 +1,120 @@
+/**
+ * Ports `internal/version/version_test.go` (2 cases).
+ *
+ * `TestGetDefaults` asserted `info.GoVersion === runtime.Version()` and
+ * `OS/Arch === runtime.GOOS/GOARCH`. The TS analogue asserts the Bun version
+ * under the retained `goVersion` key, and the Go-spelled os/arch.
+ *
+ * `TestGetUsesInjectedValues` mutated the package variables. Bun's `--define`
+ * is not mutable at runtime, so `resolveVersionDetails(overrides)` is the
+ * equivalent seam.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import {
+  goarch,
+  goos,
+  makeVersionInfo,
+  resolveVersionDetails,
+  runtimeVersion
+} from "./versionInfo.ts"
+
+const noEnv = () => undefined
+
+describe("resolveVersionDetails", () => {
+  // internal/version/version_test.go: TestGetDefaults
+  test("defaults are dev/unknown/unknown with a populated runtime and platform", () => {
+    const info = resolveVersionDetails({ env: noEnv })
+    expect(info.version).toBe("dev")
+    expect(info.commit).toBe("unknown")
+    expect(info.date).toBe("unknown")
+    expect(info.goVersion).toBe(runtimeVersion())
+    expect(info.goVersion).toBe(`bun${Bun.version}`)
+    expect(info.os).toBe(goos(process.platform))
+    expect(info.arch).toBe(goarch(process.arch))
+    expect(info.version).not.toBe("")
+  })
+
+  // internal/version/version_test.go: TestGetUsesInjectedValues
+  test("injected values win over the defaults", () => {
+    const info = resolveVersionDetails({
+      version: "v9.9.9",
+      commit: "abcdef1",
+      date: "2026-01-02T03:04:05Z",
+      env: noEnv
+    })
+    expect(info.version).toBe("v9.9.9")
+    expect(info.commit).toBe("abcdef1")
+    expect(info.date).toBe("2026-01-02T03:04:05Z")
+  })
+
+  test("the six documented JSON keys are all present, goVersion included", () => {
+    const info = resolveVersionDetails({ env: noEnv })
+    expect(Object.keys(info).sort()).toEqual([
+      "arch",
+      "commit",
+      "date",
+      "goVersion",
+      "os",
+      "version"
+    ])
+  })
+
+  test("an empty override is ignored rather than blanking the field", () => {
+    const info = resolveVersionDetails({ version: "", commit: "", date: "", env: noEnv })
+    expect(info.version).toBe("dev")
+    expect(info.commit).toBe("unknown")
+    expect(info.date).toBe("unknown")
+  })
+
+  test("OYTC_* env vars fill in for an unstamped build", () => {
+    const env = (name: string) =>
+      ({ OYTC_VERSION: "v0.4.2", OYTC_COMMIT: "cafe123", OYTC_DATE: "2026-07-24T00:00:00Z" })[
+        name
+      ]
+    const info = resolveVersionDetails({ env })
+    expect(info.version).toBe("v0.4.2")
+    expect(info.commit).toBe("cafe123")
+    expect(info.date).toBe("2026-07-24T00:00:00Z")
+  })
+
+  test("an empty env var does not shadow the default", () => {
+    const info = resolveVersionDetails({ env: () => "" })
+    expect(info.version).toBe("dev")
+    expect(info.commit).toBe("unknown")
+  })
+
+  test("platform and arch overrides are normalized to Go spellings", () => {
+    const info = resolveVersionDetails({ platform: "win32", arch: "x64", env: noEnv })
+    expect(info.os).toBe("windows")
+    expect(info.arch).toBe("amd64")
+  })
+})
+
+describe("goos / goarch", () => {
+  test.each([
+    ["darwin", "darwin"],
+    ["linux", "linux"],
+    ["win32", "windows"],
+    ["freebsd", "freebsd"]
+  ])("goos(%s) -> %s", (input, expected) => {
+    expect(goos(input)).toBe(expected)
+  })
+
+  test.each([
+    ["x64", "amd64"],
+    ["arm64", "arm64"],
+    ["ia32", "386"]
+  ])("goarch(%s) -> %s", (input, expected) => {
+    expect(goarch(input)).toBe(expected)
+  })
+})
+
+describe("VersionInfo service", () => {
+  test("get resolves the same details", async () => {
+    const info = await Effect.runPromise(makeVersionInfo.get)
+    expect(info.goVersion).toBe(runtimeVersion())
+    expect(info.os).toBe(goos(process.platform))
+  })
+})
diff --git a/src/impl/versionInfo.ts b/src/impl/versionInfo.ts
index ca14f9a..5e1cb84 100644
--- a/src/impl/versionInfo.ts
+++ b/src/impl/versionInfo.ts
@@ -1,2 +1,109 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `VersionInfo` — the port of `internal/version/version.go`.
+ *
+ * Go injected three package variables with `-ldflags -X`. Bun's equivalent is
+ * `--define`, which textually substitutes a bare identifier at build time:
+ *
+ *     bun build --compile \
+ *       --define OYTC_VERSION='"v1.2.3"' \
+ *       --define OYTC_COMMIT='"abc1234"' \
+ *       --define OYTC_DATE='"2026-01-02T15:04:05Z"'
+ *
+ * `typeof OYTC_VERSION === "string"` is safe on an *undeclared* identifier, so
+ * an un-defined build folds to the default. Defaults match Go exactly:
+ * `dev` / `unknown` / `unknown`.
+ *
+ * **The Go build-info fallback is dropped, deliberately.** Go consulted
+ * `debug.ReadBuildInfo()` so that `go install pkg@v1.2.3` and VCS stamping
+ * produced a real version without ldflags. Bun has no analogue. (SPEC §5.2
+ * documents this as the expected port.)
+ *
+ * Two keys deserve a note:
+ *
+ * - **`goVersion` is retained.** It is a documented JSON column and the
+ *   `version` table's `go:` line, so renaming it would be an API change. It
+ *   now carries the Bun version, formatted `bun` to mirror Go's
+ *   `go1.26.5` shape.
+ * - **`os`/`arch` are normalized to Go's spellings** (`win32` -> `windows`,
+ *   `x64` -> `amd64`). Without this, `oytc version` on linux-x64 would start
+ *   reporting `x64` where every previous release reported `amd64`, and the
+ *   value would no longer match the release asset the user downloaded.
+ */
+
+import { Effect, Layer } from "effect"
+import { VersionInfo, type VersionDetails, type VersionInfoShape } from "../services/index.ts"
+
+declare const OYTC_VERSION: string
+declare const OYTC_COMMIT: string
+declare const OYTC_DATE: string
+
+// `typeof ` is the one expression that does not throw a
+// ReferenceError, so these read as the substituted literal in a stamped build
+// and as `undefined` in an unstamped one.
+const definedVersion = (): string | undefined =>
+  typeof OYTC_VERSION === "string" && OYTC_VERSION !== "" ? OYTC_VERSION : undefined
+const definedCommit = (): string | undefined =>
+  typeof OYTC_COMMIT === "string" && OYTC_COMMIT !== "" ? OYTC_COMMIT : undefined
+const definedDate = (): string | undefined =>
+  typeof OYTC_DATE === "string" && OYTC_DATE !== "" ? OYTC_DATE : undefined
+
+/** `process.platform` -> Go's `runtime.GOOS`. Only `win32` differs. */
+export const goos = (platform: string): string => (platform === "win32" ? "windows" : platform)
+
+/** `process.arch` -> Go's `runtime.GOARCH`. */
+export const goarch = (arch: string): string =>
+  arch === "x64" ? "amd64" : arch === "ia32" ? "386" : arch
+
+/** Go's `runtime.Version()` analogue: the runtime name with its version. */
+export const runtimeVersion = (): string =>
+  typeof Bun === "undefined" ? `node${process.versions.node}` : `bun${Bun.version}`
+
+/**
+ * Resolve the effective build metadata.
+ *
+ * `overrides` is the test seam that replaces Go's mutable package variables
+ * (`version.Version = "v9.9.9"` in `TestGetUsesInjectedValues`). Production
+ * calls pass nothing and get the build-time defines.
+ *
+ * The `OYTC_*` environment variables are consulted only when the corresponding
+ * define is absent, which keeps `bun run src/main.ts` agreeing with `main.ts`'s
+ * own `process.env["OYTC_VERSION"]` read while leaving a stamped release
+ * binary immune to environment tampering.
+ */
+export const resolveVersionDetails = (overrides?: {
+  readonly version?: string | undefined
+  readonly commit?: string | undefined
+  readonly date?: string | undefined
+  readonly platform?: string | undefined
+  readonly arch?: string | undefined
+  readonly runtime?: string | undefined
+  readonly env?: (name: string) => string | undefined
+}): VersionDetails => {
+  const env = overrides?.env ?? ((name: string) => process.env[name])
+  const pick = (
+    override: string | undefined,
+    defined: string | undefined,
+    envName: string,
+    fallback: string
+  ): string => {
+    if (override !== undefined && override !== "") return override
+    if (defined !== undefined) return defined
+    const fromEnv = env(envName)
+    return fromEnv !== undefined && fromEnv !== "" ? fromEnv : fallback
+  }
+
+  return {
+    version: pick(overrides?.version, definedVersion(), "OYTC_VERSION", "dev"),
+    commit: pick(overrides?.commit, definedCommit(), "OYTC_COMMIT", "unknown"),
+    date: pick(overrides?.date, definedDate(), "OYTC_DATE", "unknown"),
+    goVersion: overrides?.runtime ?? runtimeVersion(),
+    os: goos(overrides?.platform ?? process.platform),
+    arch: goarch(overrides?.arch ?? process.arch)
+  }
+}
+
+export const makeVersionInfo: VersionInfoShape = {
+  get: Effect.sync(() => resolveVersionDetails())
+}
+
+export const VersionInfoLive = Layer.succeed(VersionInfo, makeVersionInfo)
diff --git a/src/impl/youtubeApi.test.ts b/src/impl/youtubeApi.test.ts
new file mode 100644
index 0000000..5952ba9
--- /dev/null
+++ b/src/impl/youtubeApi.test.ts
@@ -0,0 +1,491 @@
+/**
+ * Data API client tests.
+ *
+ * Ported from `internal/youtube/client_test.go`:
+ *   TestListPaginationLimitAndToken            (MODIFIED — see DEVIATIONS.md D2)
+ *   TestListReturnsEmptySliceWhenResponseHasNoItems
+ *
+ * These run against a stub `HttpCore` rather than a stub `fetch`, because the
+ * transport already has its own suite; what matters here is the pagination
+ * algebra. One case reaches all the way down through the real `HttpCore` to a
+ * stub `fetch` to prove the two layers actually compose.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Cause, Effect, Exit, Layer, Option } from "effect"
+import { FetchHttpClient } from "../effect.ts"
+import { ApiError, OperationalError, type OytcError } from "../domain/errors.ts"
+import { defaultPageOptions, type PageOptions } from "../domain/listResult.ts"
+import { parseJson } from "../json/parse.ts"
+import { isRawNumber, type JsonObject, type JsonValue } from "../json/value.ts"
+import {
+  HttpCore,
+  type HttpCoreRequest,
+  type HttpCoreShape,
+  type Params
+} from "../services/index.ts"
+import { makeHttpCore } from "./httpCore.ts"
+import { makeYouTubeApi } from "./youtubeApi.ts"
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+interface SeenCall {
+  readonly resource: string
+  readonly params: Params
+  readonly authenticate: boolean
+  readonly baseUrl: string
+}
+
+interface Stub {
+  readonly seen: Array
+  readonly layer: Layer.Layer
+}
+
+/** See httpCore.test.ts — a stub only needs fetch's call signature. */
+type StubFetch = (input: URL | RequestInfo, init?: RequestInit) => Promise
+
+const jsonBody = (text: string): JsonValue => {
+  const parsed = parseJson(text)
+  if (parsed._tag === "Failure") throw new Error(`bad fixture: ${parsed.failure.message}`)
+  return parsed.success
+}
+
+/** `bodies[n-1]` answers request n; the last entry repeats. */
+const stubCore = (bodies: ReadonlyArray): Stub => {
+  const seen: Array = []
+  const layer = Layer.succeed(HttpCore, {
+    getJson: (request: HttpCoreRequest) => {
+      seen.push({
+        resource: request.resource,
+        params: request.params,
+        authenticate: request.authenticate,
+        baseUrl: request.baseUrl
+      })
+      const entry = bodies[Math.min(seen.length - 1, bodies.length - 1)]!
+      return typeof entry === "string"
+        ? Effect.succeed(jsonBody(entry))
+        : Effect.fail(entry as never)
+    }
+  })
+  return { seen, layer }
+}
+
+const runList = (
+  bodies: ReadonlyArray,
+  options: Partial = {},
+  resource = "playlistItems",
+  params: Params = []
+) => {
+  const stub = stubCore(bodies)
+  const program = Effect.gen(function* () {
+    const api = yield* makeYouTubeApi()
+    return yield* api.list(resource, params, { ...defaultPageOptions, ...options })
+  })
+  return Effect.runPromise(
+    program.pipe(Effect.provide(stub.layer), Effect.exit)
+  ).then((exit) => ({ exit, seen: stub.seen }))
+}
+
+const okOf = (exit: Exit.Exit): A => {
+  if (!Exit.isSuccess(exit)) throw new Error(`expected success: ${Cause.pretty(exit.cause)}`)
+  return exit.value
+}
+
+const errOf = (exit: Exit.Exit): E => {
+  if (!Exit.isFailure(exit)) throw new Error("expected failure")
+  const found = Cause.findErrorOption(exit.cause)
+  if (!Option.isSome(found)) throw new Error("no error in cause")
+  return found.value
+}
+
+const param = (params: Params, key: string): string | undefined =>
+  params.find(([k]) => k === key)?.[1]
+
+const ids = (items: ReadonlyArray): ReadonlyArray =>
+  items.map((item) => item["id"])
+
+// ---------------------------------------------------------------------------
+// get
+// ---------------------------------------------------------------------------
+
+describe("get", () => {
+  test("decodes the envelope and always authenticates", async () => {
+    const stub = stubCore([`{"items":[{"id":"v"}],"nextPageToken":"n","kind":"youtube#videoListResponse"}`])
+    const response = await Effect.runPromise(
+      Effect.gen(function* () {
+        const api = yield* makeYouTubeApi()
+        return yield* api.get("videos", [["id", "v"]])
+      }).pipe(Effect.provide(stub.layer))
+    )
+    expect(response.items).toHaveLength(1)
+    expect(response.nextPageToken).toBe("n")
+    expect(stub.seen[0]!.authenticate).toBe(true)
+    expect(stub.seen[0]!.resource).toBe("videos")
+  })
+
+  test("{} decodes with no items", async () => {
+    const stub = stubCore(["{}"])
+    const response = await Effect.runPromise(
+      Effect.gen(function* () {
+        const api = yield* makeYouTubeApi()
+        return yield* api.get("search", [])
+      }).pipe(Effect.provide(stub.layer))
+    )
+    expect(response.items).toBeUndefined()
+  })
+
+  test("unknown top-level keys are ignored", async () => {
+    const stub = stubCore([`{"items":[],"regionCode":"US","tokenPagination":{}}`])
+    const response = await Effect.runPromise(
+      Effect.gen(function* () {
+        const api = yield* makeYouTubeApi()
+        return yield* api.get("search", [])
+      }).pipe(Effect.provide(stub.layer))
+    )
+    expect(response.items).toEqual([])
+  })
+
+  test("defaults to the production base URL", async () => {
+    const stub = stubCore(["{}"])
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const api = yield* makeYouTubeApi()
+        return yield* api.get("videos", [])
+      }).pipe(Effect.provide(stub.layer))
+    )
+    expect(stub.seen[0]!.baseUrl).toBe("https://www.googleapis.com/youtube/v3")
+  })
+
+  test("an overridden base URL is threaded through", async () => {
+    const stub = stubCore(["{}"])
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const api = yield* makeYouTubeApi({ baseUrl: "https://stub.test/v3" })
+        return yield* api.get("videos", [])
+      }).pipe(Effect.provide(stub.layer))
+    )
+    expect(stub.seen[0]!.baseUrl).toBe("https://stub.test/v3")
+  })
+
+  test("propagates an ApiError unchanged", async () => {
+    const stub = stubCore([
+      new ApiError({ httpStatus: 403, code: 403, apiMessage: "no", reasons: ["quotaExceeded"] })
+    ])
+    const exit = await Effect.runPromise(
+      Effect.gen(function* () {
+        const api = yield* makeYouTubeApi()
+        return yield* api.get("videos", [])
+      }).pipe(Effect.provide(stub.layer), Effect.exit)
+    )
+    const error = errOf(exit)
+    expect(error).toBeInstanceOf(ApiError)
+  })
+
+  test("an envelope of the wrong shape is a decode error", async () => {
+    const stub = stubCore([`{"items":"not-an-array"}`])
+    const exit = await Effect.runPromise(
+      Effect.gen(function* () {
+        const api = yield* makeYouTubeApi()
+        return yield* api.get("videos", [])
+      }).pipe(Effect.provide(stub.layer), Effect.exit)
+    )
+    const error = errOf(exit)
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toStartWith("decode YouTube API response: ")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// list — pagination
+// ---------------------------------------------------------------------------
+
+describe("list", () => {
+  // Go: TestListPaginationLimitAndToken — MODIFIED under DEVIATIONS.md D2.
+  test("all=true, limit=3, pageSize=2: two requests, three items, empty token", async () => {
+    const { exit, seen } = await runList(
+      [
+        `{"items":[{"id":"1"},{"id":"2"}],"nextPageToken":"next"}`,
+        `{"items":[{"id":"3"},{"id":"4"}],"nextPageToken":"unused"}`
+      ],
+      { all: true, limit: 3, pageSize: 2, pageToken: "start" }
+    )
+
+    const result = okOf(exit)
+    expect(result.items).toHaveLength(3)
+    expect(ids(result.items)).toEqual(["1", "2", "3"])
+    expect(result.requests).toBe(2)
+    // DEVIATIONS.md D2: Go asserted "unused" here. Page 2 returned 2 items but
+    // only 1 was kept, so "unused" points past the discarded 4th item and is
+    // not a valid resume point. Report "" instead.
+    expect(result.nextPageToken).toBe("")
+
+    expect(seen).toHaveLength(2)
+    expect(param(seen[0]!.params, "maxResults")).toBe("2")
+    expect(param(seen[0]!.params, "pageToken")).toBe("start")
+    expect(param(seen[1]!.params, "maxResults")).toBe("2")
+    expect(param(seen[1]!.params, "pageToken")).toBe("next")
+  })
+
+  // DEVIATIONS.md D2 — the adjacent exact-boundary case.
+  test("all=true, limit=4, pageSize=2: the exact boundary KEEPS the token", async () => {
+    const { exit, seen } = await runList(
+      [
+        `{"items":[{"id":"1"},{"id":"2"}],"nextPageToken":"next"}`,
+        `{"items":[{"id":"3"},{"id":"4"}],"nextPageToken":"still-valid"}`
+      ],
+      { all: true, limit: 4, pageSize: 2, pageToken: "start" }
+    )
+
+    const result = okOf(exit)
+    expect(ids(result.items)).toEqual(["1", "2", "3", "4"])
+    expect(result.requests).toBe(2)
+    // No items were DISCARDED from page 2 — it filled the limit exactly — so
+    // the token is a correct resume point and is kept.
+    expect(result.nextPageToken).toBe("still-valid")
+    expect(seen).toHaveLength(2)
+  })
+
+  test("truncation is evaluated per page, not once at the end", async () => {
+    // Page 1 is truncated but the loop continues would-be… it does not: the
+    // limit is reached, so it stops with "" from the truncated page.
+    const { exit } = await runList(
+      [`{"items":[{"id":"1"},{"id":"2"},{"id":"3"}],"nextPageToken":"n"}`],
+      { all: true, limit: 2, pageSize: 3 }
+    )
+    const result = okOf(exit)
+    expect(ids(result.items)).toEqual(["1", "2"])
+    expect(result.nextPageToken).toBe("")
+  })
+
+  test("a single page truncated by the limit reports no token", async () => {
+    // DEVIATIONS.md D2, row "No --all (single page), truncated".
+    const { exit } = await runList([`{"items":[{"id":"1"},{"id":"2"}],"nextPageToken":"t"}`], {
+      limit: 1
+    })
+    const result = okOf(exit)
+    expect(ids(result.items)).toEqual(["1"])
+    expect(result.nextPageToken).toBe("")
+    expect(result.requests).toBe(1)
+  })
+
+  test("a single untruncated page keeps its token", async () => {
+    const { exit } = await runList([`{"items":[{"id":"1"}],"nextPageToken":"t"}`], { limit: 5 })
+    expect(okOf(exit).nextPageToken).toBe("t")
+  })
+
+  test("without all, exactly one request is made regardless of limit", async () => {
+    const { exit, seen } = await runList(
+      [`{"items":[{"id":"1"}],"nextPageToken":"more"}`],
+      { all: false, limit: 100 }
+    )
+    expect(seen).toHaveLength(1)
+    const result = okOf(exit)
+    expect(result.requests).toBe(1)
+    expect(result.nextPageToken).toBe("more")
+  })
+
+  test("all=true stops on an empty upstream token", async () => {
+    const { exit, seen } = await runList(
+      [`{"items":[{"id":"1"}],"nextPageToken":"n"}`, `{"items":[{"id":"2"}]}`],
+      { all: true }
+    )
+    expect(seen).toHaveLength(2)
+    const result = okOf(exit)
+    expect(ids(result.items)).toEqual(["1", "2"])
+    expect(result.nextPageToken).toBe("")
+  })
+
+  test("all=true with no limit walks every page", async () => {
+    const { exit, seen } = await runList(
+      [
+        `{"items":[{"id":"1"}],"nextPageToken":"a"}`,
+        `{"items":[{"id":"2"}],"nextPageToken":"b"}`,
+        `{"items":[{"id":"3"}]}`
+      ],
+      { all: true }
+    )
+    expect(seen).toHaveLength(3)
+    expect(okOf(exit).requests).toBe(3)
+    expect(param(seen[1]!.params, "pageToken")).toBe("a")
+    expect(param(seen[2]!.params, "pageToken")).toBe("b")
+  })
+
+  // Go: TestListReturnsEmptySliceWhenResponseHasNoItems
+  test("items is a non-null empty array when the response has none", async () => {
+    const { exit } = await runList(["{}"], {}, "search")
+    const result = okOf(exit)
+    expect(result.items).toEqual([])
+    expect(Array.isArray(result.items)).toBe(true)
+    expect(result.requests).toBe(1)
+    expect(result.nextPageToken).toBe("")
+  })
+
+  test("pageSize=0 sends no maxResults", async () => {
+    const { seen } = await runList([`{"items":[]}`], { pageSize: 0 })
+    expect(param(seen[0]!.params, "maxResults")).toBeUndefined()
+  })
+
+  test("pageToken='' sends no pageToken", async () => {
+    const { seen } = await runList([`{"items":[]}`], { pageToken: "" })
+    expect(param(seen[0]!.params, "pageToken")).toBeUndefined()
+  })
+
+  test("maxResults replaces a caller-supplied value rather than duplicating it", async () => {
+    const { seen } = await runList([`{"items":[]}`], { pageSize: 7 }, "playlistItems", [
+      ["maxResults", "1"],
+      ["part", "snippet"]
+    ])
+    expect(seen[0]!.params.filter(([k]) => k === "maxResults")).toHaveLength(1)
+    expect(param(seen[0]!.params, "maxResults")).toBe("7")
+    expect(param(seen[0]!.params, "part")).toBe("snippet")
+  })
+
+  test("the caller's params array is never mutated", async () => {
+    const params: Params = [["part", "snippet"]]
+    await runList([`{"items":[{"id":"1"}],"nextPageToken":"a"}`, `{"items":[]}`], {
+      all: true,
+      pageSize: 5
+    }, "search", params)
+    expect(params).toEqual([["part", "snippet"]])
+  })
+
+  test("limit=0 means no cap", async () => {
+    const { exit } = await runList([`{"items":[{"id":"1"},{"id":"2"},{"id":"3"}]}`], { limit: 0 })
+    expect(okOf(exit).items).toHaveLength(3)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// list — filtering
+// ---------------------------------------------------------------------------
+
+describe("list filtering", () => {
+  const isVideo = (item: JsonObject) => item["kind"] === "video"
+
+  test("the limit is applied AFTER the filter", async () => {
+    const { exit, seen } = await runList(
+      [
+        `{"items":[{"id":"1","kind":"channel"},{"id":"2","kind":"video"}],"nextPageToken":"n"}`,
+        `{"items":[{"id":"3","kind":"channel"},{"id":"4","kind":"video"}],"nextPageToken":"n2"}`,
+        `{"items":[{"id":"5","kind":"video"}]}`
+      ],
+      { all: true, limit: 3, filter: isVideo }
+    )
+    const result = okOf(exit)
+    expect(ids(result.items)).toEqual(["2", "4", "5"])
+    // Three pages were needed for three items.
+    expect(seen).toHaveLength(3)
+    expect(result.requests).toBe(3)
+  })
+
+  test("a page can contribute zero items while still consuming a request", async () => {
+    const { exit } = await runList(
+      [
+        `{"items":[{"id":"1","kind":"channel"}],"nextPageToken":"n"}`,
+        `{"items":[{"id":"2","kind":"video"}]}`
+      ],
+      { all: true, filter: isVideo }
+    )
+    const result = okOf(exit)
+    expect(ids(result.items)).toEqual(["2"])
+    expect(result.requests).toBe(2)
+  })
+
+  test("a filter that rejects everything yields an empty result", async () => {
+    const { exit } = await runList([`{"items":[{"id":"1","kind":"channel"}]}`], {
+      filter: isVideo
+    })
+    expect(okOf(exit).items).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// list — errors and precision
+// ---------------------------------------------------------------------------
+
+describe("list errors", () => {
+  test("an error on the first page aborts immediately", async () => {
+    const { exit, seen } = await runList(
+      [new ApiError({ httpStatus: 500, code: 500, apiMessage: "boom", reasons: [] })],
+      { all: true }
+    )
+    expect(errOf(exit)).toBeInstanceOf(ApiError)
+    expect(seen).toHaveLength(1)
+  })
+
+  test("an error on a later page aborts the whole list", async () => {
+    const { exit, seen } = await runList(
+      [
+        `{"items":[{"id":"1"}],"nextPageToken":"n"}`,
+        new ApiError({ httpStatus: 503, code: 503, apiMessage: "later", reasons: [] })
+      ],
+      { all: true }
+    )
+    expect(errOf(exit)).toBeInstanceOf(ApiError)
+    expect(seen).toHaveLength(2)
+  })
+})
+
+test("large numeric literals survive the list path intact", async () => {
+  const { exit } = await runList([
+    `{"items":[{"id":"v","statistics":{"viewCount":9007199254740993123}}]}`
+  ])
+  const item = okOf(exit).items[0]!
+  const stats = item["statistics"] as JsonObject
+  const count = stats["viewCount"]!
+  expect(isRawNumber(count)).toBe(true)
+  if (!isRawNumber(count)) throw new Error("unreachable")
+  expect(count.$rawNumber).toBe("9007199254740993123")
+})
+
+// ---------------------------------------------------------------------------
+// Composition with the real transport
+// ---------------------------------------------------------------------------
+
+test("composes with the real HttpCore over a stub fetch", async () => {
+  const urls: Array = []
+  const stub: StubFetch = async (input) => {
+    urls.push(String(input))
+    const body =
+      urls.length === 1
+        ? `{"items":[{"id":"1"},{"id":"2"}],"nextPageToken":"p2"}`
+        : `{"items":[{"id":"3"}]}`
+    return new Response(body, { status: 200 })
+  }
+
+  const result = await Effect.runPromise(
+    Effect.gen(function* () {
+      const core = yield* makeHttpCore({
+        apiKey: "k",
+        tokenSource: undefined,
+        maxRetries: 0
+      })
+      const api = yield* makeYouTubeApi({ baseUrl: "https://stub.test/youtube/v3" }).pipe(
+        Effect.provide(Layer.succeed(HttpCore, core))
+      )
+      return yield* api.list("liveChat/messages", [["part", "snippet"]], {
+        ...defaultPageOptions,
+        all: true,
+        pageSize: 2
+      })
+    }).pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, stub as unknown as typeof globalThis.fetch))
+    ) as Effect.Effect<{
+      readonly items: ReadonlyArray
+      readonly nextPageToken: string
+      readonly requests: number
+    }>
+  )
+
+  expect(ids(result.items)).toEqual(["1", "2", "3"])
+  expect(result.requests).toBe(2)
+  // The embedded slash survives, params are sorted, and no credential leaked.
+  expect(urls[0]).toBe("https://stub.test/youtube/v3/liveChat/messages?maxResults=2&part=snippet")
+  expect(urls[1]).toBe(
+    "https://stub.test/youtube/v3/liveChat/messages?maxResults=2&pageToken=p2&part=snippet"
+  )
+  expect(urls.every((u) => !u.includes("k="))).toBe(true)
+})
diff --git a/src/impl/youtubeApi.ts b/src/impl/youtubeApi.ts
index ca14f9a..f3129b9 100644
--- a/src/impl/youtubeApi.ts
+++ b/src/impl/youtubeApi.ts
@@ -1,2 +1,135 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * The YouTube Data API client — `Get`, `List` and `ResolveChannel` from
+ * `internal/youtube/client.go` + `list.go`, layered over `HttpCore`.
+ *
+ * `Get` decodes the one typed envelope; `items` stay opaque records, because
+ * `--parts` and `--fields` let a user request arbitrary subsets and any
+ * per-resource schema would reject responses the Go client accepts.
+ */
+
+import { Effect, Layer, Result, Schema } from "effect"
+import { OperationalError, type OytcError } from "../domain/errors.ts"
+import type { ListResult, PageOptions } from "../domain/listResult.ts"
+import type { JsonObject } from "../json/value.ts"
+import { DataApiResponse } from "../schema/dataapi.ts"
+import {
+  HttpCore,
+  type HttpCoreShape,
+  type Params,
+  type ResolvedChannel,
+  YouTubeApi,
+  type YouTubeApiShape
+} from "../services/index.ts"
+import { DEFAULT_BASE_URL } from "./httpCore.ts"
+import { resolveChannelWith } from "./resolveChannel.ts"
+
+export interface YouTubeApiConfig {
+  /** Overridable so tests (and the Analytics client) can retarget the host. */
+  readonly baseUrl?: string | undefined
+}
+
+const decodeResponse = Schema.decodeUnknownResult(DataApiResponse)
+
+/**
+ * `params.Set(key, value)` — replaces every existing entry for `key` and, when
+ * the key is new, appends. Position of an existing key is preserved, which is
+ * invisible in the URL (the encoder sorts) but keeps this list stable.
+ */
+const setParam = (params: Params, key: string, value: string): Params => {
+  const kept = params.filter(([k]) => k !== key)
+  return kept.length === params.length
+    ? [...params, [key, value] as const]
+    : params.map((entry) => (entry[0] === key ? ([key, value] as const) : entry))
+}
+
+export const makeYouTubeApi = (
+  config: YouTubeApiConfig = {}
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const core = yield* HttpCore
+    const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL
+
+    const get = (resource: string, params: Params): Effect.Effect =>
+      Effect.gen(function* () {
+        const body = yield* core.getJson({ baseUrl, resource, params, authenticate: true })
+        const decoded = decodeResponse(body)
+        if (Result.isFailure(decoded)) {
+          // Go's decoder is far more forgiving than a Schema — it silently
+          // zeroes a wrong-typed field. Reaching this means the envelope's
+          // shape is genuinely wrong, which Go would also surface as a decode
+          // error, so the message matches `%w`-wrapped Go text.
+          return yield* Effect.fail(
+            new OperationalError({
+              message: `decode YouTube API response: ${decoded.failure.message}`,
+              cause: decoded.failure
+            })
+          )
+        }
+        return decoded.success
+      })
+
+    /**
+     * The pagination loop.
+     *
+     * DEVIATIONS.md D2: Go set `nextPageToken` unconditionally to the last
+     * fetched page's token, so a `--limit` truncation advertised a resume token
+     * that skipped the discarded items. Here a page from which items were
+     * DISCARDED reports `""` instead. Evaluated per page, so a page trimmed to
+     * exactly its own length is not truncated and keeps its token.
+     */
+    const list = (
+      resource: string,
+      params: Params,
+      options: PageOptions
+    ): Effect.Effect =>
+      Effect.gen(function* () {
+        // Go mutates the caller's url.Values in place; copying is strictly
+        // safer and observationally identical for every call site.
+        let current = params
+        if (options.pageSize > 0) current = setParam(current, "maxResults", String(options.pageSize))
+        if (options.pageToken !== "") current = setParam(current, "pageToken", options.pageToken)
+
+        const kept: Array = []
+        let requests = 0
+        let nextPageToken = ""
+
+        for (;;) {
+          const response = yield* get(resource, current)
+          requests++
+
+          let items = ((response.items ?? []) as ReadonlyArray).slice()
+          // The filter runs BEFORE the limit, so rejected items do not count
+          // toward it and a page can contribute zero items while still
+          // consuming a request.
+          if (options.filter !== undefined) items = items.filter(options.filter)
+
+          let truncated = false
+          if (options.limit > 0 && kept.length + items.length > options.limit) {
+            items = items.slice(0, options.limit - kept.length)
+            truncated = true // items were DISCARDED from this page
+          }
+          kept.push(...items)
+          // DEVIATIONS.md D2
+          nextPageToken = truncated ? "" : (response.nextPageToken ?? "")
+
+          if (
+            !options.all ||
+            nextPageToken === "" ||
+            (options.limit > 0 && kept.length >= options.limit)
+          ) {
+            break
+          }
+          current = setParam(current, "pageToken", nextPageToken)
+        }
+
+        return { items: kept, nextPageToken, requests }
+      })
+
+    const resolveChannel = (reference: string): Effect.Effect =>
+      resolveChannelWith(get)(reference)
+
+    return { get, list, resolveChannel } satisfies YouTubeApiShape
+  })
+
+export const youTubeApiLayer = (config: YouTubeApiConfig = {}) =>
+  Layer.effect(YouTubeApi, makeYouTubeApi(config))
diff --git a/src/layers.ts b/src/layers.ts
index 0b45b88..b559b58 100644
--- a/src/layers.ts
+++ b/src/layers.ts
@@ -1,14 +1,110 @@
 /**
  * The application Layer graph.
  *
- * Written once, in the foundation. Feature packages supply the `make*`
- * functions in `src/impl/`; this wiring does not change as they land.
+ * One subtlety dominates this file: `HttpCore` needs a token source so it can
+ * attach `Authorization: Bearer` and force a refresh after a 401, and that
+ * token source lives on `OAuthService` — which itself needs an `HttpClient`
+ * (to hit Google's token endpoint) and a `CredentialStore` (to persist a
+ * refreshed token). Wiring `HttpCore <- OAuthService` directly would be a
+ * dependency cycle.
  *
- * `AppOptions` is deliberately NOT here — it is per-invocation and supplied by
+ * It is broken the same way Go broke it: the token source is a *function*
+ * handed to the transport, not a service the transport depends on. The
+ * transport calls `tokenSource(force)` and neither knows nor cares that the
+ * implementation reaches back into OAuth. Effect makes this explicit — the
+ * function is resolved inside the layer body, after OAuthService is built.
+ *
+ * `AppOptions` is deliberately absent: it is per-invocation and supplied by
  * `Command.provide` in cli/root.ts, because it depends on parsed flags.
  */
 
-import { Layer } from "effect"
+import { Effect, Layer } from "effect"
+import { FetchHttpClient } from "./effect.ts"
+import { AnalyticsApiLive } from "./impl/analyticsApi.ts"
+import { BrowserOpenerLive } from "./impl/browserOpener.ts"
+import { CredentialStoreLive } from "./impl/credentialStore.ts"
+import { FileLockLive } from "./impl/fileLock.ts"
+import { makeHttpCore } from "./impl/httpCore.ts"
+import { OAuthServiceLive } from "./impl/oauth.ts"
 import { ProcessEnvLive } from "./impl/processEnv.ts"
+import { PromptsLive } from "./impl/prompts.ts"
+import { RendererLive } from "./impl/renderer.ts"
+import { SkillInstallerLive } from "./impl/skillInstaller.ts"
+import { UpdaterLive } from "./impl/updater.ts"
+import { VersionInfoLive } from "./impl/versionInfo.ts"
+import { makeYouTubeApi } from "./impl/youtubeApi.ts"
+import { CredentialStore, HttpCore, OAuthService, YouTubeApi } from "./services/index.ts"
+
+/** HTTP transport + Fetch. */
+const HttpClientLive = FetchHttpClient.layer
+
+/**
+ * `ProcessEnv` is a dependency of CredentialStore, BrowserOpener,
+ * SkillInstaller and Updater — not merely a sibling of them.
+ *
+ * Effect does NOT let members of a `Layer.mergeAll` satisfy each other's
+ * requirements: an unmet requirement propagates outward as a requirement of
+ * the whole merge, and providing it at the outer edge is too late for a layer
+ * that needs it during construction. So every consumer gets it explicitly via
+ * `Layer.provide`. (Symptom when this is wrong: adding CredentialStore to the
+ * merge makes ProcessEnv itself vanish with "Service not found".)
+ */
+const EnvLive = ProcessEnvLive
+
+/** Credential storage, which serializes writes through the file lock. */
+const CredentialsLive = CredentialStoreLive.pipe(
+  Layer.provide(Layer.mergeAll(FileLockLive, EnvLive))
+)
+
+const BrowserLive = BrowserOpenerLive.pipe(Layer.provide(EnvLive))
+
+/** OAuth needs the HTTP client, the credential store, and a browser opener. */
+const OAuthLive = OAuthServiceLive.pipe(
+  Layer.provide(Layer.mergeAll(HttpClientLive, CredentialsLive, BrowserLive))
+)
+
+/**
+ * The transport.
+ *
+ * An API key is read once at construction (matching Go, which resolved it
+ * before issuing any request), and the token source is only attached when
+ * OAuth credentials actually exist — otherwise `HttpCore`'s first-match-wins
+ * auth switch would take the OAuth branch and fail with MissingOAuthError
+ * instead of falling through to the key.
+ */
+const HttpCoreLive = Layer.effect(
+  HttpCore,
+  Effect.gen(function* () {
+    const credentials = yield* CredentialStore
+    const oauth = yield* OAuthService
+    const stored = yield* credentials.load
+
+    return yield* makeHttpCore({
+      apiKey: stored.key,
+      tokenSource: stored.oauth === undefined ? undefined : oauth.tokenSource
+    })
+  })
+).pipe(Layer.provide(Layer.mergeAll(HttpClientLive, CredentialsLive, OAuthLive)))
+
+const YouTubeApiLive = Layer.effect(YouTubeApi, makeYouTubeApi()).pipe(
+  Layer.provide(HttpCoreLive)
+)
+
+const AnalyticsLive = AnalyticsApiLive.pipe(Layer.provide(HttpCoreLive))
 
-export const AppLayer = Layer.mergeAll(ProcessEnvLive)
+export const AppLayer = Layer.mergeAll(
+  EnvLive,
+  CredentialsLive,
+  HttpCoreLive,
+  YouTubeApiLive,
+  AnalyticsLive,
+  OAuthLive,
+  UpdaterLive.pipe(
+    Layer.provide(Layer.mergeAll(HttpClientLive, EnvLive, VersionInfoLive))
+  ),
+  SkillInstallerLive.pipe(Layer.provide(EnvLive)),
+  RendererLive,
+  PromptsLive,
+  BrowserLive,
+  VersionInfoLive
+)
diff --git a/src/main.ts b/src/main.ts
index 3653027..1bc4b31 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -10,16 +10,23 @@
  * is for the CLI framework's own parse failures: it exits 1 where Go exits 2.
  */
 
-import { Effect } from "effect"
+import { Effect, Layer } from "effect"
 import { BunRuntime, BunServices } from "@effect/platform-bun"
 import { Command } from "./effect.ts"
 import { AppLayer } from "./layers.ts"
 import { root } from "./cli/root.ts"
+import { resolveVersionDetails } from "./impl/versionInfo.ts"
 
-const cli = Command.run(root, {
-  version: process.env["OYTC_VERSION"] ?? "dev"
-})
+const cli = Command.run(root, { version: resolveVersionDetails().version })
 
-BunRuntime.runMain(
-  cli.pipe(Effect.provide(AppLayer), Effect.provide(BunServices.layer))
-)
+/**
+ * BunServices supplies FileSystem/Path/Stdio/Terminal/Spawner. AppLayer's
+ * members depend on those, and so does the CLI runtime itself, so
+ * `provideMerge` is required rather than `provide`: it satisfies AppLayer's
+ * requirements AND keeps the platform services in the output for the command
+ * handlers. Plain `provide` would consume them and leave the CLI unable to
+ * resolve Stdio.
+ */
+const MainLayer = Layer.provideMerge(AppLayer, BunServices.layer)
+
+BunRuntime.runMain(cli.pipe(Effect.provide(MainLayer)))
diff --git a/src/output/columns.test.ts b/src/output/columns.test.ts
new file mode 100644
index 0000000..8ec91cf
--- /dev/null
+++ b/src/output/columns.test.ts
@@ -0,0 +1,547 @@
+import { describe, expect, test } from "bun:test"
+import { Result } from "effect"
+import { parseJson } from "../json/parse.ts"
+import type { JsonObject, JsonValue } from "../json/value.ts"
+import { rawNumber } from "../json/value.ts"
+import {
+  analyticsDemographicsColumns,
+  analyticsOverviewColumns,
+  analyticsOverviewMetrics,
+  analyticsReportColumns,
+  analyticsTrafficSourcesColumns,
+  analyticsVideoColumns,
+  categoryListColumns,
+  cell,
+  channelActivitiesColumns,
+  channelGetColumns,
+  channelSectionsColumns,
+  channelUploadsColumns,
+  clean,
+  commentColumns,
+  commentThreadsColumns,
+  fallbackColumns,
+  generateRows,
+  goUpper,
+  headerCell,
+  headerRow,
+  languageListColumns,
+  liveChatColumns,
+  pathValue,
+  playlistGetColumns,
+  playlistItemsColumns,
+  playlistListColumns,
+  regionListColumns,
+  resolveColumns,
+  rowCells,
+  searchColumns,
+  statusCheckColumns,
+  statusColumns,
+  subscriptionListColumns,
+  updateColumns,
+  versionColumns,
+  videoGetColumns,
+  videoPopularColumns,
+  videoStatsColumns,
+  videoTrainabilityColumns
+} from "./columns.ts"
+
+const obj = (text: string): JsonObject => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as JsonObject
+}
+
+describe("goUpper — Go strings.ToUpper, never length-changing", () => {
+  // Every expectation here was produced by the Go implementation via
+  // `--columns ` header rendering, not by JS toUpperCase().
+  test.each([
+    ["snippet.title", "SNIPPET.TITLE"],
+    ["contentDetails.videoId", "CONTENTDETAILS.VIDEOID"],
+    ["api_key.configured", "API_KEY.CONFIGURED"],
+    ["snippet.topLevelComment.snippet.authorDisplayName", "SNIPPET.TOPLEVELCOMMENT.SNIPPET.AUTHORDISPLAYNAME"],
+    ["", ""],
+    ["ALREADY.UPPER", "ALREADY.UPPER"],
+    ["123-x_y", "123-X_Y"]
+  ])("%s -> %s", (input, want) => {
+    expect(goUpper(input)).toBe(want)
+  })
+
+  test("ß stays ß (JS would produce SS)", () => {
+    expect(goUpper("straße")).toBe("STRAßE")
+    expect("straße".toUpperCase()).toBe("STRASSE")
+  })
+
+  test("fi ligature stays (JS would produce FI)", () => {
+    expect(goUpper("file")).toBe("fiLE")
+  })
+
+  test("dotless i uppercases to I", () => {
+    expect(goUpper("ıd")).toBe("ID")
+  })
+
+  test("dz maps to the upper form DZ, not the title form Dz", () => {
+    expect(goUpper("dzx")).toBe("DZX")
+  })
+
+  // The "leave any length-changing rune alone" rule has 27 counter-examples:
+  // the Greek iota-subscript letters, where Go DOES have a 1-rune simple
+  // mapping (to the prosgegrammeni capital) but JS decomposes to capital +
+  // U+0399. Every expectation below came from Go 1.26.5 `strings.ToUpper`.
+  // Escapes, not literals: NFC normalization would not disturb these, but an
+  // editor that "fixes" Greek text might.
+  test.each([
+    ["ᾀ", "ᾈ"], // ᾀ -> ᾈ   (JS full: "ἈΙ")
+    ["ᾇ", "ᾏ"],
+    ["ᾐ", "ᾘ"],
+    ["ᾗ", "ᾟ"],
+    ["ᾠ", "ᾨ"],
+    ["ᾧ", "ᾯ"],
+    ["ᾳ", "ᾼ"], // ᾳ -> ᾼ   delta is +9 here, not +8
+    ["ῃ", "ῌ"],
+    ["ῳ", "ῼ"]
+  ])("iota subscript %s uppercases to one rune %s", (input, want) => {
+    expect(goUpper(input)).toBe(want)
+    expect(input.toUpperCase()).not.toBe(want) // JS alone gets this wrong
+  })
+
+  test("an iota-subscript rune inside a real column path", () => {
+    expect(goUpper("ᾀid")).toBe("ᾈID")
+  })
+
+  test("the exception table never lengthens a string", () => {
+    for (const cp of [0x1f80, 0x1f87, 0x1f90, 0x1fa7, 0x1fb3, 0x1fc3, 0x1ff3]) {
+      const ch = String.fromCodePoint(cp)
+      expect(Array.from(goUpper(ch)).length).toBe(1)
+    }
+  })
+
+  test("ligatures and ß still stay put (they have no 1-rune mapping)", () => {
+    // Guards against the exception table being widened into "uppercase everything".
+    expect(goUpper("ßfiffi")).toBe("ßfiffi")
+  })
+
+  test("headerCell is goUpper of the whole dotted path", () => {
+    expect(headerCell("snippet.title")).toBe("SNIPPET.TITLE")
+  })
+})
+
+describe("pathValue", () => {
+  test("walks a dotted path", () => {
+    expect(pathValue(obj('{"a":{"b":{"c":"deep"}}}'), "a.b.c")).toBe("deep")
+  })
+
+  test("single segment", () => {
+    expect(pathValue(obj('{"id":"x"}'), "id")).toBe("x")
+  })
+
+  test("missing key is null", () => {
+    expect(pathValue(obj('{"id":"x"}'), "nope")).toBeNull()
+  })
+
+  test("explicit null is null", () => {
+    expect(pathValue(obj('{"a":null}'), "a")).toBeNull()
+  })
+
+  test("intermediate is a string -> null", () => {
+    expect(pathValue(obj('{"a":"notobject"}'), "a.b.c")).toBeNull()
+  })
+
+  test("intermediate is a bool -> null", () => {
+    expect(pathValue(obj('{"a":true}'), "a.b")).toBeNull()
+  })
+
+  test("intermediate is null -> null", () => {
+    expect(pathValue(obj('{"a":null}'), "a.b")).toBeNull()
+  })
+
+  test("intermediate is an array -> null (arrays are not objects)", () => {
+    expect(pathValue(obj('{"a":[1,2]}'), "a.0")).toBeNull()
+  })
+
+  test("intermediate is a number -> null", () => {
+    expect(pathValue(obj('{"a":5}'), "a.b")).toBeNull()
+  })
+
+  test("a key containing a literal dot is unreachable", () => {
+    expect(pathValue(obj('{"a.b":"direct"}'), "a.b")).toBeNull()
+  })
+
+  test("leading dot means an empty first segment", () => {
+    expect(pathValue(obj('{"":{"id":"x"}}'), ".id")).toBe("x")
+  })
+
+  test("trailing dot means an empty last segment", () => {
+    expect(pathValue(obj('{"id":{"":"y"}}'), "id.")).toBe("y")
+  })
+
+  test("empty column path reads the empty-string key", () => {
+    expect(pathValue(obj('{"":"weird"}'), "")).toBe("weird")
+  })
+
+  test("returns whole subtrees, not just leaves", () => {
+    expect(pathValue(obj('{"a":{"b":1}}'), "a")).toEqual({ b: rawNumber("1") })
+  })
+})
+
+describe("cell", () => {
+  test("null is the empty string", () => {
+    expect(cell(null)).toBe("")
+  })
+
+  test("string passes through clean()", () => {
+    expect(cell("plain")).toBe("plain")
+  })
+
+  test("booleans", () => {
+    expect(cell(true)).toBe("true")
+    expect(cell(false)).toBe("false")
+  })
+
+  test.each([
+    ["1.50", "1.50"],
+    ["1e3", "1e3"],
+    ["1E+10", "1E+10"],
+    ["-0.0", "-0.0"],
+    ["900719925474099312345", "900719925474099312345"]
+  ])("number literal %s is emitted verbatim", (literal, want) => {
+    expect(cell(rawNumber(literal))).toBe(want)
+  })
+
+  test("array joins with a bare comma", () => {
+    expect(cell(["a", "b", "c"])).toBe("a,b,c")
+  })
+
+  test("empty array is the empty string", () => {
+    expect(cell([])).toBe("")
+  })
+
+  test("array elements render recursively; null becomes an empty slot", () => {
+    // Go golden for --columns arr over [1,"a",null,{"z":1,"a":2}]
+    const value = (parseJson('[1,"a",null,{"z":1,"a":2}]') as Result.Result)
+    expect(Result.isSuccess(value)).toBe(true)
+    expect(cell(Result.getOrThrow(value))).toBe("1,a,,a=2,z=1")
+  })
+
+  test("object renders sorted k=v pairs", () => {
+    expect(cell({ z: "1", a: "2" })).toBe("a=2,z=1")
+  })
+
+  test("empty object is the empty string", () => {
+    expect(cell({})).toBe("")
+  })
+
+  test("nested objects flatten ambiguously", () => {
+    // Go golden: {"b":{"c":"1","a":"2"},"a":"x"} -> "a=x,b=a=2,c=1"
+    expect(cell(obj('{"b":{"c":"1","a":"2"},"a":"x"}'))).toBe("a=x,b=a=2,c=1")
+  })
+
+  test("object keys sort by UTF-8 bytes, not UTF-16 units", () => {
+    // U+FFFF (0xEF 0xBF 0xBF) sorts BEFORE U+10000 (0xF0 0x90 0x80 0x80) in
+    // UTF-8, but AFTER it under a naive UTF-16 comparison.
+    expect(cell({ "\u{10000}": "astral", "￿": "bmp" })).toBe("￿=bmp,\u{10000}=astral")
+  })
+
+  test("a RawNumber is not mistaken for an object", () => {
+    expect(cell({ n: rawNumber("42") })).toBe("n=42")
+  })
+})
+
+describe("clean — only tab, CR, LF become spaces", () => {
+  test("the Go output_test.go case", () => {
+    expect(clean("line one\nline two")).toBe("line one line two")
+  })
+
+  test("each of tab/CR/LF maps to exactly one space", () => {
+    expect(clean("a\tb\rc\nd")).toBe("a b c d")
+  })
+
+  test("CRLF becomes TWO spaces, not one", () => {
+    expect(clean("a\r\nb")).toBe("a  b")
+  })
+
+  test("vertical tab and form feed SURVIVE (they are not in the replacer)", () => {
+    expect(clean("a\vb\fc")).toBe("a\vb\fc")
+  })
+
+  test("backspace, NUL and other controls survive", () => {
+    expect(clean("a\bbc")).toBe("a\bbc")
+  })
+
+  test("clean is applied by cell()", () => {
+    expect(cell("x\ty")).toBe("x y")
+  })
+})
+
+describe("resolveColumns", () => {
+  test("requested wins", () => {
+    expect(resolveColumns(["a"], ["b"])).toEqual(["a"])
+  })
+
+  test("defaults when nothing requested", () => {
+    expect(resolveColumns([], ["b"])).toEqual(["b"])
+  })
+
+  test("global fallback when both are empty", () => {
+    expect(resolveColumns([], [])).toEqual(["id", "snippet.title"])
+    expect(fallbackColumns).toEqual(["id", "snippet.title"])
+  })
+})
+
+describe("row generation", () => {
+  test("rowCells maps each column through pathValue+cell", () => {
+    expect(rowCells(obj('{"id":"v","snippet":{"title":"T"}}'), ["id", "snippet.title", "nope"])).toEqual([
+      "v",
+      "T",
+      ""
+    ])
+  })
+
+  test("headerRow uppercases every column", () => {
+    expect(headerRow(["id", "snippet.title"])).toEqual(["ID", "SNIPPET.TITLE"])
+  })
+
+  test("generateRows includes the header by default", () => {
+    expect(generateRows([obj('{"id":"a"}')], ["id"], false)).toEqual([["ID"], ["a"]])
+  })
+
+  test("generateRows omits the header when suppressed", () => {
+    expect(generateRows([obj('{"id":"a"}')], ["id"], true)).toEqual([["a"]])
+  })
+
+  test("no items still emits the header row", () => {
+    expect(generateRows([], ["id", "x"], false)).toEqual([["ID", "X"]])
+  })
+
+  test("no items and no header emits nothing", () => {
+    expect(generateRows([], ["id", "x"], true)).toEqual([])
+  })
+})
+
+describe("default column sets (27 of them)", () => {
+  // Every list below was read out of the Go call site named in the comment on
+  // the corresponding export in columns.ts.
+  test("search", () => {
+    expect(searchColumns).toEqual(["id.kind", "id.videoId", "id.channelId", "id.playlistId", "snippet.title"])
+  })
+
+  test("channel get", () => {
+    expect(channelGetColumns).toEqual([
+      "id",
+      "snippet.title",
+      "statistics.subscriberCount",
+      "statistics.videoCount",
+      "statistics.viewCount"
+    ])
+  })
+
+  test("channel activities", () => {
+    expect(channelActivitiesColumns).toEqual(["id", "snippet.publishedAt", "snippet.type", "snippet.title"])
+  })
+
+  test("channel sections", () => {
+    expect(channelSectionsColumns).toEqual(["id", "snippet.type", "snippet.position", "snippet.title"])
+  })
+
+  test("channel uploads", () => {
+    expect(channelUploadsColumns).toEqual([
+      "snippet.position",
+      "contentDetails.videoId",
+      "snippet.title",
+      "snippet.publishedAt"
+    ])
+  })
+
+  test("video get", () => {
+    expect(videoGetColumns).toEqual([
+      "id",
+      "snippet.title",
+      "snippet.channelTitle",
+      "contentDetails.duration",
+      "statistics.viewCount"
+    ])
+  })
+
+  test("video stats", () => {
+    expect(videoStatsColumns).toEqual([
+      "id",
+      "statistics.viewCount",
+      "statistics.likeCount",
+      "statistics.commentCount"
+    ])
+  })
+
+  test("video popular", () => {
+    expect(videoPopularColumns).toEqual(["id", "snippet.title", "snippet.channelTitle", "statistics.viewCount"])
+  })
+
+  test("video trainability", () => {
+    expect(videoTrainabilityColumns).toEqual(["videoId", "permitted"])
+  })
+
+  test("playlist get", () => {
+    expect(playlistGetColumns).toEqual([
+      "id",
+      "snippet.title",
+      "snippet.channelTitle",
+      "contentDetails.itemCount",
+      "status.privacyStatus"
+    ])
+  })
+
+  test("playlist list", () => {
+    expect(playlistListColumns).toEqual([
+      "id",
+      "snippet.title",
+      "contentDetails.itemCount",
+      "status.privacyStatus"
+    ])
+  })
+
+  test("playlist items", () => {
+    expect(playlistItemsColumns).toEqual([
+      "snippet.position",
+      "contentDetails.videoId",
+      "snippet.title",
+      "snippet.videoOwnerChannelTitle"
+    ])
+  })
+
+  test("comment get and comment replies share one list", () => {
+    expect(commentColumns).toEqual([
+      "id",
+      "snippet.authorDisplayName",
+      "snippet.textDisplay",
+      "snippet.likeCount",
+      "snippet.publishedAt"
+    ])
+  })
+
+  test("comment threads", () => {
+    expect(commentThreadsColumns).toEqual([
+      "id",
+      "snippet.topLevelComment.snippet.authorDisplayName",
+      "snippet.topLevelComment.snippet.textDisplay",
+      "snippet.totalReplyCount"
+    ])
+  })
+
+  test("subscription list", () => {
+    expect(subscriptionListColumns).toEqual([
+      "id",
+      "snippet.resourceId.channelId",
+      "snippet.title",
+      "contentDetails.totalItemCount"
+    ])
+  })
+
+  test("category list", () => {
+    expect(categoryListColumns).toEqual(["id", "snippet.title", "snippet.assignable"])
+  })
+
+  test("language list", () => {
+    expect(languageListColumns).toEqual(["id", "snippet.name"])
+  })
+
+  test("region list", () => {
+    expect(regionListColumns).toEqual(["id", "snippet.name", "snippet.glName"])
+  })
+
+  test("live-chat list and stream", () => {
+    expect(liveChatColumns).toEqual([
+      "snippet.publishedAt",
+      "authorDetails.displayName",
+      "snippet.displayMessage",
+      "snippet.type",
+      "id"
+    ])
+  })
+
+  test("analytics report is dimensions then metrics", () => {
+    expect(analyticsReportColumns(["day"], ["views", "likes"])).toEqual(["day", "views", "likes"])
+    expect(analyticsReportColumns([], ["views"])).toEqual(["views"])
+  })
+
+  test("analytics overview without --by", () => {
+    expect(analyticsOverviewColumns("")).toEqual([
+      "views",
+      "estimatedMinutesWatched",
+      "averageViewDuration",
+      "averageViewPercentage",
+      "subscribersGained"
+    ])
+  })
+
+  test("analytics overview with --by prepends the dimension", () => {
+    expect(analyticsOverviewColumns("day")).toEqual(["day", ...analyticsOverviewMetrics])
+  })
+
+  test("analytics overview treats a whitespace --by as unset (csvValues trims)", () => {
+    expect(analyticsOverviewColumns("  ")).toEqual([...analyticsOverviewMetrics])
+  })
+
+  test("analytics video", () => {
+    expect(analyticsVideoColumns).toEqual([
+      "views",
+      "estimatedMinutesWatched",
+      "averageViewDuration",
+      "likes",
+      "comments",
+      "subscribersGained"
+    ])
+  })
+
+  test("analytics traffic-sources", () => {
+    expect(analyticsTrafficSourcesColumns).toEqual([
+      "insightTrafficSourceType",
+      "views",
+      "estimatedMinutesWatched"
+    ])
+  })
+
+  test("analytics demographics", () => {
+    expect(analyticsDemographicsColumns).toEqual(["ageGroup", "gender", "viewerPercentage"])
+  })
+
+  test("status without --check", () => {
+    expect(statusColumns).toEqual([
+      "path",
+      "api_key.configured",
+      "api_key.source",
+      "api_key.fingerprint",
+      "oauth.configured",
+      "oauth.client_id",
+      "oauth.scopes",
+      "oauth.expiry"
+    ])
+  })
+
+  test("status --check adds api_key.valid and oauth.valid in place", () => {
+    expect(statusCheckColumns).toEqual([
+      "path",
+      "api_key.configured",
+      "api_key.source",
+      "api_key.fingerprint",
+      "api_key.valid",
+      "oauth.configured",
+      "oauth.client_id",
+      "oauth.scopes",
+      "oauth.expiry",
+      "oauth.valid"
+    ])
+  })
+
+  test("version", () => {
+    expect(versionColumns).toEqual(["version", "commit", "date", "goVersion", "os", "arch"])
+  })
+
+  test("update uses the renamed asset/executable keys", () => {
+    expect(updateColumns).toEqual([
+      "currentVersion",
+      "targetVersion",
+      "updated",
+      "upToDate",
+      "asset",
+      "executable"
+    ])
+  })
+})
diff --git a/src/output/columns.ts b/src/output/columns.ts
index ca14f9a..a4e23e4 100644
--- a/src/output/columns.ts
+++ b/src/output/columns.ts
@@ -1,2 +1,416 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Column resolution and cell rendering — the shared row generator behind both
+ * `table` and `tsv`.
+ *
+ * Ports `pathValue`, `cell`, and `clean` from `internal/output/output.go`, plus
+ * the per-command default column lists that live in `internal/cli/*.go`.
+ */
+
+import { compareUtf8, runeLength } from "../util/gostring.ts"
+import { isJsonArray, isJsonObject, isRawNumber } from "../json/value.ts"
+import type { JsonObject, JsonValue } from "../json/value.ts"
+
+/**
+ * `renderRows`'s fallback when the caller supplies no columns at all.
+ * Every command supplies defaults in practice, but `RenderObject` callers and
+ * `live-chat stream` route through the same code path.
+ */
+export const fallbackColumns: ReadonlyArray = ["id", "snippet.title"]
+
+/** `columns` if non-empty, else the command default, else the global fallback. */
+export const resolveColumns = (
+  requested: ReadonlyArray,
+  defaults: ReadonlyArray
+): ReadonlyArray => {
+  const chosen = requested.length > 0 ? requested : defaults
+  return chosen.length > 0 ? chosen : fallbackColumns
+}
+
+/**
+ * The 27 runes where Go's SIMPLE uppercase is one rune but JS's FULL uppercase
+ * expands to several, so the "length-changing means leave it alone" rule below
+ * would wrongly leave them unchanged.
+ *
+ * All of them are the Greek ypogegrammeni (iota-subscript) letters: Go maps
+ * each to its precomposed *prosgegrammeni* capital (U+1F80 "ᾀ" -> U+1F88 "ᾈ"),
+ * while JS decomposes to a capital plus a separate U+0399 ("ἈΙ", 2 runes).
+ * Enumerated by diffing `strings.ToUpper` over every rune in Go 1.26.5 against
+ * this function; these were the only disagreements of this kind.
+ *
+ * Encoded as [start, end, delta] runs rather than 27 entries: 0x1F80-0x1F87,
+ * 0x1F90-0x1F97 and 0x1FA0-0x1FA7 shift by +8; the three standalone
+ * 0x1FB3/0x1FC3/0x1FF3 shift by +9.
+ */
+const IOTA_SUBSCRIPT_UPPER: ReadonlyArray = [
+  [0x1f80, 0x1f87, 8],
+  [0x1f90, 0x1f97, 8],
+  [0x1fa0, 0x1fa7, 8],
+  [0x1fb3, 0x1fb3, 9],
+  [0x1fc3, 0x1fc3, 9],
+  [0x1ff3, 0x1ff3, 9]
+]
+
+const simpleUpperException = (codePoint: number): string | undefined => {
+  for (const [start, end, delta] of IOTA_SUBSCRIPT_UPPER) {
+    if (codePoint >= start && codePoint <= end) return String.fromCodePoint(codePoint + delta)
+  }
+  return undefined
+}
+
+/**
+ * `strings.ToUpper` — per-rune, locale-independent, and NEVER length-changing.
+ *
+ * Go's ToUpper applies the Unicode SIMPLE uppercase mapping, which is a
+ * 1-rune -> 1-rune function. JS `toUpperCase()` applies the FULL mapping, which
+ * expands some runes ("ß" -> "SS", "fi" -> "FI"). Verified against the Go
+ * implementation: ToUpper("straße") == "STRAßE" and ToUpper("file") == "fiLE", so
+ * any rune whose uppercase is longer than one rune is left unchanged — EXCEPT
+ * for the iota-subscript runes above, where Go does have a 1-rune mapping.
+ *
+ * "ı" (U+0131) -> "I" and "dz" (U+01F3) -> "DZ" (U+01F1, the *upper* not the
+ * title form) both round-trip correctly through this rule.
+ *
+ * Checked exhaustively against Go 1.26.5 over all 1,112,064 scalar values; the
+ * only remaining differences are runes cased in Unicode 15.1 (Bun's ICU) but
+ * not in Unicode 15.0 (Go's table), e.g. U+019B and the Garay/Kirat Rai blocks.
+ * That is a data-version gap, not a rule difference, and it resolves itself as
+ * Go's tables update.
+ */
+export const goUpper = (s: string): string => {
+  let out = ""
+  for (const ch of s) {
+    const upper = ch.toUpperCase()
+    if (runeLength(upper) === 1) {
+      out += upper
+      continue
+    }
+    out += simpleUpperException(ch.codePointAt(0) ?? 0) ?? ch
+  }
+  return out
+}
+
+/** Header text for one column: the ENTIRE dotted path, uppercased. */
+export const headerCell = (column: string): string => goUpper(column)
+
+/**
+ * Walk a dotted path. Returns `null` when any intermediate value is not an
+ * object — indistinguishable from an explicit JSON `null` or a missing key,
+ * exactly as in Go (all three collapse to `nil`).
+ *
+ * There is no escaping for literal dots in keys: a key containing a dot is
+ * unreachable through `--columns`.
+ */
+export const pathValue = (item: JsonObject, path: string): JsonValue => {
+  let value: JsonValue = item
+  for (const segment of path.split(".")) {
+    if (!isJsonObject(value)) return null
+    value = value[segment] ?? null
+  }
+  return value
+}
+
+/**
+ * Go's `strings.NewReplacer("\t", " ", "\r", " ", "\n", " ")`.
+ *
+ * Note what is NOT replaced: `\v` (U+000B) and `\f` (U+000C) survive, and both
+ * are cell/line terminators for text/tabwriter. `table.ts` reproduces that.
+ */
+export const clean = (value: string): string => value.replace(/[\t\r\n]/g, " ")
+
+/**
+ * Render one value as flat text.
+ *
+ *   null/missing -> ""            (indistinguishable from an empty string)
+ *   string       -> clean()       (tab, CR, LF each become one space)
+ *   number       -> the ORIGINAL literal text (`1.50` stays `1.50`)
+ *   bool         -> "true"/"false"
+ *   array        -> elements joined with "," (no brackets, no quoting)
+ *   object       -> keys sorted, "k=v" joined with "," (no braces)
+ */
+export const cell = (value: JsonValue): string => {
+  if (value === null) return ""
+  if (typeof value === "string") return clean(value)
+  if (typeof value === "boolean") return value ? "true" : "false"
+  if (isRawNumber(value)) return value.$rawNumber
+  if (isJsonArray(value)) return value.map(cell).join(",")
+  if (isJsonObject(value)) {
+    return Object.keys(value)
+      .sort(compareUtf8)
+      .map((key) => `${key}=${cell(value[key] ?? null)}`)
+      .join(",")
+  }
+  return ""
+}
+
+/** One rendered row: `cell(pathValue(item, column))` for each column. */
+export const rowCells = (
+  item: JsonObject,
+  columns: ReadonlyArray
+): ReadonlyArray => columns.map((column) => cell(pathValue(item, column)))
+
+/** The header row. */
+export const headerRow = (columns: ReadonlyArray): ReadonlyArray =>
+  columns.map(headerCell)
+
+/**
+ * Every row that will be emitted, header included when not suppressed. Shared
+ * verbatim by `table.ts` and `tsv.ts` — Go's `renderRows` generates the rows
+ * once and only the writer differs.
+ */
+export const generateRows = (
+  items: ReadonlyArray,
+  columns: ReadonlyArray,
+  noHeader: boolean
+): ReadonlyArray> => {
+  const rows: Array> = []
+  if (!noHeader) rows.push(headerRow(columns))
+  for (const item of items) rows.push(rowCells(item, columns))
+  return rows
+}
+
+// ---------------------------------------------------------------------------
+// Default column sets
+//
+// Transcribed from the Go call sites, NOT from the spec table, and cross-checked
+// with `grep -rn 'columns' internal/cli/`. Each comment names the Go file:line.
+// ---------------------------------------------------------------------------
+
+/** `search` — app.go:186 */
+export const searchColumns: ReadonlyArray = [
+  "id.kind",
+  "id.videoId",
+  "id.channelId",
+  "id.playlistId",
+  "snippet.title"
+]
+
+/** `channel get` — channel_video.go:61 */
+export const channelGetColumns: ReadonlyArray = [
+  "id",
+  "snippet.title",
+  "statistics.subscriberCount",
+  "statistics.videoCount",
+  "statistics.viewCount"
+]
+
+/** `channel activities` — channel_video.go:98 */
+export const channelActivitiesColumns: ReadonlyArray = [
+  "id",
+  "snippet.publishedAt",
+  "snippet.type",
+  "snippet.title"
+]
+
+/** `channel sections` — channel_video.go:140 */
+export const channelSectionsColumns: ReadonlyArray = [
+  "id",
+  "snippet.type",
+  "snippet.position",
+  "snippet.title"
+]
+
+/** `channel uploads` — channel_video.go:183 */
+export const channelUploadsColumns: ReadonlyArray = [
+  "snippet.position",
+  "contentDetails.videoId",
+  "snippet.title",
+  "snippet.publishedAt"
+]
+
+/** `video get` — channel_video.go:200 */
+export const videoGetColumns: ReadonlyArray = [
+  "id",
+  "snippet.title",
+  "snippet.channelTitle",
+  "contentDetails.duration",
+  "statistics.viewCount"
+]
+
+/** `video stats` — channel_video.go:203 */
+export const videoStatsColumns: ReadonlyArray = [
+  "id",
+  "statistics.viewCount",
+  "statistics.likeCount",
+  "statistics.commentCount"
+]
+
+/** `video popular` — channel_video.go:252 */
+export const videoPopularColumns: ReadonlyArray = [
+  "id",
+  "snippet.title",
+  "snippet.channelTitle",
+  "statistics.viewCount"
+]
+
+/** `video trainability` — channel_video.go:273 */
+export const videoTrainabilityColumns: ReadonlyArray = ["videoId", "permitted"]
+
+/** `playlist get` — resources.go:43 */
+export const playlistGetColumns: ReadonlyArray = [
+  "id",
+  "snippet.title",
+  "snippet.channelTitle",
+  "contentDetails.itemCount",
+  "status.privacyStatus"
+]
+
+/** `playlist list` — resources.go:62 */
+export const playlistListColumns: ReadonlyArray = [
+  "id",
+  "snippet.title",
+  "contentDetails.itemCount",
+  "status.privacyStatus"
+]
+
+/** `playlist items` — resources.go:80 */
+export const playlistItemsColumns: ReadonlyArray = [
+  "snippet.position",
+  "contentDetails.videoId",
+  "snippet.title",
+  "snippet.videoOwnerChannelTitle"
+]
+
+/** `comment get` and `comment replies` — resources.go:195 (`commentColumns()`) */
+export const commentColumns: ReadonlyArray = [
+  "id",
+  "snippet.authorDisplayName",
+  "snippet.textDisplay",
+  "snippet.likeCount",
+  "snippet.publishedAt"
+]
+
+/** `comment threads` — resources.go:180 */
+export const commentThreadsColumns: ReadonlyArray = [
+  "id",
+  "snippet.topLevelComment.snippet.authorDisplayName",
+  "snippet.topLevelComment.snippet.textDisplay",
+  "snippet.totalReplyCount"
+]
+
+/** `subscription list` — resources.go:225 */
+export const subscriptionListColumns: ReadonlyArray = [
+  "id",
+  "snippet.resourceId.channelId",
+  "snippet.title",
+  "contentDetails.totalItemCount"
+]
+
+/** `category list` — resources.go:249 */
+export const categoryListColumns: ReadonlyArray = [
+  "id",
+  "snippet.title",
+  "snippet.assignable"
+]
+
+/** `language list` — resources.go:267 */
+export const languageListColumns: ReadonlyArray = ["id", "snippet.name"]
+
+/** `region list` — resources.go:283 */
+export const regionListColumns: ReadonlyArray = ["id", "snippet.name", "snippet.glName"]
+
+/** `live-chat list` and `live-chat stream` — live_chat.go:201 */
+export const liveChatColumns: ReadonlyArray = [
+  "snippet.publishedAt",
+  "authorDetails.displayName",
+  "snippet.displayMessage",
+  "snippet.type",
+  "id"
+]
+
+/**
+ * `analytics report` — analytics.go:53. Dimensions first (in the order given),
+ * then metrics. Both lists come from `csvValues`, which trims and drops empties.
+ */
+export const analyticsReportColumns = (
+  dimensions: ReadonlyArray,
+  metrics: ReadonlyArray
+): ReadonlyArray => [...dimensions, ...metrics]
+
+/** `analytics overview` metrics — analytics.go:66 */
+export const analyticsOverviewMetrics: ReadonlyArray = [
+  "views",
+  "estimatedMinutesWatched",
+  "averageViewDuration",
+  "averageViewPercentage",
+  "subscribersGained"
+]
+
+/**
+ * `analytics overview` — `[--by if set]` then the metrics (analytics.go:76).
+ * `--by` goes through `csvValues`, so a blank or whitespace-only value
+ * contributes no dimension at all.
+ */
+export const analyticsOverviewColumns = (by: string): ReadonlyArray => {
+  const dimension = by.trim()
+  return dimension === "" ? analyticsOverviewMetrics : [dimension, ...analyticsOverviewMetrics]
+}
+
+/** `analytics video` — analytics.go:85 (metrics only, no dimensions). */
+export const analyticsVideoColumns: ReadonlyArray = [
+  "views",
+  "estimatedMinutesWatched",
+  "averageViewDuration",
+  "likes",
+  "comments",
+  "subscribersGained"
+]
+
+/** `analytics traffic-sources` — analytics.go:99-100 */
+export const analyticsTrafficSourcesColumns: ReadonlyArray = [
+  "insightTrafficSourceType",
+  "views",
+  "estimatedMinutesWatched"
+]
+
+/** `analytics demographics` — analytics.go:115-116 */
+export const analyticsDemographicsColumns: ReadonlyArray = [
+  "ageGroup",
+  "gender",
+  "viewerPercentage"
+]
+
+/** `status` without `--check`, non-table formats only — auth.go:169 */
+export const statusColumns: ReadonlyArray = [
+  "path",
+  "api_key.configured",
+  "api_key.source",
+  "api_key.fingerprint",
+  "oauth.configured",
+  "oauth.client_id",
+  "oauth.scopes",
+  "oauth.expiry"
+]
+
+/** `status --check`, non-table formats only — auth.go:171 */
+export const statusCheckColumns: ReadonlyArray = [
+  "path",
+  "api_key.configured",
+  "api_key.source",
+  "api_key.fingerprint",
+  "api_key.valid",
+  "oauth.configured",
+  "oauth.client_id",
+  "oauth.scopes",
+  "oauth.expiry",
+  "oauth.valid"
+]
+
+/** `version`, non-table formats only — version_update.go:31 */
+export const versionColumns: ReadonlyArray = [
+  "version",
+  "commit",
+  "date",
+  "goVersion",
+  "os",
+  "arch"
+]
+
+/** `update`, non-table formats only — version_update.go:71 */
+export const updateColumns: ReadonlyArray = [
+  "currentVersion",
+  "targetVersion",
+  "updated",
+  "upToDate",
+  "asset",
+  "executable"
+]
diff --git a/src/output/jsonOut.test.ts b/src/output/jsonOut.test.ts
new file mode 100644
index 0000000..7dbd2f3
--- /dev/null
+++ b/src/output/jsonOut.test.ts
@@ -0,0 +1,192 @@
+/**
+ * Goldens captured from `internal/output/output.go` (Go's `json.Encoder` with
+ * `SetEscapeHTML(false)` and `SetIndent("", "  ")`) on the same inputs, plus a
+ * direct capture from the real `oytc version --format json` binary.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Result } from "effect"
+import type { ListResult } from "../domain/listResult.ts"
+import { parseJson } from "../json/parse.ts"
+import type { JsonObject } from "../json/value.ts"
+import { renderJson, renderJsonl, renderObjectJson, renderObjectJsonl } from "./jsonOut.ts"
+
+const obj = (text: string): JsonObject => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as JsonObject
+}
+
+const items = (text: string): ReadonlyArray => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as ReadonlyArray
+}
+
+const result = (
+  itemsText: string,
+  nextPageToken = "",
+  requests = 0
+): ListResult => ({ items: items(itemsText), nextPageToken, requests })
+
+describe("json envelope", () => {
+  test("empty result: items is [] and requests is present at 0", () => {
+    expect(renderJson(result("[]", "", 1))).toBe('{\n  "items": [],\n  "requests": 1\n}\n')
+  })
+
+  test("nextPageToken is omitted when empty and ordered between items and requests", () => {
+    expect(renderJson(result('[{"id":"a"}]', "CAoQAA", 3))).toBe(
+      '{\n  "items": [\n    {\n      "id": "a"\n    }\n  ],\n  "nextPageToken": "CAoQAA",\n  "requests": 3\n}\n'
+    )
+  })
+
+  test("envelope keys use struct order, not alphabetical", () => {
+    const out = renderJson(result('[{"id":"a"}]', "T", 2))
+    expect(out.indexOf('"items"')).toBeLessThan(out.indexOf('"nextPageToken"'))
+    expect(out.indexOf('"nextPageToken"')).toBeLessThan(out.indexOf('"requests"'))
+  })
+
+  test("nested item keys ARE sorted alphabetically at every depth", () => {
+    expect(renderJson(result('[{"z":{"y":"1","a":"2"},"a":"x"}]'))).toBe(
+      '{\n  "items": [\n    {\n      "a": "x",\n      "z": {\n        "a": "2",\n        "y": "1"\n      }\n    }\n  ],\n  "requests": 0\n}\n'
+    )
+  })
+
+  test("large counters keep their exact text (Go's TestJSONPreservesLargeCounterString)", () => {
+    const out = renderJson(result('[{"id":"v","statistics":{"viewCount":"900719925474099312345"}}]', "", 1))
+    expect(out).toContain('"viewCount": "900719925474099312345"')
+  })
+
+  test("numeric literals are not reformatted", () => {
+    expect(renderJson(result('[{"a":1.50,"b":1e3,"c":900719925474099312345}]'))).toContain(
+      '"a": 1.50'
+    )
+    expect(renderJson(result('[{"b":1e3}]'))).toContain('"b": 1e3')
+  })
+
+  test("SetEscapeHTML(false): < > & are literal", () => {
+    expect(renderJson(result('[{"t":"& x"}]'))).toBe(
+      '{\n  "items": [\n    {\n      "t": "& x"\n    }\n  ],\n  "requests": 0\n}\n'
+    )
+  })
+
+  test("U+2028 and U+2029 are always escaped", () => {
+    expect(renderJson(result('[{"t":"a\\u2028b\\u2029c"}]'))).toContain('"a\\u2028b\\u2029c"')
+  })
+
+  test("control characters use Go's short escapes for \\b and \\f", () => {
+    expect(renderJson(result('[{"t":"a\\bb\\fc\\u0001d"}]'))).toContain('"a\\bb\\fc\\u0001d"')
+  })
+
+  test("two-space indent throughout", () => {
+    expect(renderJson(result('[{"a":{"b":"c"}}]'))).toBe(
+      '{\n  "items": [\n    {\n      "a": {\n        "b": "c"\n      }\n    }\n  ],\n  "requests": 0\n}\n'
+    )
+  })
+
+  test("always ends in exactly one newline", () => {
+    const out = renderJson(result("[]"))
+    expect(out.endsWith("}\n")).toBe(true)
+    expect(out.endsWith("}\n\n")).toBe(false)
+  })
+
+  test("--no-header is irrelevant to json (it never reads the flag)", () => {
+    expect(renderJson(result('[{"id":"a"}]'))).toBe(renderJson(result('[{"id":"a"}]')))
+  })
+})
+
+describe("jsonl", () => {
+  test("one compact object per line", () => {
+    expect(renderJsonl(result('[{"id":"a","z":"1"},{"id":"b"}]'))).toBe(
+      '{"id":"a","z":"1"}\n{"id":"b"}\n'
+    )
+  })
+
+  test("an empty result produces ZERO BYTES, not an empty line", () => {
+    expect(renderJsonl(result("[]"))).toBe("")
+    expect(renderJsonl(result("[]")).length).toBe(0)
+  })
+
+  test("no envelope: nextPageToken and requests are dropped", () => {
+    const out = renderJsonl(result('[{"id":"a"}]', "CAoQAA", 7))
+    expect(out).toBe('{"id":"a"}\n')
+    expect(out).not.toContain("nextPageToken")
+    expect(out).not.toContain("requests")
+  })
+
+  test("keys are still sorted within each line", () => {
+    expect(renderJsonl(result('[{"z":"1","a":"2"}]'))).toBe('{"a":"2","z":"1"}\n')
+  })
+
+  test("no spaces after colons or commas", () => {
+    expect(renderJsonl(result('[{"a":"1","b":"2"}]'))).toBe('{"a":"1","b":"2"}\n')
+  })
+})
+
+describe("renderObject — no list envelope", () => {
+  test("json: a bare indented object with a trailing newline", () => {
+    expect(renderObjectJson(obj('{"version":"1.2.3","commit":"abc","os":"darwin"}'))).toBe(
+      '{\n  "commit": "abc",\n  "os": "darwin",\n  "version": "1.2.3"\n}\n'
+    )
+  })
+
+  test("json: never wraps in items/requests", () => {
+    const out = renderObjectJson(obj('{"version":"1.2.3"}'))
+    expect(out).not.toContain('"items"')
+    expect(out).not.toContain('"requests"')
+  })
+
+  test("jsonl: the same object, compact, one line", () => {
+    expect(renderObjectJsonl(obj('{"version":"1.2.3","commit":"abc"}'))).toBe(
+      '{"commit":"abc","version":"1.2.3"}\n'
+    )
+  })
+
+  test("an empty object still emits {} and a newline (unlike an empty item list)", () => {
+    expect(renderObjectJson(obj("{}"))).toBe("{}\n")
+    expect(renderObjectJsonl(obj("{}"))).toBe("{}\n")
+  })
+
+  test("nested objects are indented and sorted", () => {
+    expect(renderObjectJson(obj('{"oauth":{"scopes":["a","b"],"configured":false},"path":"/x"}'))).toBe(
+      '{\n  "oauth": {\n    "configured": false,\n    "scopes": [\n      "a",\n      "b"\n    ]\n  },\n  "path": "/x"\n}\n'
+    )
+  })
+})
+
+describe("release CI grep contract", () => {
+  // .depot/workflows/release.yml runs, verbatim:
+  //
+  //   /tmp/oytc version --format json | grep -q '"version": ""'
+  //
+  // — colon, ONE space, quote. A regression in the pretty-printer's key/value
+  // separator would silently fail the release with no other symptom, so these
+  // assertions are about raw bytes, not parsed shape.
+  const versionState = obj(
+    '{"version":"0.4.1","commit":"none","date":"unknown","goVersion":"go1.26.5","os":"darwin","arch":"arm64"}'
+  )
+
+  test('pretty JSON contains the literal `"version": "`', () => {
+    expect(renderObjectJson(versionState)).toContain('"version": "')
+  })
+
+  test("the exact release grep pattern matches, tag included", () => {
+    const tagged = obj('{"version":"v1.2.3","commit":"abc","os":"darwin"}')
+    expect(renderObjectJson(tagged)).toContain('"version": "v1.2.3"')
+  })
+
+  test("the full version payload matches the Go binary byte-for-byte", () => {
+    expect(renderObjectJson(versionState)).toBe(
+      '{\n  "arch": "arm64",\n  "commit": "none",\n  "date": "unknown",\n  "goVersion": "go1.26.5",\n  "os": "darwin",\n  "version": "0.4.1"\n}\n'
+    )
+  })
+
+  test("the JSONL form does NOT have the space (it is compact) — grep must target json", () => {
+    expect(renderObjectJsonl(versionState)).toContain('"version":"')
+    expect(renderObjectJsonl(versionState)).not.toContain('"version": "')
+  })
+
+  test("a version inside a list envelope keeps the space too", () => {
+    expect(renderJson(result('[{"version":"0.4.1"}]'))).toContain('"version": "')
+  })
+})
diff --git a/src/output/jsonOut.ts b/src/output/jsonOut.ts
index ca14f9a..458aadc 100644
--- a/src/output/jsonOut.ts
+++ b/src/output/jsonOut.ts
@@ -1,2 +1,34 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * The two JSON output shapes.
+ *
+ * `json` emits the full `ListResult` envelope: struct-ordered keys, 2-space
+ * indent, trailing newline. `jsonl` emits one compact object per line with NO
+ * envelope — `nextPageToken` and `requests` are lost, and an empty result set
+ * produces ZERO bytes rather than an empty line.
+ *
+ * `renderObject*` are the `RenderObject` path (`video trainability`, `status`,
+ * `version`, `update`): a bare object, no envelope, same indentation rules.
+ *
+ * All four go through `json/encode.ts` so that Go's escaping and key ordering
+ * are preserved; the stdlib JSON serializer is banned outside that file (CI
+ * enforces it with a text grep, so it must not appear even in a comment).
+ */
+
+import { encodeGoValue } from "../json/encode.ts"
+import { encodeListResultJson, encodeListResultJsonl } from "../domain/listResult.ts"
+import type { ListResult } from "../domain/listResult.ts"
+import type { JsonObject } from "../json/value.ts"
+
+/** `--format json` for a list result. */
+export const renderJson = (result: ListResult): string => encodeListResultJson(result)
+
+/** `--format jsonl` for a list result; "" when there are no items. */
+export const renderJsonl = (result: ListResult): string => encodeListResultJsonl(result)
+
+/** `RenderObject` with `--format json`: indented, trailing newline. */
+export const renderObjectJson = (object: JsonObject): string =>
+  `${encodeGoValue(object, { indent: "  " })}\n`
+
+/** `RenderObject` with `--format jsonl`: compact, one line, trailing newline. */
+export const renderObjectJsonl = (object: JsonObject): string =>
+  `${encodeGoValue(object, { indent: "" })}\n`
diff --git a/src/output/table.test.ts b/src/output/table.test.ts
new file mode 100644
index 0000000..5b19314
--- /dev/null
+++ b/src/output/table.test.ts
@@ -0,0 +1,253 @@
+/**
+ * Every `want` in this file is a byte-for-byte capture from Go's
+ * `text/tabwriter` at `NewWriter(w, 0, 4, 2, ' ', 0)`, taken by running the
+ * real `internal/output/output.go` (and, for `tabwrite`, tabwriter directly)
+ * over the same input. They are literals so the suite keeps its value after the
+ * Go source is deleted.
+ *
+ * A 5000-case randomized differential run against the Go implementation — mixed
+ * ASCII, CJK, astral emoji, combining marks, U+FFFD, tabs, vertical tabs and
+ * form feeds — matched 5000/5000. The cases below are the ones worth naming.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Result } from "effect"
+import { parseJson } from "../json/parse.ts"
+import type { JsonObject } from "../json/value.ts"
+import { generateRows } from "./columns.ts"
+import { renderTable, tabwrite } from "./table.ts"
+
+const items = (text: string): ReadonlyArray => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as ReadonlyArray
+}
+
+const table = (
+  itemsText: string,
+  columns: ReadonlyArray,
+  noHeader = false
+): string => renderTable(generateRows(items(itemsText), columns, noHeader))
+
+describe("basic alignment", () => {
+  test("columns pad to the widest cell plus 2", () => {
+    expect(table('[{"id":"v","snippet":{"title":"hello"}},{"id":"longerid","snippet":{"title":"x"}}]', ["id", "snippet.title"])).toBe(
+      "ID        SNIPPET.TITLE\nv         hello\nlongerid  x\n"
+    )
+  })
+
+  test("the header can be the widest cell in its column", () => {
+    expect(table('[{"statistics":{"subscriberCount":"1"},"id":"x"}]', ["statistics.subscriberCount", "id"])).toBe(
+      "STATISTICS.SUBSCRIBERCOUNT  ID\n1                           x\n"
+    )
+  })
+
+  test("three columns with mixed widths", () => {
+    expect(
+      table('[{"a":"a","b":"bbbbbbb","c":"c"},{"a":"aaaaaaaa","b":"b","c":"cccc"}]', ["a", "b", "c"])
+    ).toBe("A         B        C\na         bbbbbbb  c\naaaaaaaa  b        cccc\n")
+  })
+
+  test("numbers are LEFT aligned like everything else", () => {
+    expect(table('[{"n":1.50,"b":true},{"n":900719925474099312345,"b":false}]', ["n", "b"])).toBe(
+      "N                      B\n1.50                   true\n900719925474099312345  false\n"
+    )
+  })
+
+  test("no borders, rules, or box characters anywhere", () => {
+    const out = table('[{"a":"x","b":"y"}]', ["a", "b"])
+    expect(out).not.toMatch(/[|+\-─│┌┐└┘═╔]/)
+  })
+
+  test("long cells are never truncated and no width cap applies", () => {
+    // Built by concatenation: the stdlib JSON serializer is confined to
+    // src/json/encode.ts by a CI text grep, which doc comments trip too.
+    const long = "x".repeat(500)
+    expect(table(`[{"a":"${long}","b":"y"}]`, ["a", "b"])).toBe(
+      `A${" ".repeat(501)}B\n${long}  y\n`
+    )
+  })
+})
+
+describe("trailing whitespace — SPEC_CLI §3.4 is WRONG about this", () => {
+  // The spec asserts "Every line therefore has no trailing whitespace."
+  // The Go implementation disagrees: the LAST cell of a line is unpadded, but
+  // when that last cell is EMPTY the preceding column is still padded, so the
+  // line ends in real spaces. Verified against the Go binary.
+  test("an empty last cell leaves the previous column's padding exposed", () => {
+    expect(table('[{"a":"xxxx"},{"a":"y","b":"bb"}]', ["a", "b"])).toBe("A     B\nxxxx  \ny     bb\n")
+  })
+
+  test("every row having an empty last cell still pads", () => {
+    expect(table('[{"a":"aaaa"},{"a":"b"}]', ["a", "b"])).toBe("A     B\naaaa  \nb     \n")
+  })
+
+  test("holds with --no-header too", () => {
+    expect(table('[{"a":"aaaa"}]', ["a", "b"], true)).toBe("aaaa  \n")
+  })
+
+  test("an entirely blank row is a run of spaces, not an empty line", () => {
+    expect(table('[{},{"a":"aa","c":"cc"}]', ["a", "b", "c"])).toBe("A   B  C\n       \naa     cc\n")
+  })
+
+  test("a populated last cell yields no trailing whitespace", () => {
+    expect(table('[{"a":"x","b":"y"}]', ["a", "b"])).toBe("A  B\nx  y\n")
+  })
+})
+
+describe("rune widths — misalignment on wide glyphs is intentional", () => {
+  test("CJK counts 1 per rune, so it visually overflows", () => {
+    expect(table('[{"id":"a","t":"日本語のタイトル"},{"id":"bb","t":"short"}]', ["id", "t"])).toBe(
+      "ID  T\na   日本語のタイトル\nbb  short\n"
+    )
+  })
+
+  test("an emoji in the first column pads by CODE POINTS, not UTF-16 units", () => {
+    // "🎬🎬" is 2 code points but 4 UTF-16 units. Go pads to width 2+2=4, so it
+    // emits 2 spaces. A `.length`-based port would emit 0 and lose a column.
+    expect(table('[{"id":"🎬🎬","t":"a"},{"id":"xy","t":"b"}]', ["id", "t"])).toBe(
+      "ID  T\n🎬🎬  a\nxy  b\n"
+    )
+  })
+
+  test("astral CJK Extension B also counts 1 per code point", () => {
+    expect(table('[{"a":"\\ud840\\udc00\\ud840\\udc01","b":"1"},{"a":"abcde","b":"2"}]', ["a", "b"])).toBe(
+      "A      B\n\u{20000}\u{20001}     1\nabcde  2\n"
+    )
+  })
+
+  test("a combining mark counts as its own rune", () => {
+    // Decomposed "e"+U+0301+"x" is 3 runes, so the column is 3+2=5 wide and
+    // only 2 spaces follow even though the grapheme cluster looks 2 wide.
+    // Escapes, not literals: an editor or formatter that NFC-normalizes this
+    // file would otherwise silently turn it into the 2-rune precomposed case.
+    expect(table(`[{"a":"e\\u0301x","b":"1"},{"a":"abc","b":"2"}]`, ["a", "b"])).toBe(
+      `A    B\ne\u0301x  1\nabc  2\n`
+    )
+  })
+
+  test("the precomposed form is one rune shorter and pads one space more", () => {
+    expect(table(`[{"a":"\\u00e9x","b":"1"},{"a":"abc","b":"2"}]`, ["a", "b"])).toBe(
+      `A    B\n\u00e9x   1\nabc  2\n`
+    )
+  })
+
+  test("U+FFFD counts 1", () => {
+    expect(table('[{"a":"\\ufffd","b":"1"},{"a":"abcd","b":"2"}]', ["a", "b"])).toBe(
+      "A     B\n�     1\nabcd  2\n"
+    )
+  })
+})
+
+describe("single-column output never aligns (ncells == 1 forces a flush)", () => {
+  test("each line is its own block, so no padding is ever emitted", () => {
+    expect(table('[{"id":"a"},{"id":"bbbbbb"}]', ["id"])).toBe("ID\na\nbbbbbb\n")
+  })
+
+  test("even with a very wide value", () => {
+    expect(table('[{"a":"short"},{"a":"muchmuchlonger"}]', ["a"])).toBe("A\nshort\nmuchmuchlonger\n")
+  })
+})
+
+describe("empty results", () => {
+  test("no items still prints the header", () => {
+    expect(table("[]", ["id", "x"])).toBe("ID  X\n")
+  })
+
+  test("no items and --no-header prints nothing at all", () => {
+    expect(table("[]", ["id", "x"], true)).toBe("")
+  })
+
+  test("header-only output for long dotted paths", () => {
+    expect(table("[]", ["contentDetails.videoId", "snippet.videoOwnerChannelTitle"])).toBe(
+      "CONTENTDETAILS.VIDEOID  SNIPPET.VIDEOOWNERCHANNELTITLE\n"
+    )
+  })
+
+  test("empty first column across all rows", () => {
+    expect(table('[{"b":"aaaa"},{"b":"b"}]', ["a", "b"])).toBe("A  B\n   aaaa\n   b\n")
+  })
+})
+
+describe("missing paths and empty cells", () => {
+  test("a broken path renders as spaces, indistinguishable from an empty value", () => {
+    expect(table('[{"a":"notobject","id":"x"}]', ["a.b.c", "id"])).toBe("A.B.C  ID\n       x\n")
+  })
+
+  test("realistic mixed table with a missing statistics object", () => {
+    expect(
+      table(
+        '[{"id":"dQw4w9WgXcQ","snippet":{"title":"Never Gonna Give You Up"},"statistics":{"viewCount":"1600000000"}},{"id":"x","snippet":{"title":"日本"},"statistics":{"viewCount":"1"}},{"id":"yy","snippet":{"title":""},"statistics":{}}]',
+        ["id", "snippet.title", "statistics.viewCount"]
+      )
+    ).toBe(
+      "ID           SNIPPET.TITLE            STATISTICS.VIEWCOUNT\n" +
+        "dQw4w9WgXcQ  Never Gonna Give You Up  1600000000\n" +
+        "x            日本                       1\n" +
+        "yy                                    \n"
+    )
+  })
+})
+
+describe("control characters inside cells", () => {
+  test("a tab is cleaned to a space before it can split a cell", () => {
+    expect(table('[{"a":"x\\ty","b":"p\\rq\\nr"},{"a":"zzzzzzzz","b":"q"}]', ["a", "b"])).toBe(
+      "A         B\nx y       p q r\nzzzzzzzz  q\n"
+    )
+  })
+
+  test("a VERTICAL TAB is NOT cleaned and splits the cell", () => {
+    // clean() replaces only \t, \r, \n — \v reaches tabwriter as a cell
+    // terminator, so this row silently gains a column.
+    expect(table('[{"a":"x\\u000by","b":"z"},{"a":"pppppp","b":"q"}]', ["a", "b"])).toBe(
+      "A       B\nx       y  z\npppppp  q\n"
+    )
+  })
+
+  test("a FORM FEED splits the cell AND forces a flush", () => {
+    // Everything after the \f gets independently computed column widths.
+    expect(table('[{"a":"x\\fy","b":"z"},{"a":"pppppp","b":"q"},{"a":"s","b":"t"}]', ["a", "b"])).toBe(
+      "A  B\nx\ny       z\npppppp  q\ns       t\n"
+    )
+  })
+
+  test("a form feed in the last row", () => {
+    expect(table('[{"a":"pppppp","b":"q"},{"a":"x\\fy","b":"z"}]', ["a", "b"])).toBe(
+      "A       B\npppppp  q\nx\ny  z\n"
+    )
+  })
+
+  test("a backspace is just a 1-rune character", () => {
+    expect(table('[{"a":"x\\by","b":"z"},{"a":"pppppp","b":"q"}]', ["a", "b"])).toBe(
+      "A       B\nx\by     z\npppppp  q\n"
+    )
+  })
+})
+
+describe("tabwrite — direct tabwriter parity", () => {
+  test("the trivial case", () => {
+    expect(tabwrite("ID\tSNIPPET.TITLE\nv\thello\nlongerid\tx\n")).toBe(
+      "ID        SNIPPET.TITLE\nv         hello\nlongerid  x\n"
+    )
+  })
+
+  test("empty input produces empty output", () => {
+    expect(tabwrite("")).toBe("")
+  })
+
+  test("input with no trailing newline still flushes the partial line", () => {
+    expect(tabwrite("a\tb")).toBe("a  b")
+  })
+
+  test("a lone newline is one empty line", () => {
+    expect(tabwrite("\n")).toBe("\n")
+  })
+
+  test("a lone form feed flushes an empty block", () => {
+    expect(tabwrite("\f")).toBe("\n")
+  })
+
+  test("padchar is a space, so tabwidth=4 never introduces a tab", () => {
+    expect(tabwrite("a\tb\tc\nlonger\tx\ty\n")).not.toContain("\t")
+  })
+})
diff --git a/src/output/table.ts b/src/output/table.ts
index ca14f9a..b920e66 100644
--- a/src/output/table.ts
+++ b/src/output/table.ts
@@ -1,2 +1,172 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * The subset of Go's `text/tabwriter` that `oytc` actually exercises:
+ *
+ *     tabwriter.NewWriter(w, minwidth=0, tabwidth=4, padding=2, padchar=' ', flags=0)
+ *
+ * This is a direct port of the `Write`/`flush`/`format`/`writeLines` state
+ * machine from `$GOROOT/src/text/tabwriter/tabwriter.go`, not an approximation.
+ * Reimplementing the algorithm rather than "pad each column to its max width"
+ * matters because of three behaviors a naive version gets wrong, all three
+ * verified byte-for-byte against the Go implementation:
+ *
+ *   1. **Trailing whitespace DOES occur.** SPEC_CLI §3.4 claims "every line
+ *      therefore has no trailing whitespace". That is FALSE. The last cell on a
+ *      line is unpadded only because no width was pushed for its column — but a
+ *      column only counts as "last" per line, and `format` skips the final cell
+ *      of each line when computing widths. When the final cell is EMPTY, the
+ *      preceding cell still gets padded and the line ends in spaces:
+ *
+ *          columns ["a","b"], items [{a:"xxxx"},{a:"y",b:"bb"}]
+ *          => "A     B\nxxxx  \ny     bb\n"
+ *                        ^^ two real trailing spaces
+ *
+ *   2. **`\v` splits a cell and `\f` splits a cell AND forces a flush.**
+ *      `clean()` maps only tab/CR/LF to spaces, so a vertical tab or form feed
+ *      inside a title survives into the tabwriter input, where both are cell
+ *      terminators. A `\f` additionally ends the current block, so the rows
+ *      after it get INDEPENDENTLY computed column widths.
+ *
+ *   3. **A line whose cell count is 1 forces a flush too** (`ncells == 1` in
+ *      `Write`). Single-column output therefore never aligns anything — each
+ *      line is its own block. Observable: `--columns id` emits every id with no
+ *      padding at all, regardless of length differences.
+ *
+ * Widths are counted in RUNES (`utf8.RuneCount`), so double-width CJK and emoji
+ * deliberately misalign; that misalignment is part of the contract.
+ */
+
+import { runeLength } from "../util/gostring.ts"
+
+/** minwidth: a column is only as wide as its widest cell plus the padding. */
+const MIN_WIDTH = 0
+
+/** padding: added to a cell's width before it becomes the column width. */
+const PADDING = 2
+
+interface Cell {
+  readonly text: string
+  /** Width in runes (code points), not UTF-16 units and not bytes. */
+  readonly width: number
+  /** True when the cell was terminated by a horizontal tab. */
+  readonly htab: boolean
+}
+
+/**
+ * Run the tabwriter over a raw input stream — the exact byte sequence Go writes
+ * into `tabwriter.Writer` (cells joined by `\t`, lines terminated by `\n`).
+ *
+ * Exported for differential testing against the Go implementation; production
+ * callers want `renderTable`.
+ */
+export const tabwrite = (input: string): string => {
+  let out = ""
+
+  // Buffered lines; `lines[lines.length - 1]` is the line being built.
+  let lines: Array> = [[]]
+  // Text accumulated for the cell currently being built.
+  let cellText = ""
+  // The column-width stack `format` pushes onto as it descends.
+  const widths: Array = []
+
+  const writePadding = (textWidth: number, cellWidth: number): void => {
+    const n = cellWidth - textWidth
+    if (n > 0) out += " ".repeat(n)
+  }
+
+  const writeLines = (line0: number, line1: number): void => {
+    for (let i = line0; i < line1; i++) {
+      const line = lines[i]!
+      for (let j = 0; j < line.length; j++) {
+        const c = line[j]!
+        // Go branches on `c.size == 0`, but with TabIndent and AlignRight both
+        // unset the empty and non-empty branches are identical: emit the text
+        // (possibly ""), then pad if a width exists for this column.
+        out += c.text
+        if (j < widths.length) writePadding(c.width, widths[j]!)
+      }
+      if (i + 1 === lines.length) {
+        // The last buffered line has no newline; flush any incomplete cell.
+        // `flush` always terminates a non-empty cell first, so this is "".
+        out += cellText
+      } else {
+        out += "\n"
+      }
+    }
+  }
+
+  const format = (line0: number, line1: number): void => {
+    const column = widths.length
+    let start = line0
+    for (let self = start; self < line1; self++) {
+      // The final cell of a line is tab-TERMINATED text before the newline and
+      // does not belong to a column, hence `length - 1`.
+      if (column >= lines[self]!.length - 1) continue
+
+      // Print everything before this column block, then measure the block.
+      writeLines(start, self)
+      start = self
+
+      let width = MIN_WIDTH
+      for (; self < line1; self++) {
+        if (column >= lines[self]!.length - 1) break
+        const c = lines[self]![column]!
+        const w = c.width + PADDING
+        if (w > width) width = w
+      }
+      // DiscardEmptyColumns is not set, so `discardable` never zeroes `width`.
+
+      widths.push(width)
+      format(start, self)
+      widths.pop()
+      start = self
+    }
+    writeLines(start, line1)
+  }
+
+  const terminateCell = (htab: boolean): number => {
+    const line = lines[lines.length - 1]!
+    line.push({ text: cellText, width: runeLength(cellText), htab })
+    cellText = ""
+    return line.length
+  }
+
+  const flush = (): void => {
+    if (cellText.length > 0) terminateCell(false)
+    format(0, lines.length)
+    // reset()
+    lines = [[]]
+    cellText = ""
+    widths.length = 0
+  }
+
+  for (const ch of input) {
+    if (ch === "\t" || ch === "\v" || ch === "\n" || ch === "\f") {
+      const ncells = terminateCell(ch === "\t")
+      if (ch === "\n" || ch === "\f") {
+        lines.push([])
+        // A form feed always forces a flush. So does a line with exactly one
+        // cell, because the last cell of a line never affects the widths of the
+        // lines that follow it.
+        if (ch === "\f" || ncells === 1) flush()
+      }
+      continue
+    }
+    cellText += ch
+  }
+
+  flush()
+  return out
+}
+
+/**
+ * Render pre-generated rows (see `columns.generateRows`) as an aligned table.
+ *
+ * Cells are joined with `\t` and each row is terminated by `\n` — the byte
+ * stream Go builds with `fmt.Fprint`/`fmt.Fprintln` — and the whole thing is
+ * flushed once at the end.
+ */
+export const renderTable = (rows: ReadonlyArray>): string => {
+  let input = ""
+  for (const row of rows) input += `${row.join("\t")}\n`
+  return tabwrite(input)
+}
diff --git a/src/output/tsv.test.ts b/src/output/tsv.test.ts
new file mode 100644
index 0000000..2125326
--- /dev/null
+++ b/src/output/tsv.test.ts
@@ -0,0 +1,122 @@
+/**
+ * Goldens captured from `internal/output/output.go` running the same inputs.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Result } from "effect"
+import { parseJson } from "../json/parse.ts"
+import type { JsonObject } from "../json/value.ts"
+import { generateRows } from "./columns.ts"
+import { renderTsv } from "./tsv.ts"
+
+const items = (text: string): ReadonlyArray => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as ReadonlyArray
+}
+
+const tsv = (itemsText: string, columns: ReadonlyArray, noHeader = false): string =>
+  renderTsv(generateRows(items(itemsText), columns, noHeader))
+
+describe("tsv", () => {
+  test("the exact case from Go's output_test.go TestTSVColumnsAndSanitization", () => {
+    expect(tsv('[{"id":"v","snippet":{"title":"line one\\nline two"}}]', ["id", "snippet.title"])).toBe(
+      "ID\tSNIPPET.TITLE\nv\tline one line two\n"
+    )
+  })
+
+  test("fields are separated by exactly one tab, with no padding", () => {
+    expect(tsv('[{"a":"x","b":"y"},{"a":"muchlonger","b":"z"}]', ["a", "b"])).toBe(
+      "A\tB\nx\ty\nmuchlonger\tz\n"
+    )
+  })
+
+  test("no alignment even when a column is much wider than the rest", () => {
+    expect(tsv('[{"statistics":{"subscriberCount":"1"},"id":"x"}]', ["statistics.subscriberCount", "id"])).toBe(
+      "STATISTICS.SUBSCRIBERCOUNT\tID\n1\tx\n"
+    )
+  })
+
+  test("missing values become adjacent tabs", () => {
+    expect(tsv('[{"a":"notobject","id":"x"}]', ["a.b.c", "id"])).toBe("A.B.C\tID\n\tx\n")
+  })
+
+  test("an empty last column leaves a trailing tab", () => {
+    expect(tsv('[{"o":{},"a":[]}]', ["o", "a"])).toBe("O\tA\n\t\n")
+  })
+
+  test("no items still prints the header", () => {
+    expect(tsv("[]", ["id", "x"])).toBe("ID\tX\n")
+  })
+
+  test("no items and --no-header prints nothing", () => {
+    expect(tsv("[]", ["id", "x"], true)).toBe("")
+  })
+
+  test("single column has no tabs at all", () => {
+    expect(tsv('[{"id":"a"},{"id":"bbbbbb"}]', ["id"])).toBe("ID\na\nbbbbbb\n")
+  })
+
+  test("every value kind in one row", () => {
+    expect(
+      tsv(
+        '[{"s":"hi","n":900719925474099312345,"f":1.50,"b":true,"arr":[1,"a",null,{"z":1,"a":2}],"obj":{"z":"1","a":{"q":true}},"nul":null}]',
+        ["s", "n", "f", "b", "arr", "obj", "nul", "missing"]
+      )
+    ).toBe(
+      "S\tN\tF\tB\tARR\tOBJ\tNUL\tMISSING\n" +
+        "hi\t900719925474099312345\t1.50\ttrue\t1,a,,a=2,z=1\ta=q=true,z=1\t\t\n"
+    )
+  })
+
+  test("numeric literals keep their original text", () => {
+    expect(tsv('[{"a":1e3,"b":-0.0,"c":1E+10}]', ["a", "b", "c"])).toBe("A\tB\tC\n1e3\t-0.0\t1E+10\n")
+  })
+
+  test("tabs, CR and LF in a cell are cleaned so they cannot break the format", () => {
+    expect(tsv('[{"a":"x\\ty","b":"p\\rq\\nr"}]', ["a", "b"])).toBe("A\tB\nx y\tp q r\n")
+  })
+
+  test("a vertical tab is NOT cleaned and passes through literally", () => {
+    // Unlike in `table`, where \v splits the cell, TSV writes it verbatim.
+    expect(tsv('[{"a":"x\\u000by","b":"z"}]', ["a", "b"])).toBe("A\tB\nx\u000by\tz\n")
+  })
+
+  test("a form feed also passes through literally, with no flush semantics", () => {
+    expect(tsv('[{"a":"x\\fy","b":"z"}]', ["a", "b"])).toBe("A\tB\nx\fy\tz\n")
+  })
+
+  test("a deep dotted path renders one long header", () => {
+    expect(
+      tsv(
+        '[{"snippet":{"topLevelComment":{"snippet":{"authorDisplayName":"Bob"}}}}]',
+        ["snippet.topLevelComment.snippet.authorDisplayName"]
+      )
+    ).toBe("SNIPPET.TOPLEVELCOMMENT.SNIPPET.AUTHORDISPLAYNAME\nBob\n")
+  })
+
+  test("a status-shaped object row", () => {
+    expect(
+      tsv(
+        '[{"path":"/x/auth.json","api_key":{"configured":true,"source":"env","fingerprint":"ab12"},"oauth":{"configured":false,"client_id":"","scopes":["a","b"],"expiry":""}}]',
+        [
+          "path",
+          "api_key.configured",
+          "api_key.source",
+          "api_key.fingerprint",
+          "oauth.configured",
+          "oauth.client_id",
+          "oauth.scopes",
+          "oauth.expiry"
+        ]
+      )
+    ).toBe(
+      "PATH\tAPI_KEY.CONFIGURED\tAPI_KEY.SOURCE\tAPI_KEY.FINGERPRINT\tOAUTH.CONFIGURED\tOAUTH.CLIENT_ID\tOAUTH.SCOPES\tOAUTH.EXPIRY\n" +
+        "/x/auth.json\ttrue\tenv\tab12\tfalse\t\ta,b\t\n"
+    )
+  })
+
+  test("wide glyphs are irrelevant here — no widths are computed", () => {
+    expect(tsv('[{"id":"🎬🎬","t":"日本"}]', ["id", "t"])).toBe("ID\tT\n🎬🎬\t日本\n")
+  })
+})
diff --git a/src/output/tsv.ts b/src/output/tsv.ts
index ca14f9a..b2e6ebf 100644
--- a/src/output/tsv.ts
+++ b/src/output/tsv.ts
@@ -1,2 +1,15 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `--format tsv`: the same row generator as `table`, written straight to the
+ * output with no tabwriter in between.
+ *
+ * Fields are separated by a single literal `\t`, rows by `\n`, with no padding
+ * and no alignment. `clean()` has already replaced any tab inside a cell with a
+ * space, so the separator is unambiguous — but `\v` and `\f` are NOT cleaned
+ * and pass through verbatim here (unlike in `table`, where they split cells).
+ */
+
+export const renderTsv = (rows: ReadonlyArray>): string => {
+  let out = ""
+  for (const row of rows) out += `${row.join("\t")}\n`
+  return out
+}
diff --git a/src/schema/authfile.test.ts b/src/schema/authfile.test.ts
new file mode 100644
index 0000000..6560b18
--- /dev/null
+++ b/src/schema/authfile.test.ts
@@ -0,0 +1,343 @@
+import { describe, expect, test } from "bun:test"
+import { Result } from "effect"
+import { parseJson } from "../json/parse.ts"
+import type { JsonValue } from "../json/value.ts"
+import {
+  cloneOAuth,
+  decodeAuthFile,
+  encodeAuthFile,
+  sameOAuth,
+  type AuthFile,
+  type AuthOAuth
+} from "./authfile.ts"
+
+const decode = (text: string): Result.Result => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) return Result.fail({ message: parsed.failure.message })
+  return decodeAuthFile(parsed.success)
+}
+
+const ok = (text: string): AuthFile => {
+  const r = decode(text)
+  if (Result.isFailure(r)) throw new Error(`expected success, got: ${r.failure.message}`)
+  return r.success
+}
+
+const oauth = (overrides: Partial = {}): AuthOAuth => ({
+  clientId: "id",
+  clientSecret: "sec",
+  accessToken: "acc",
+  refreshToken: "ref",
+  expiry: "2026-02-01T12:00:00Z",
+  scopes: undefined,
+  ...overrides
+})
+
+describe("encodeAuthFile — byte parity with json.MarshalIndent(file, \"\", \"  \") + '\\n'", () => {
+  // Every expected string below was produced by running the real Go structs
+  // through encoding/json (Go 1.26.5) and capturing the bytes.
+
+  test("an empty file marshals to {}", () => {
+    expect(encodeAuthFile({ apiKey: "", oauth: undefined })).toBe("{}\n")
+  })
+
+  test("api_key is omitempty", () => {
+    expect(encodeAuthFile({ apiKey: "abc", oauth: undefined })).toBe('{\n  "api_key": "abc"\n}\n')
+  })
+
+  test("a nil scopes slice marshals as null, not []", () => {
+    expect(encodeAuthFile({ apiKey: "abc", oauth: oauth() })).toBe(
+      `{
+  "api_key": "abc",
+  "oauth": {
+    "client_id": "id",
+    "client_secret": "sec",
+    "access_token": "acc",
+    "refresh_token": "ref",
+    "expiry": "2026-02-01T12:00:00Z",
+    "scopes": null
+  }
+}
+`
+    )
+  })
+
+  test("an empty scopes slice marshals as [] and empty strings are still emitted", () => {
+    expect(
+      encodeAuthFile({
+        apiKey: "",
+        oauth: {
+          clientId: "id",
+          clientSecret: "sec",
+          accessToken: "",
+          refreshToken: "",
+          expiry: "",
+          scopes: []
+        }
+      })
+    ).toBe(
+      `{
+  "oauth": {
+    "client_id": "id",
+    "client_secret": "sec",
+    "access_token": "",
+    "refresh_token": "",
+    "expiry": "",
+    "scopes": []
+  }
+}
+`
+    )
+  })
+
+  test("a populated scopes array indents at 6 spaces", () => {
+    expect(
+      encodeAuthFile({
+        apiKey: "k",
+        oauth: {
+          clientId: "id",
+          clientSecret: "sec",
+          accessToken: "a",
+          refreshToken: "r",
+          expiry: "e",
+          scopes: ["scope.one", "scope.two"]
+        }
+      })
+    ).toBe(
+      `{
+  "api_key": "k",
+  "oauth": {
+    "client_id": "id",
+    "client_secret": "sec",
+    "access_token": "a",
+    "refresh_token": "r",
+    "expiry": "e",
+    "scopes": [
+      "scope.one",
+      "scope.two"
+    ]
+  }
+}
+`
+    )
+  })
+
+  test("oauth-only files omit api_key entirely", () => {
+    const text = encodeAuthFile({ apiKey: "", oauth: oauth({ scopes: ["s"] }) })
+    expect(text.includes("api_key")).toBe(false)
+    expect(text.startsWith('{\n  "oauth": {')).toBe(true)
+  })
+
+  test("key order is struct order, not alphabetical", () => {
+    const text = encodeAuthFile({ apiKey: "k", oauth: oauth({ scopes: ["s"] }) })
+    const keys = [...text.matchAll(/"([a-z_]+)":/g)].map((m) => m[1])
+    expect(keys).toEqual([
+      "api_key",
+      "oauth",
+      "client_id",
+      "client_secret",
+      "access_token",
+      "refresh_token",
+      "expiry",
+      "scopes"
+    ])
+  })
+
+  test("every encoding round-trips through the decoder", () => {
+    const cases: ReadonlyArray = [
+      { apiKey: "", oauth: undefined },
+      { apiKey: "abc", oauth: undefined },
+      { apiKey: "abc", oauth: oauth() },
+      { apiKey: "", oauth: oauth({ scopes: ["a", "b"] }) }
+    ]
+    for (const file of cases) {
+      expect(ok(encodeAuthFile(file))).toEqual(file)
+    }
+  })
+})
+
+describe("decodeAuthFile — Go encoding/json semantics", () => {
+  test("an empty object yields the zero file", () => {
+    expect(ok("{}")).toEqual({ apiKey: "", oauth: undefined })
+  })
+
+  test("unknown keys are ignored", () => {
+    expect(ok('{"unknown":1,"api_key":"z"}')).toEqual({ apiKey: "z", oauth: undefined })
+  })
+
+  test("null decodes to the zero value rather than failing", () => {
+    expect(ok('{"api_key":null}')).toEqual({ apiKey: "", oauth: undefined })
+    expect(ok('{"oauth":null}')).toEqual({ apiKey: "", oauth: undefined })
+    // Verified against Go: a top-level null is a no-op, not an error.
+    expect(ok("null")).toEqual({ apiKey: "", oauth: undefined })
+  })
+
+  test("a null scopes value is nil, an empty array is empty", () => {
+    expect(ok('{"oauth":{"client_id":"x","scopes":null}}').oauth?.scopes).toBeUndefined()
+    expect(ok('{"oauth":{"client_id":"x","scopes":[]}}').oauth?.scopes).toEqual([])
+  })
+
+  test("a null scopes element becomes an empty string, keeping the slot", () => {
+    expect(ok('{"oauth":{"scopes":["a",null]}}').oauth?.scopes).toEqual(["a", ""])
+  })
+
+  test("missing oauth fields default to empty strings", () => {
+    expect(ok('{"oauth":{"scopes":["a"],"client_id":"x"}}').oauth).toEqual({
+      clientId: "x",
+      clientSecret: "",
+      accessToken: "",
+      refreshToken: "",
+      expiry: "",
+      scopes: ["a"]
+    })
+  })
+
+  test("keys match case-insensitively when there is no exact match", () => {
+    // Verified against Go 1.26.5: encoding/json falls back to a
+    // case-insensitive field match.
+    expect(ok('{"OAUTH":{"client_id":"x"}}').oauth?.clientId).toBe("x")
+    expect(ok('{"API_KEY":"z"}').apiKey).toBe("z")
+  })
+
+  test.each([
+    // Go decodes EVERY key that resolves to a field, in document order, so the
+    // last one wins — even when an EARLIER key was the exact tag match. Every
+    // expectation below was captured from Go 1.26.5.
+    ['{"api_key":"exact","API_KEY":"upper"}', "upper"],
+    ['{"API_KEY":"upper","api_key":"exact"}', "exact"],
+    ['{"API_KEY":"first","Api_Key":"second"}', "second"],
+    ['{"Api_Key":"second","API_KEY":"first"}', "first"],
+    ['{"api_key":"a","API_KEY":"b","apI_kEy":"c"}', "c"],
+    ['{"api_key":"a","API_KEY":"","x":1}', ""],
+    // null into a non-pointer STRING field is a Go no-op, NOT a reset to "".
+    ['{"api_key":"a","API_KEY":null}', "a"],
+    ['{"API_KEY":null,"api_key":"a"}', "a"],
+    ['{"api_key":"a","API_KEY":null,"apI_kEy":"c"}', "c"],
+    // ...but with no other value present the field keeps its zero value.
+    ['{"api_key":null}', ""]
+  ])("case-variant string keys fold in document order: %s -> %s", (text, expected) => {
+    expect(ok(text).apiKey).toBe(expected)
+  })
+
+  test("null into a POINTER field (oauth) really does clear it", () => {
+    // Unlike a string field, a pointer IS set to nil by null — and a later
+    // object re-allocates it.
+    expect(ok('{"oauth":{"client_id":"a"},"OAUTH":null}').oauth).toBeUndefined()
+    expect(ok('{"OAUTH":null,"oauth":{"client_id":"a"}}').oauth?.clientId).toBe("a")
+    expect(ok('{"oauth":null,"OAUTH":{"client_id":"a"}}').oauth?.clientId).toBe("a")
+  })
+
+  test("null into a SLICE field (scopes) clears it, unlike a string field", () => {
+    expect(ok('{"oauth":{"scopes":["a"],"SCOPES":null}}').oauth?.scopes).toBeUndefined()
+    expect(ok('{"oauth":{"SCOPES":null,"scopes":["a"]}}').oauth?.scopes).toEqual(["a"])
+    expect(ok('{"oauth":{"client_id":"a","CLIENT_ID":null}}').oauth?.clientId).toBe("a")
+  })
+
+  test("case-variant oauth objects MERGE into one struct rather than replacing", () => {
+    // Go allocates the struct once and decodes each matching object into it.
+    const merged = ok('{"oauth":{"client_id":"a"},"OAUTH":{"client_secret":"b"}}').oauth
+    expect(merged?.clientId).toBe("a")
+    expect(merged?.clientSecret).toBe("b")
+    // Nested keys fold the same way, last-wins.
+    expect(ok('{"oauth":{"CLIENT_ID":"ci","client_id":"exact"}}').oauth?.clientId).toBe("exact")
+    expect(ok('{"oauth":{"client_id":"exact","CLIENT_ID":"ci"}}').oauth?.clientId).toBe("ci")
+  })
+
+  test("a type error inside an oauth block a later null CLEARS is still an error", () => {
+    // Go decodes each object as it walks the document and keeps the first
+    // error, so the trailing null does not excuse the bad type. This is what
+    // routes Load() to its corrupt-file/env-key path. Verified against Go.
+    expect(Result.isFailure(decode('{"oauth":{"client_id":123},"OAUTH":null}'))).toBe(true)
+    expect(Result.isFailure(decode('{"oauth":{"scopes":"notarray"},"OAUTH":null}'))).toBe(true)
+    // A well-typed block cleared by a later null is still just nil.
+    expect(ok('{"oauth":{"client_id":"a"},"OAUTH":null}').oauth).toBeUndefined()
+  })
+
+  test("a wrong type under a case-variant key still errors", () => {
+    expect(Result.isFailure(decode('{"API_KEY":123}'))).toBe(true)
+    expect(Result.isFailure(decode('{"api_key":"ok","API_KEY":123}'))).toBe(true)
+    expect(Result.isFailure(decode('{"API_KEY":123,"api_key":"ok"}'))).toBe(true)
+  })
+
+  test("whitespace inside a value is preserved; trimming happens in Load()", () => {
+    expect(ok('{"api_key":"  spaced  "}').apiKey).toBe("  spaced  ")
+  })
+
+  test.each([
+    ['{"api_key":123}', "number into"],
+    ['{"api_key":true}', "bool into"],
+    ['{"oauth":{"scopes":"x"}}', "string into"],
+    ['{"oauth":{"scopes":[1,2]}}', "number into"],
+    ['{"oauth":[]}', "array into"],
+    ['{"oauth":true}', "bool into"],
+    ['"a string"', "string into"],
+    ["123", "number into"],
+    ["[]", "array into"]
+  ])("a wrong type is an error: %s", (text, fragment) => {
+    const r = decode(text)
+    expect(Result.isFailure(r)).toBe(true)
+    if (Result.isFailure(r)) expect(r.failure.message).toContain(fragment)
+  })
+
+  test.each([["{not json"], [""], ['{"api_key":"x"}{"api_key":"y"}']])(
+    "malformed JSON fails: %s",
+    (text) => {
+      expect(Result.isFailure(decode(text))).toBe(true)
+    }
+  )
+
+  test("a non-object, non-null JSON value is rejected", () => {
+    const r = decodeAuthFile(true as JsonValue)
+    expect(Result.isFailure(r)).toBe(true)
+  })
+})
+
+describe("sameOAuth — the compare half of the compare-and-swap", () => {
+  const base = oauth({ scopes: ["a", "b"] })
+
+  test("both undefined are equal; exactly one undefined is not", () => {
+    expect(sameOAuth(undefined, undefined)).toBe(true)
+    expect(sameOAuth(base, undefined)).toBe(false)
+    expect(sameOAuth(undefined, base)).toBe(false)
+  })
+
+  test("identical values are equal", () => {
+    expect(sameOAuth(base, { ...base, scopes: ["a", "b"] })).toBe(true)
+  })
+
+  test.each([
+    ["clientId", { clientId: "other" }],
+    ["clientSecret", { clientSecret: "other" }],
+    ["accessToken", { accessToken: "other" }],
+    ["refreshToken", { refreshToken: "other" }],
+    ["expiry", { expiry: "other" }]
+  ] as ReadonlyArray]>)(
+    "a differing %s breaks equality",
+    (_name, patch) => {
+      expect(sameOAuth(base, { ...base, ...patch })).toBe(false)
+    }
+  )
+
+  test("scope length and element ORDER both matter", () => {
+    expect(sameOAuth(base, { ...base, scopes: ["a"] })).toBe(false)
+    expect(sameOAuth(base, { ...base, scopes: ["a", "b", "c"] })).toBe(false)
+    expect(sameOAuth(base, { ...base, scopes: ["b", "a"] })).toBe(false)
+  })
+
+  test("nil and empty scopes both have length 0 and compare equal", () => {
+    expect(sameOAuth(oauth({ scopes: undefined }), oauth({ scopes: [] }))).toBe(true)
+  })
+})
+
+describe("cloneOAuth", () => {
+  test("copies the scope array rather than aliasing it", () => {
+    const scopes = ["a", "b"]
+    const clone = cloneOAuth(oauth({ scopes }))
+    scopes.push("c")
+    expect(clone.scopes).toEqual(["a", "b"])
+  })
+
+  test("an empty slice clones to nil, matching append([]string(nil), empty...)", () => {
+    expect(cloneOAuth(oauth({ scopes: [] })).scopes).toBeUndefined()
+  })
+})
diff --git a/src/schema/authfile.ts b/src/schema/authfile.ts
new file mode 100644
index 0000000..53fc7d9
--- /dev/null
+++ b/src/schema/authfile.ts
@@ -0,0 +1,362 @@
+/**
+ * `auth.json` — the on-disk credential file.
+ *
+ * DELIBERATELY HAND-ROLLED rather than an Effect `Schema`. Go's
+ * `encoding/json` has three behaviors this file must reproduce exactly, none of
+ * which a `Schema` expresses naturally:
+ *
+ *   1. `null` is never a decode error, but what it DOES depends on the Go field
+ *      type. Into a non-pointer `string` it is a NO-OP, so
+ *      `{"api_key":"a","API_KEY":null}` keeps `"a"`; into a pointer (`oauth`) or
+ *      a slice (`scopes`) it assigns nil. A `Schema.NullOr` union captures
+ *      neither rule.
+ *   2. A wrong *type* IS an error (`{"api_key":123}` fails), and `Load()`
+ *      converts that into the corrupt-file/env-key fallback, so the
+ *      strict-vs-tolerant split has to land on exactly Go's line.
+ *   3. Object keys are resolved to fields by exact tag match OR a
+ *      case-insensitive fold, and every matching key is decoded IN DOCUMENT
+ *      ORDER into the same field — so `{"api_key":"exact","API_KEY":"upper"}`
+ *      yields `"upper"`, and two case-variant `oauth` objects MERGE rather than
+ *      the last replacing the first. Verified against Go 1.26.5.
+ *
+ * Differentially fuzzed against the real Go structs over 4,000 generated
+ * documents (case variants, nulls, wrong types, nested and repeated `oauth`
+ * blocks): identical on every input, with one class of exception.
+ *
+ * KNOWN LIMITATION — repeated IDENTICAL keys. `JSON.parse` collapses
+ * `{"api_key":123,"api_key":"ok"}` to last-wins before this decoder runs, so
+ * an earlier duplicate's TYPE ERROR is invisible and Go's hard failure becomes
+ * a success here. (It never differs the other way: this decoder is never
+ * stricter than Go.) Reproducing it needs a parser that surfaces every
+ * key/value pair, which `src/json/parse.ts` deliberately does not do. The
+ * effect is confined to a hand-edited auth.json that repeats a key verbatim
+ * AND gives the earlier copy a wrong type; the value ultimately read is still
+ * Go's last-wins value.
+ *
+ * The serializer is likewise hand-composed. `encodeGoStruct` only preserves key
+ * order at the top level — nested objects are sorted, which would emit the six
+ * oauth keys alphabetically. Go marshals them in struct-field order, so the
+ * `oauth` block is encoded on its own and re-indented into place.
+ *
+ * nil vs. empty `scopes` is a real distinction on disk: a nil slice marshals as
+ * `null`, an empty slice as `[]`. `undefined` here means nil.
+ */
+
+import { Data, Result } from "effect"
+import { encodeGoString, encodeGoStruct } from "../json/encode.ts"
+import { isJsonArray, isJsonObject, type JsonValue } from "../json/value.ts"
+
+export class AuthFileDecodeError extends Data.TaggedError("AuthFileDecodeError")<{
+  readonly message: string
+}> {}
+
+/** The `oauth` block. `scopes: undefined` is Go's nil slice, which emits `null`. */
+export interface AuthOAuth {
+  readonly clientId: string
+  readonly clientSecret: string
+  readonly accessToken: string
+  readonly refreshToken: string
+  readonly expiry: string
+  readonly scopes: ReadonlyArray | undefined
+}
+
+export interface AuthFile {
+  readonly apiKey: string
+  readonly oauth: AuthOAuth | undefined
+}
+
+export const emptyAuthFile: AuthFile = { apiKey: "", oauth: undefined }
+
+// ---------------------------------------------------------------------------
+// Decoding
+// ---------------------------------------------------------------------------
+
+type JsonObject = { readonly [key: string]: JsonValue }
+
+/**
+ * Every value that Go would decode into the field tagged `name`, in DOCUMENT
+ * ORDER, gathered across all `objects` (an object list because a struct field
+ * can be targeted by several case-variant keys — see `decodeAuthFile`).
+ *
+ * `encoding/json` walks the object's keys in order and resolves each to a field
+ * by exact tag match first, case-insensitive (`equalsFold`) match second, then
+ * ASSIGNS. It does not stop at the first hit, so several keys can write the same
+ * field and the effect is cumulative rather than "exact match wins":
+ *
+ *   {"api_key":"exact","API_KEY":"upper"} -> "upper"   (NOT "exact")
+ *   {"API_KEY":"upper","api_key":"exact"} -> "exact"
+ *   {"API_KEY":"a","Api_Key":"b"}         -> "b"
+ *
+ * Callers fold this list with the semantics of their own Go field type, which
+ * differ for `null` (see `decodeString` vs `decodeScopes`). No two field names
+ * in this schema fold-collide, so a fold-equality test is exactly Go's rule.
+ * Verified against Go 1.26.5.
+ */
+const goFields = (objects: ReadonlyArray, name: string): ReadonlyArray => {
+  const lower = name.toLowerCase()
+  const values: Array = []
+  for (const object of objects) {
+    for (const key of Object.keys(object)) {
+      if (key === name || key.toLowerCase() === lower) values.push(object[key] as JsonValue)
+    }
+  }
+  return values
+}
+
+const jsonKind = (value: JsonValue): string => {
+  if (value === null) return "null"
+  if (typeof value === "string") return "string"
+  if (typeof value === "boolean") return "bool"
+  if (isJsonArray(value)) return "array"
+  if (isJsonObject(value)) return "object"
+  return "number"
+}
+
+const fail = (message: string): Result.Result =>
+  Result.fail(new AuthFileDecodeError({ message }))
+
+/**
+ * Fold every value targeting a Go `string` field.
+ *
+ * `null` into a NON-POINTER field is a documented Go no-op ("To unmarshal JSON
+ * null into a value, Unmarshal sets that value to nil" applies to
+ * interface/pointer/map/slice; for a string it leaves the field untouched), so
+ * `{"api_key":"a","API_KEY":null}` keeps `"a"`. A wrong type is a hard error.
+ */
+const decodeString = (
+  values: ReadonlyArray,
+  field: string
+): Result.Result => {
+  let result = ""
+  for (const value of values) {
+    // A null leaves the previously-assigned value in place.
+    if (value === null) continue
+    if (typeof value !== "string") {
+      return fail(
+        `json: cannot unmarshal ${jsonKind(value)} into Go struct field ${field} of type string`
+      )
+    }
+    result = value
+  }
+  return Result.succeed(result)
+}
+
+/**
+ * Fold every value targeting the `[]string` scopes field. Unlike a string, a
+ * SLICE field IS set to nil by `null`, so a trailing `"SCOPES":null` really does
+ * clear an earlier `"scopes":["a"]`.
+ */
+const decodeScopes = (
+  values: ReadonlyArray
+): Result.Result | undefined, AuthFileDecodeError> => {
+  let result: ReadonlyArray | undefined
+  for (const value of values) {
+    if (value === null) {
+      result = undefined
+      continue
+    }
+    if (!isJsonArray(value)) {
+      return fail(
+        `json: cannot unmarshal ${jsonKind(value)} into Go struct field OAuthCredentials.oauth.scopes of type []string`
+      )
+    }
+    const scopes: Array = []
+    for (const element of value) {
+      // Go decodes a null array element to the zero value, keeping the slot.
+      if (element === null) {
+        scopes.push("")
+        continue
+      }
+      if (typeof element !== "string") {
+        return fail(
+          `json: cannot unmarshal ${jsonKind(element)} into Go struct field OAuthCredentials.oauth.scopes of type string`
+        )
+      }
+      scopes.push(element)
+    }
+    result = scopes
+  }
+  return Result.succeed(result)
+}
+
+/**
+ * Decode the `oauth` block from every object that targeted it, in order. Go
+ * allocates the struct once and decodes each such object INTO it, so
+ * `{"oauth":{"client_id":"a"},"OAUTH":{"client_secret":"b"}}` merges into a
+ * single value rather than the last object replacing the first.
+ */
+const decodeOAuth = (
+  objects: ReadonlyArray
+): Result.Result => {
+  const clientId = decodeString(
+    goFields(objects, "client_id"),
+    "OAuthCredentials.oauth.client_id"
+  )
+  if (Result.isFailure(clientId)) return Result.fail(clientId.failure)
+  const clientSecret = decodeString(
+    goFields(objects, "client_secret"),
+    "OAuthCredentials.oauth.client_secret"
+  )
+  if (Result.isFailure(clientSecret)) return Result.fail(clientSecret.failure)
+  const accessToken = decodeString(
+    goFields(objects, "access_token"),
+    "OAuthCredentials.oauth.access_token"
+  )
+  if (Result.isFailure(accessToken)) return Result.fail(accessToken.failure)
+  const refreshToken = decodeString(
+    goFields(objects, "refresh_token"),
+    "OAuthCredentials.oauth.refresh_token"
+  )
+  if (Result.isFailure(refreshToken)) return Result.fail(refreshToken.failure)
+  const expiry = decodeString(goFields(objects, "expiry"), "OAuthCredentials.oauth.expiry")
+  if (Result.isFailure(expiry)) return Result.fail(expiry.failure)
+  const scopes = decodeScopes(goFields(objects, "scopes"))
+  if (Result.isFailure(scopes)) return Result.fail(scopes.failure)
+
+  return Result.succeed({
+    clientId: clientId.success,
+    clientSecret: clientSecret.success,
+    accessToken: accessToken.success,
+    refreshToken: refreshToken.success,
+    expiry: expiry.success,
+    scopes: scopes.success
+  })
+}
+
+/**
+ * Decode a parsed `auth.json`. Top-level `null` is a no-op yielding the zero
+ * File (Go); any other non-object is an error.
+ */
+export const decodeAuthFile = (
+  value: JsonValue
+): Result.Result => {
+  if (value === null) return Result.succeed(emptyAuthFile)
+  if (!isJsonObject(value)) {
+    return fail(`json: cannot unmarshal ${jsonKind(value)} into Go value of type config.File`)
+  }
+
+  const apiKey = decodeString(goFields([value], "api_key"), "File.api_key")
+  if (Result.isFailure(apiKey)) return Result.fail(apiKey.failure)
+
+  // `oauth` is a POINTER field, so `null` really does reset it to nil — but a
+  // later object then re-allocates and decodes into a fresh struct. Collect the
+  // objects that survive the last null and merge them.
+  const rawOAuths = goFields([value], "oauth")
+  const blocks: Array = []
+  for (const raw of rawOAuths) {
+    if (raw === null) {
+      blocks.length = 0
+      continue
+    }
+    if (!isJsonObject(raw)) {
+      return fail(
+        `json: cannot unmarshal ${jsonKind(raw)} into Go struct field File.oauth of type config.OAuthCredentials`
+      )
+    }
+    // Validate EVERY block, even one a later null discards. Go decodes each
+    // object as it walks the document and keeps the first error it hits, so a
+    // bad type inside a block that is subsequently cleared still fails the
+    // whole Unmarshal — which is what routes Load() to its corrupt-file path.
+    const checked = decodeOAuth([raw])
+    if (Result.isFailure(checked)) return Result.fail(checked.failure)
+    blocks.push(raw)
+  }
+  if (blocks.length === 0) {
+    return Result.succeed({ apiKey: apiKey.success, oauth: undefined })
+  }
+  const oauth = decodeOAuth(blocks)
+  if (Result.isFailure(oauth)) return Result.fail(oauth.failure)
+  return Result.succeed({ apiKey: apiKey.success, oauth: oauth.success })
+}
+
+// ---------------------------------------------------------------------------
+// Encoding
+// ---------------------------------------------------------------------------
+
+/** Push every line but the first right by `pad`, nesting a rendered block. */
+const indentBlock = (text: string, pad: string): string => text.split("\n").join(`\n${pad}`)
+
+const encodeOAuthBlock = (oauth: AuthOAuth): string =>
+  indentBlock(
+    encodeGoStruct(
+      [
+        ["client_id", oauth.clientId],
+        ["client_secret", oauth.clientSecret],
+        ["access_token", oauth.accessToken],
+        ["refresh_token", oauth.refreshToken],
+        ["expiry", oauth.expiry],
+        // A nil slice is `null`; an empty slice is `[]`. Both are reachable.
+        ["scopes", oauth.scopes === undefined ? null : [...oauth.scopes]]
+      ],
+      { indent: "  " }
+    ),
+    "  "
+  )
+
+/**
+ * `json.MarshalIndent(file, "", "  ")` + a trailing newline.
+ *
+ * `api_key` is `omitempty`; `oauth` is omitted when nil; the six oauth keys are
+ * always present. An entirely empty file marshals to `{}\n`.
+ *
+ * NOTE: Go's `json.Marshal` escapes `<`, `>` and `&` as `<`/`>`/
+ * `&` (HTML escaping is on by default — `internal/output` explicitly turns
+ * it OFF, `internal/config` does not). Credential values are opaque secrets,
+ * so an API key containing one of those bytes would round-trip differently
+ * from Go byte-for-byte. It still round-trips correctly through this reader,
+ * and Google API keys / OAuth tokens are `[A-Za-z0-9._~-]`, so the divergence
+ * is unreachable in practice. Flagged rather than fixed because the shared
+ * `encodeGoString` is owned elsewhere.
+ */
+export const encodeAuthFile = (file: AuthFile): string => {
+  const lines: Array = []
+  if (file.apiKey !== "") {
+    lines.push(`  ${encodeGoString("api_key")}: ${encodeGoString(file.apiKey)}`)
+  }
+  if (file.oauth !== undefined) {
+    lines.push(`  ${encodeGoString("oauth")}: ${encodeOAuthBlock(file.oauth)}`)
+  }
+  if (lines.length === 0) return "{}\n"
+  return `{\n${lines.join(",\n")}\n}\n`
+}
+
+// ---------------------------------------------------------------------------
+// Helpers shared with the credential store
+// ---------------------------------------------------------------------------
+
+/**
+ * Go's `cloneOAuth`. Note `append([]string(nil), empty...)` returns **nil**, so
+ * an empty scope slice becomes nil here and therefore serializes as `null`.
+ */
+export const cloneOAuth = (oauth: AuthOAuth): AuthOAuth => ({
+  ...oauth,
+  scopes: oauth.scopes === undefined || oauth.scopes.length === 0 ? undefined : [...oauth.scopes]
+})
+
+/**
+ * Go's `sameOAuth`: both nil -> equal; exactly one nil -> not equal; otherwise
+ * all five strings, then scope length, then each scope by index. A nil slice
+ * and an empty slice both have length 0 and so compare equal.
+ */
+export const sameOAuth = (
+  left: AuthOAuth | undefined,
+  right: AuthOAuth | undefined
+): boolean => {
+  if (left === undefined || right === undefined) return left === right
+  if (
+    left.clientId !== right.clientId ||
+    left.clientSecret !== right.clientSecret ||
+    left.accessToken !== right.accessToken ||
+    left.refreshToken !== right.refreshToken ||
+    left.expiry !== right.expiry
+  ) {
+    return false
+  }
+  const leftScopes = left.scopes ?? []
+  const rightScopes = right.scopes ?? []
+  if (leftScopes.length !== rightScopes.length) return false
+  for (let i = 0; i < leftScopes.length; i++) {
+    if (leftScopes[i] !== rightScopes[i]) return false
+  }
+  return true
+}
diff --git a/src/schema/errorEnvelope.test.ts b/src/schema/errorEnvelope.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..087829bad294bea0585889370100037b87a8a139
GIT binary patch
literal 8637
zcmcIpU2+?_5zezt(S<5kD2E~?#fmG8;|kYiyh_QEOO*FTQ7yq4h#YG;-~uy}8I`JX
zh+H5i$x|M3jhrN30~m6K9NO|mtMXE-A*RvjpRd1ebe})pq31NXRc1kvw2Hm4&oatcp3HQ%nCZfj
z%}o*IG@4_v>VG&M7^BUIVil#*DBH%;n54DJMh7g>)Vh}9cvHqRICP=o9irkmqkch=go
zrG!q`=~S-mXStQaDfxQut?cqw*V~(Y-swh}$@Q=xMSfm2!7T*ad8*IUuM
zyl3rr^RR00IZ`Udnun{0hf&yk*Ztn@Chv^Y-Q=X_to7=#{EZg?z(to*>
zenk%~6d(9x54E6q7Rg*?_|N)4fN3}kGI%+cNs2$=D#V~Nw;WO0#L7IO(GIF6n{6?Y
zIuH--iqX^|EY%i4!@5CZtgTux_}Q*m^HM-)n*>DR6E9t@o90HTxuv+6rwN*InC_$L6IihJ?`OtwIV+$w-2empRiXz_pH
z$hM@Au&MY|WH+Lk8gjATt16vRU8)TSr>HDJ03a*N
zQ7Q_Cmkc%rgf#g`Pf~@N36q9$)Csu_>%+iPl`EqsDpOo6QR{L&F0QGcEl3(87r%(j
z8_@+xCH|Bz=74*_zd94my32WDJCUAs{hu8(k2(X6$>Z!=JC~F%eXr6vWTZ)U!-88{Qa~UcA26_J1jHtQ*JkAx=nEo<6JH?_#
zOf(3{irLszX7S>%Dj_S_%Jwse>@x>pPl~rc5r$;cq?je<_2KTlw~5#80@d6(-zJ)L&#G3;^@i+!_{s}
z=!~AZi2E^>p#E**s96%u3gCMd+JN`&h20J?5QOf6Be>-=N
zkw>`@#jW11P^-w&bUD^eEa0_oKtwY(a&{a>HUf`xm-IPz=F7=b5)5R
z?c(juEt&dex3hG0$-Y;Z#+GHP=qyDwiz1LEm;~)w2JV8Ih_;dYK(;^K=^}->+#*VH
zMD(ibX^fy%VpRejpxovzVg&}9%l3}ks=cExE!uZ$_LocG^gc+HzGlaxNuEgr(DD#<
z7S<+IP1jL41EBZZUwVC09cbHG-|ez_*~>MhnwF`o;YqWPMjxVO^xherP4<`(q0y~HB@w~`a|chg%T64L$72&WHDQ!+a@;N+?tu@X
z64#k@V^6*r2+nzr=`6ufxTErCC)(_`_p7~jouq&n2cF`xx=d|mA}!&&6<BY~G3?vR#lxlrb%*iGxvV^Cc
zENV5qCwh~3a+Xi!jQ7H;kbd@Z>|X`t;1RkO<$9ZD(Y$0w45
zR(747mkIP`eSkjPoBGCdD;L~OC_+oR>{{Gij^}|@!jOWm7zS|kC}@}N3=opwg*3rq
zoxu+X!dORz8^|`@55R2z(c1*|&w4?4!!2~9Q=Z!Jf*_v@NR|5B2f5;RqoM2*`kLRaD@b54ofP9$UQ+E
z@SAX8pL`tnnd152!%6?mU`Vxz<9rUPR`*ko`xV-_JeNBS5~6xT#&hnQ|y3ckDHhFV_=FQl-BnTuS3soCzB{YfsPJg$@c7atC*HNlvULNR?H<8`u~RdHVP0
zG;`iqq4H6g`M6SBSM}&yfTWtDZLy?H{`}#~vTvKY#x0~??eu&ax|M0+#zvuOLzQ-^
z7T{xh+Ev}#lseoHBZ2~33L(V)3DDpquds!$hpv_&5x9age}p_Ss15lqqF5NHY*owY
J1oXnc{{duUVGRHP

literal 0
HcmV?d00001

diff --git a/src/schema/errorEnvelope.ts b/src/schema/errorEnvelope.ts
new file mode 100644
index 0000000..a2e272c
--- /dev/null
+++ b/src/schema/errorEnvelope.ts
@@ -0,0 +1,175 @@
+/**
+ * Google's error envelope, decoded the way Go decodes it: tolerantly, and
+ * NEVER throwing.
+ *
+ * Go writes `_ = json.Unmarshal(body, &envelope)` — the decode error is
+ * explicitly discarded, so a malformed, non-JSON, empty, or HTML body simply
+ * leaves every field at its zero value. The caller then falls back to the HTTP
+ * status for `code` and to the canonical status text for `message`.
+ *
+ * This is deliberately hand-written rather than Schema-based. Go's decoder is
+ * *partial*: when one element of `errors[]` has the wrong shape it records the
+ * zero value for that element and keeps going, and it still fills sibling
+ * fields. Verified against Go 1.26.5 (`go run` probe):
+ *
+ *   errors:[{reason:"a"},"junk",{reason:""},{reason:"b"}]  -> reasons a, b
+ *   errors:["junk"], details:[{reason:"d1"}]               -> reasons d1
+ *   errors:{reason:"a"}   (object, not array)              -> no reasons
+ *   error:"boom"          (string, not object)             -> everything zero
+ *   code:"403" / 403.7 / 4e2 / 99999999999999999999        -> code 0
+ *   code:-5                                                -> code -5
+ *   `{...} trailing garbage`                               -> everything zero
+ *
+ * That last one matters: `json.Unmarshal` (unlike `json.Decoder`) rejects
+ * trailing content, so the envelope path uses a STRICT parse while the success
+ * path (§1.9) tolerates trailing bytes. The asymmetry is real, not an oversight.
+ *
+ * `Schema.Array` is all-or-nothing and would drop every reason as soon as one
+ * element were malformed, so it is the wrong tool here.
+ *
+ * KNOWN LIMITATION — repeated IDENTICAL keys. Go merges `{"error":{"code":9},
+ * "error":{"message":"m"}}` into one struct (code 9 AND message "m"); the
+ * underlying `JSON.parse` keeps only the last occurrence, so this yields
+ * message "m" with code 0. Same root cause as the note in `schema/authfile.ts`
+ * and it lives in `json/parse.ts`, not here. Case-VARIANT duplicates
+ * (`"error"` + `"Error"`) are distinct keys and ARE handled correctly below.
+ * Google's API never emits duplicate keys.
+ */
+
+import { Result } from "effect"
+import { parseJson } from "../json/parse.ts"
+import { isJsonObject, isRawNumber, type JsonObject, type JsonValue } from "../json/value.ts"
+
+export interface ErrorEnvelope {
+  /** `error.code`, or 0 when absent/not an integer. */
+  readonly code: number
+  /** `error.message`, or "" when absent/not a string. */
+  readonly message: string
+  /** `errors[].reason` then `details[].reason`; empties skipped, duplicates kept. */
+  readonly reasons: ReadonlyArray
+}
+
+export const emptyErrorEnvelope: ErrorEnvelope = { code: 0, message: "", reasons: [] }
+
+/** Go's int64 bounds — `code` is declared `int`, so an overflow decodes to 0. */
+const INT64_MIN = -9223372036854775808n
+const INT64_MAX = 9223372036854775807n
+
+/**
+ * A JSON number that Go would accept into an `int` field: an integer literal
+ * with no fraction, no exponent, and within int64 range. `403.0` and `4e2` are
+ * both rejected by Go even though they are integral values.
+ */
+const asGoInt = (value: JsonValue | undefined): number | undefined => {
+  if (!isRawNumber(value)) return undefined
+  const literal = value.$rawNumber
+  if (!/^-?(?:0|[1-9][0-9]*)$/.test(literal)) return undefined
+  const parsed = BigInt(literal)
+  if (parsed < INT64_MIN || parsed > INT64_MAX) return undefined
+  return Number(parsed)
+}
+
+/**
+ * Go's `foldName`: struct-tag matching is CASE-INSENSITIVE when no exact match
+ * exists, so `{"Error":{"CODE":403}}` decodes exactly like the lowercase form.
+ * Verified against Go 1.26.5 — a case-sensitive lookup silently returns a zero
+ * envelope for any provider that capitalises a key.
+ *
+ * The fold is ASCII-only plus Go's two special runes (`ſ` U+017F folds to `s`,
+ * `K` U+212A to `k`); of those only `ſ` can appear in a field name here.
+ * A non-ASCII near-miss such as `ɡ` (U+0261) does NOT match, matching Go.
+ */
+const foldName = (name: string): string => {
+  let out = ""
+  for (const char of name) {
+    const code = char.codePointAt(0)!
+    if (code === 0x017f) out += "S"
+    else if (code === 0x212a) out += "K"
+    else if (code < 0x80) out += char.toUpperCase()
+    else out += char
+  }
+  return out
+}
+
+/**
+ * Go matches an object key to a struct field by exact tag first, then by fold.
+ * Keys are visited in document order and each assignment overwrites the last,
+ * so `{"CODE":1,"code":2}` yields 2 and `{"code":2,"CODE":1}` yields 1.
+ */
+const fieldValues = (object: JsonObject, tag: string): Array => {
+  const folded = foldName(tag)
+  const out: Array = []
+  for (const key of Object.keys(object)) {
+    if (key === tag || foldName(key) === folded) out.push(object[key])
+  }
+  return out
+}
+
+const asString = (value: JsonValue | undefined): string =>
+  typeof value === "string" ? value : ""
+
+/** Element-wise, tolerant: non-objects and empty reasons contribute nothing. */
+const collectReasons = (value: JsonValue | undefined, into: Array): void => {
+  if (!Array.isArray(value)) return
+  for (const element of value) {
+    if (!isJsonObject(element)) continue
+    // `reason` is matched with the same fold rule as every other tag.
+    let reason: JsonValue | undefined
+    for (const candidate of fieldValues(element, "reason")) reason = candidate
+    if (typeof reason === "string" && reason !== "") into.push(reason)
+  }
+}
+
+/**
+ * Best-effort extraction. Any failure — invalid JSON, an unexpected shape, a
+ * wrong-typed field — yields zero values for the affected parts and never
+ * raises.
+ */
+export const parseErrorEnvelope = (body: string): ErrorEnvelope => {
+  const parsed = parseJson(body)
+  if (Result.isFailure(parsed)) return emptyErrorEnvelope
+
+  const root = parsed.success
+  if (!isJsonObject(root)) return emptyErrorEnvelope
+
+  // Go decodes EVERY key that matches the `error` tag (exactly or by fold), in
+  // document order, merging into the one struct. A key whose value is not an
+  // object — `null`, a string, a number — is a no-op that leaves already-decoded
+  // fields intact, so `{"error":{"code":1},"Error":"junk"}` still yields 1.
+  let code = 0
+  let message = ""
+  let errors: JsonValue | undefined
+  let details: JsonValue | undefined
+  let sawError = false
+
+  for (const candidate of fieldValues(root, "error")) {
+    if (candidate === undefined || !isJsonObject(candidate)) continue
+    sawError = true
+    // Scalars: a valid value overwrites; null or a wrong type is a no-op.
+    for (const raw of fieldValues(candidate, "code")) {
+      const next = asGoInt(raw)
+      if (next !== undefined) code = next
+    }
+    for (const raw of fieldValues(candidate, "message")) {
+      if (typeof raw === "string") message = raw
+    }
+    // Slices: an array overwrites and `null` RESETS to nil, but any other type
+    // is a no-op. Verified against Go 1.26.5.
+    for (const raw of fieldValues(candidate, "errors")) {
+      if (Array.isArray(raw)) errors = raw
+      else if (raw === null) errors = undefined
+    }
+    for (const raw of fieldValues(candidate, "details")) {
+      if (Array.isArray(raw)) details = raw
+      else if (raw === null) details = undefined
+    }
+  }
+
+  if (!sawError) return emptyErrorEnvelope
+
+  const reasons: Array = []
+  collectReasons(errors, reasons)
+  collectReasons(details, reasons)
+
+  return { code, message, reasons }
+}
diff --git a/src/services/index.ts b/src/services/index.ts
index d4d540e..94eac85 100644
--- a/src/services/index.ts
+++ b/src/services/index.ts
@@ -39,9 +39,19 @@ export interface HttpCoreRequest {
 }
 
 export interface HttpCoreShape {
+  /**
+   * `OAuthError` is in the union because a token-source failure propagates
+   * verbatim rather than being wrapped: it carries its own exit code (3 to
+   * re-login, 5 on a 429, 6 on a 5xx), and flattening it into an
+   * `OperationalError` would report every case as 6 and drop the
+   * "re-run 'oytc login --oauth'" hint.
+   */
   readonly getJson: (
     request: HttpCoreRequest
-  ) => Effect.Effect
+  ) => Effect.Effect<
+    JsonValue,
+    ApiError | MissingKeyError | MissingOAuthError | OAuthError | OperationalError
+  >
 }
 
 export const HttpCore = Context.Service("oytc/HttpCore")
diff --git a/src/skills/SKILL.md b/src/skills/SKILL.md
new file mode 100644
index 0000000..0de51a5
--- /dev/null
+++ b/src/skills/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: oytc
+description: Query public YouTube data and an authorized channel's read-only analytics via the oytc CLI. Use for video/channel stats, searches, uploads, comments, live chat, watch time, traffic sources, and demographics.
+---
+
+# oytc — read-only YouTube data and analytics CLI
+
+`oytc` reads public YouTube Data API v3 resources with an API key and the authorized
+channel's YouTube Analytics with read-only OAuth. It never writes. Revenue/content-owner
+reports, private playlist/subscription access, moderation, uploads, and mutations remain
+unsupported.
+
+This skill assumes `oytc` is installed. Public commands need `oytc login` (or
+`OYTC_API_KEY`); `analytics ...` needs `oytc login --oauth`. Verify both with
+`oytc status --check`. Exit code 3 means the indicated credential must be configured or
+reauthorized.
+
+## Core usage pattern
+
+Always request machine-readable output: `--format json` (stable envelope with `items`,
+`nextPageToken`, `requests`) or `--format jsonl` (one resource per line). Piped output
+defaults to JSON already, but be explicit.
+
+```sh
+oytc search "topic" --type video --limit 10 --format json
+oytc channel get @handle --format json                 # accepts UC… IDs, @handles, URLs
+oytc channel uploads @handle --all --limit 200 --format jsonl
+oytc video get VIDEO_ID --format json
+oytc video stats VIDEO_ID_1 VIDEO_ID_2 --format json   # counters are JSON strings
+oytc playlist items PLAYLIST_ID --all --format jsonl
+oytc comment threads --video VIDEO_ID --order relevance --format jsonl
+oytc live-chat stream --video LIVE_VIDEO_ID --limit 100   # JSONL; REST polling fallback
+
+# OAuth-only owner analytics
+oytc analytics overview --by day --format json
+oytc analytics video VIDEO_ID --start 2026-01-01 --end 2026-01-31 --format json
+oytc analytics traffic-sources --format jsonl
+oytc analytics demographics --format json
+```
+
+Pagination: `--all` follows pages, `--limit N` caps output, `--page-token` resumes.
+Trim payloads with `--parts` and `--fields` when you only need specific properties.
+
+## Quota and safety
+
+- `search` costs 1 call from a small daily bucket (default 100/day) — batch reasoning
+  before searching, prefer `channel uploads` / `playlist items` for enumeration.
+- Other list reads cost ~1 unit of a 10,000/day quota; exit code 5 = quota exhausted.
+- Exit codes: 0 ok, 2 usage, 3 credentials, 4 not found/forbidden, 5 quota, 6 transient.
+- Never print, log, or echo API keys, OAuth tokens, or the client secret. `oytc status`
+  intentionally shows only a key fingerprint plus OAuth client ID/scopes/expiry. Do not
+  read the `auth.json` credential file.
+- View/subscriber counters arrive as strings; keep them as strings to avoid precision loss.
+
+## References
+
+- [references/commands.md](references/commands.md) — condensed command/flag matrix
+- [references/recipes.md](references/recipes.md) — common data-collection recipes
+- Full project docs: https://github.com/davis7dotsh/open-yt-cli/blob/main/docs/commands.md
diff --git a/src/skills/bundle.test.ts b/src/skills/bundle.test.ts
new file mode 100644
index 0000000..7aacad2
--- /dev/null
+++ b/src/skills/bundle.test.ts
@@ -0,0 +1,61 @@
+/**
+ * Guards on the embedded bundle itself.
+ *
+ * The Go equivalent is `TestBundledSkillIsComplete` in
+ * `internal/skill/install_test.go`, which stats each of the three files in the
+ * embedded FS and fails on a zero-size entry. The extra assertions here exist
+ * because the TS bundle has a failure mode Go did not: a text import that
+ * silently resolves to something other than the file on disk.
+ */
+
+import { describe, expect, test } from "bun:test"
+import * as fsSync from "node:fs"
+import * as nodePath from "node:path"
+import { bundledSkillFileNames, bundledSkillFiles } from "./bundle.ts"
+
+const skillsDirectory = nodePath.dirname(import.meta.path)
+
+describe("bundledSkillFiles", () => {
+  test("is the hardcoded three-file list, in Go's order", () => {
+    expect(bundledSkillFileNames).toEqual([
+      "SKILL.md",
+      "references/commands.md",
+      "references/recipes.md"
+    ])
+  })
+
+  test("every entry is non-empty", () => {
+    for (const file of bundledSkillFiles) {
+      expect(file.content.length).toBeGreaterThan(0)
+    }
+  })
+
+  test("each entry matches the file on disk byte for byte", () => {
+    for (const file of bundledSkillFiles) {
+      const onDisk = fsSync.readFileSync(
+        nodePath.join(skillsDirectory, ...file.name.split("/")),
+        "utf8"
+      )
+      expect(file.content).toBe(onDisk)
+    }
+  })
+
+  test("names are slash-separated bundle paths, never absolute or traversing", () => {
+    for (const name of bundledSkillFileNames) {
+      expect(name).not.toContain("\\")
+      expect(name).not.toContain("..")
+      expect(nodePath.posix.isAbsolute(name)).toBe(false)
+    }
+  })
+
+  test("the list is not derived from a directory walk", () => {
+    // A stray file dropped into src/skills/ must NOT become part of a release.
+    // If this ever needs updating, the update belongs in bundle.ts by hand.
+    const onDisk = fsSync
+      .readdirSync(skillsDirectory, { recursive: true, encoding: "utf8" })
+      .filter((entry) => entry.endsWith(".md"))
+      .map((entry) => entry.split(nodePath.sep).join("/"))
+      .sort()
+    expect(onDisk).toEqual([...bundledSkillFileNames].sort())
+  })
+})
diff --git a/src/skills/bundle.ts b/src/skills/bundle.ts
new file mode 100644
index 0000000..af894a9
--- /dev/null
+++ b/src/skills/bundle.ts
@@ -0,0 +1,48 @@
+/**
+ * The bundled agent skill — the port of `skills/oytc/embed.go`.
+ *
+ * Go compiled the skill into the binary with `//go:embed SKILL.md
+ * references/*.md`. Bun's equivalent is a static text import, which the
+ * bundler inlines into the compiled executable:
+ *
+ *     import raw from "./SKILL.md" with { type: "text" }
+ *
+ * **The file list is HARDCODED, deliberately, in both implementations.** Go's
+ * embed glob could match more than three files; `internal/skill/install.go`
+ * still installs exactly the three named in its `files` slice, in that order.
+ * Never replace this with a directory walk: a stray file dropped into
+ * `src/skills/` must not silently become part of a release.
+ *
+ * TypeScript cannot resolve `*.md` module specifiers (no wildcard ambient
+ * declaration is in scope), so each import carries a `@ts-ignore` and an
+ * explicit `string` annotation. Bun resolves them at build and at `bun run`.
+ */
+
+// @ts-ignore -- Bun text import; TypeScript has no resolver for "*.md".
+import skillMarkdown from "./SKILL.md" with { type: "text" }
+// @ts-ignore -- Bun text import; TypeScript has no resolver for "*.md".
+import commandsMarkdown from "./references/commands.md" with { type: "text" }
+// @ts-ignore -- Bun text import; TypeScript has no resolver for "*.md".
+import recipesMarkdown from "./references/recipes.md" with { type: "text" }
+
+/** One embedded file: a slash-separated relative name and its contents. */
+export interface BundledFile {
+  /** Always slash-separated, even on Windows — it is a bundle path, not a host path. */
+  readonly name: string
+  readonly content: string
+}
+
+/**
+ * The install manifest, in Go's order. `SkillInstaller` copies exactly these
+ * entries and nothing else.
+ */
+export const bundledSkillFiles: ReadonlyArray = [
+  { name: "SKILL.md", content: skillMarkdown as string },
+  { name: "references/commands.md", content: commandsMarkdown as string },
+  { name: "references/recipes.md", content: recipesMarkdown as string }
+]
+
+/** Just the names, for callers that report what was installed. */
+export const bundledSkillFileNames: ReadonlyArray = bundledSkillFiles.map(
+  (file) => file.name
+)
diff --git a/src/skills/references/commands.md b/src/skills/references/commands.md
new file mode 100644
index 0000000..14a0761
--- /dev/null
+++ b/src/skills/references/commands.md
@@ -0,0 +1,69 @@
+# oytc command matrix (agent reference)
+
+Canonical, exhaustive documentation lives at
+. `oytc  --help`
+is authoritative for the installed version. This file is a condensed matrix.
+
+## Global flags (all commands)
+
+| Flag | Notes |
+| --- | --- |
+| `--format table\|json\|jsonl\|tsv` | JSON when piped by default; be explicit anyway |
+| `--columns a.b,c.d` | dotted paths for table/TSV |
+| `--no-header` / `--quiet` | script-friendly output |
+| `--timeout 20s` | per-request timeout |
+
+Resource commands: `--parts` (API parts), `--fields` (Google partial-response selector),
+sometimes `--hl` (localization).
+
+Public list commands use an API key (or fall back to an OAuth grant that includes
+`youtube.readonly`): `--page-size N`, `--page-token T`, `--all`, `--limit N`. Analytics
+commands always require OAuth.
+
+## Commands
+
+| Command | Required input | Key flags |
+| --- | --- | --- |
+| `analytics report` **(OAuth)** | `--metrics CSV` | `--dimensions`, `--start/--end` (YYYY-MM-DD), `--filters`, `--sort`, `--limit` (1–200) |
+| `analytics overview` **(OAuth)** | — | `--by day\|month`, date/filter/sort/limit flags |
+| `analytics video ` **(OAuth)** | owned video ID | core metrics; applies `video==ID`; date/filter/sort/limit flags |
+| `analytics traffic-sources` **(OAuth)** | — | groups views/watch time by traffic source |
+| `analytics demographics` **(OAuth)** | — | groups viewer percentage by age and gender |
+| `search [QUERY]` | — | `--type video,channel,playlist`, `--channel`, `--order`, `--published-after/-before` (RFC3339), `--region`, `--language`, `--safe-search`, `--event-type` (video), `--video-duration/-caption/-category/…`, `--location`+`--location-radius`, `--topic` |
+| `channel get ...` | UC… ID, @handle, or channel URL | `--parts` (no `auditDetails`/`contentOwnerDetails`) |
+| `channel activities ` | channel ref | `--published-after/-before` |
+| `channel sections ` or `--id` | one of the two | |
+| `channel uploads ` | channel ref | resolves uploads playlist, then lists items |
+| `video get ...` / `video stats ...` | video IDs (batched ×50) | `--parts` (no `fileDetails`/`processingDetails`/`suggestions`) |
+| `video popular` | — | `--region` (default US), `--category` |
+| `video trainability ` | video ID | no key, no quota |
+| `playlist get ...` | playlist IDs | |
+| `playlist list --channel ` | channel ID | |
+| `playlist items ` | playlist ID | `--video` filters to one video |
+| `comment get ...` | comment IDs (batched ×100) | `--text-format plainText\|html` |
+| `comment replies ` | parent comment ID | |
+| `comment threads` | exactly one of `--video`/`--channel`/`--id` | `--order time\|relevance`, `--search` (both incompatible with `--id`) |
+| `subscription list` | exactly one of `--channel`/`--id` | `--for-channel`, `--order` (incompatible with `--id`); many channels hide subscriptions → API error |
+| `live-chat list` | one of `--video`/`--chat-id` | finite single page; `--all` rejected |
+| `live-chat stream` | one of `--video`/`--chat-id` | JSONL default, `--limit`, `--page-token`; REST polling, respects `pollingIntervalMillis`, dedupes IDs, exits when chat ends |
+| `category list` | one of `--region`/`--id` | |
+| `language list` / `region list` | — | |
+| `login [--oauth]` | API key, or Desktop OAuth client | no flag = API key; `--oauth` = loopback PKCE analytics authorization |
+| `status [--check]` | — | shows both credential types; local-only unless `--check` |
+| `logout` | — | best-effort OAuth revoke, then removes stored credentials |
+| `skills install` | confirmation | installs this bundled skill to `~/.agents/skills/oytc` |
+| `version` | — | version/commit/date/platform |
+| `update [--check] [--version vX.Y.Z]` | — | self-update; alias `upgrade` |
+
+## Output envelope (JSON)
+
+```json
+{"items": [...], "nextPageToken": "…", "requests": 2}
+```
+
+JSONL: one item object per line, no envelope. Numeric counters are strings.
+
+## Exit codes
+
+0 success · 2 usage · 3 API-key/OAuth credentials · 4 not found/forbidden ·
+5 quota/rate limit · 6 network/transient · 130 interrupted.
diff --git a/src/skills/references/recipes.md b/src/skills/references/recipes.md
new file mode 100644
index 0000000..ce533dc
--- /dev/null
+++ b/src/skills/references/recipes.md
@@ -0,0 +1,93 @@
+# oytc recipes (agent reference)
+
+Practical patterns for common data-collection tasks. Public-data examples assume an API
+key (`oytc login`); analytics examples require read-only OAuth (`oytc login --oauth`).
+`oytc status --check` validates both when configured.
+
+## Resolve a channel and get its stats
+
+```sh
+oytc channel get @GoogleDevelopers --format json \
+  --columns id,snippet.title,statistics.subscriberCount,statistics.viewCount
+```
+
+Accepts `UC…` IDs, `@handles`, and youtube.com channel URLs. Legacy `/c/name` URLs resolve
+by best-match search and may be wrong for ambiguous names — prefer the @handle.
+
+## Enumerate every public upload of a channel
+
+Cheaper and more complete than search:
+
+```sh
+oytc channel uploads @handle --all --format jsonl \
+  --fields 'items(contentDetails/videoId,snippet/title,snippet/publishedAt),nextPageToken'
+```
+
+Then batch stats (50 IDs per request):
+
+```sh
+oytc video stats ID1 ID2 ID3 … --format json
+```
+
+## Search sparingly
+
+Search has its own small quota bucket (default 100 calls/day). One page of 25–50 results
+is usually enough; avoid `--all` on search.
+
+```sh
+oytc search "query" --type video --page-size 25 --order viewCount \
+  --published-after 2026-01-01T00:00:00Z --format json
+```
+
+## Collect a video's comment threads
+
+```sh
+oytc comment threads --video VIDEO_ID --order relevance --all --limit 500 --format jsonl
+```
+
+Replies beyond the inlined ones: `oytc comment replies TOP_LEVEL_COMMENT_ID`.
+
+## Sample a live stream's chat
+
+```sh
+oytc live-chat stream --video LIVE_VIDEO_ID --limit 200 --format jsonl
+```
+
+Bounded by `--limit`; exits on its own when the chat ends. This is REST polling (documented
+fallback), so expect `pollingIntervalMillis`-paced batches, not per-message latency.
+
+## Analyze your authorized channel (OAuth)
+
+Authorize once, then request normalized JSON rows:
+
+```sh
+oytc login --oauth
+oytc analytics overview --by day --start 2026-01-01 --end 2026-01-31 --format json
+oytc analytics video VIDEO_ID --start 2026-01-01 --end 2026-01-31 --format json
+oytc analytics traffic-sources --sort=-views --format jsonl
+oytc analytics demographics --format json
+```
+
+For custom combinations:
+
+```sh
+oytc analytics report --metrics views,estimatedMinutesWatched \
+  --dimensions day --filters 'video==VIDEO_ID' --sort day --format json
+```
+
+Analytics always targets `channel==MINE`, accepts at most 200 rows per invocation, and
+passes Google's metric/dimension compatibility errors through. It cannot report revenue or
+another user's channel.
+
+## Check AI-training permission for a video (no key, no quota)
+
+```sh
+oytc video trainability VIDEO_ID --format json
+```
+
+## Robust scripting
+
+- Check exit codes: retry only on 6, surface 3 (run `login` or `login --oauth` as hinted)
+  and 5 (quota) to the user.
+- Resume long enumerations with the `nextPageToken` from the JSON envelope + `--page-token`.
+- Keep counter fields as strings; they can exceed float64-safe integers.

From 5b34fa5d35ff74faae62d8aeefcfc94af686e4a5 Mon Sep 17 00:00:00 2001
From: Benjamin Davis 
Date: Sat, 25 Jul 2026 02:21:51 -0700
Subject: [PATCH 4/6] feat(ts): implement the command layer (wave 2)

All 30 leaf commands across 12 groups, wired into root.ts. Three packages
implemented in parallel, each independently verified against the real Go
binary rather than against the spec.

- cli/search, channel, video + the shared fields/validate/render helpers
- cli/playlist, comment, subscription, catalog
- cli/livechat, analyticsCmd, auth, versionUpdate, skillsCmd

Fixes the highest-priority bug the verifiers found: main.ts printed
NOTHING to stderr on failure. Every tagged error carries
`Runtime.errorReported = false` to suppress the runtime's multi-line
reporter, but the single-line printer that was supposed to replace it
was only ever described in a comment. Exit codes were right and the
message was absent, so a user saw a silent failure.

main.ts now installs that printer and translates the CLI framework's
parse errors into Go's wording and exit code (the framework exits 1 and
uses different phrasing). Two framework details worth recording: its
unknown-subcommand tag is spelled `UnknownSubcomand` with one "m", and
`--limit -1` lexes as two flags rather than a negative value, so the
underlying range error is reported instead of the lexer artifact.

Also corrects `--timeout must be greater than zero` to Go's
`--timeout must be positive`, and updates the two tests that pinned the
old wording.

Verified against /tmp/oytc-ref:

- 9 of 9 validation errors match exactly, message and exit code
- `status` is byte-identical in all four formats, including the G1 quirk
  where scopes render as ["https://..."] with brackets rather than
  comma-joined, because Go reaches them through a different code path
- `status` leaks no secret in any format, checked with distinctive
  fixture values for the access token, refresh token and client secret

Verifier findings fixed in the packages themselves include `video
trainability` mishandling every non-object response body: a `null` body
succeeds in Go (exit 0), and other scalars produce an OperationalError
at exit 6, where the port returned exit 4 with invented text. The
pre-existing test asserted the buggy behavior.

2136 tests pass; TypeScript 7 typechecks clean.

Co-Authored-By: Claude Opus 5 (1M context) 
---
 src/cli/analyticsCmd.test.ts   | 831 +++++++++++++++++++++++++++++
 src/cli/analyticsCmd.ts        | 381 +++++++++++++-
 src/cli/auth.test.ts           | 857 ++++++++++++++++++++++++++++++
 src/cli/auth.ts                | 551 ++++++++++++++++++-
 src/cli/catalog.test.ts        | 239 +++++++++
 src/cli/catalog.ts             | 162 +++++-
 src/cli/channel.test.ts        | 603 +++++++++++++++++++++
 src/cli/channel.ts             | 334 +++++++++++-
 src/cli/comment.test.ts        | 434 +++++++++++++++
 src/cli/comment.ts             | 191 ++++++-
 src/cli/fields.test.ts         | 272 ++++++++++
 src/cli/fields.ts              | 213 +++++++-
 src/cli/globals.ts             |   2 +-
 src/cli/harness.testutil.ts    | 274 ++++++++++
 src/cli/livechat.test.ts       | 937 +++++++++++++++++++++++++++++++++
 src/cli/livechat.ts            | 545 ++++++++++++++++++-
 src/cli/p8aHarness.testutil.ts | 397 ++++++++++++++
 src/cli/playlist.test.ts       | 643 ++++++++++++++++++++++
 src/cli/playlist.ts            | 622 +++++++++++++++++++++-
 src/cli/render.test.ts         | 278 ++++++++++
 src/cli/render.ts              | 103 +++-
 src/cli/root.ts                |  35 +-
 src/cli/search.test.ts         | 659 +++++++++++++++++++++++
 src/cli/search.ts              | 293 ++++++++++-
 src/cli/skillsCmd.test.ts      | 307 +++++++++++
 src/cli/skillsCmd.ts           | 135 ++++-
 src/cli/subscription.test.ts   | 283 ++++++++++
 src/cli/subscription.ts        | 108 +++-
 src/cli/validate.test.ts       | 416 +++++++++++++++
 src/cli/validate.ts            | 544 ++++++++++++++++++-
 src/cli/versionUpdate.test.ts  | 398 ++++++++++++++
 src/cli/versionUpdate.ts       | 190 ++++++-
 src/cli/video.test.ts          | 668 +++++++++++++++++++++++
 src/cli/video.ts               | 281 +++++++++-
 src/main.ts                    | 150 +++++-
 35 files changed, 13293 insertions(+), 43 deletions(-)
 create mode 100644 src/cli/analyticsCmd.test.ts
 create mode 100644 src/cli/auth.test.ts
 create mode 100644 src/cli/catalog.test.ts
 create mode 100644 src/cli/channel.test.ts
 create mode 100644 src/cli/comment.test.ts
 create mode 100644 src/cli/fields.test.ts
 create mode 100644 src/cli/harness.testutil.ts
 create mode 100644 src/cli/livechat.test.ts
 create mode 100644 src/cli/p8aHarness.testutil.ts
 create mode 100644 src/cli/playlist.test.ts
 create mode 100644 src/cli/render.test.ts
 create mode 100644 src/cli/search.test.ts
 create mode 100644 src/cli/skillsCmd.test.ts
 create mode 100644 src/cli/subscription.test.ts
 create mode 100644 src/cli/validate.test.ts
 create mode 100644 src/cli/versionUpdate.test.ts
 create mode 100644 src/cli/video.test.ts

diff --git a/src/cli/analyticsCmd.test.ts b/src/cli/analyticsCmd.test.ts
new file mode 100644
index 0000000..70691fa
--- /dev/null
+++ b/src/cli/analyticsCmd.test.ts
@@ -0,0 +1,831 @@
+/**
+ * `analytics {report,overview,video,traffic-sources,demographics}` tests.
+ *
+ * The five presets are asserted against the exact metric/dimension/filter
+ * strings the Analytics API receives, because those ARE the contract — a
+ * preset that drops a metric produces a report that is quietly wrong rather
+ * than one that fails.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Effect, Exit, Layer, Sink, Stdio } from "effect"
+import { Command } from "../effect.ts"
+import {
+  ApiError,
+  exitCodeFor,
+  MissingOAuthError,
+  OperationalError,
+  UsageError,
+  type OytcError
+} from "../domain/errors.ts"
+import type { AnalyticsResponse } from "../schema/analytics.ts"
+import { rawNumber } from "../json/value.ts"
+import { makeRendererWith } from "../impl/renderer.ts"
+import { addUtcDays, formatDateOnly, MAX_RESULTS } from "../impl/analyticsApi.ts"
+import {
+  AnalyticsApi,
+  AppOptions,
+  CredentialStore,
+  Renderer,
+  type AnalyticsQuery,
+  type AppOptionsShape,
+  type Credentials,
+  type OutputFormat,
+  type StoredOAuth
+} from "../services/index.ts"
+import { globalFlags } from "./flags.ts"
+import {
+  analyticsCommand,
+  csvValues,
+  DEFAULT_RANGE,
+  mergeFilters,
+  parseDateOnly,
+  validateAnalyticsDates,
+  validateEnum
+} from "./analyticsCmd.ts"
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const storedOAuth: StoredOAuth = {
+  clientId: "cid",
+  clientSecret: "secret",
+  accessToken: "at",
+  refreshToken: "rt",
+  expiry: "2027-01-01T00:00:00Z",
+  scopes: ["https://www.googleapis.com/auth/yt-analytics.readonly"]
+}
+
+const credentials = (): Credentials => ({
+  key: "",
+  source: "",
+  oauth: storedOAuth,
+  path: "/tmp/auth.json"
+})
+
+/**
+ * Credentials with no OAuth block. A separate constructor rather than an
+ * optional parameter: `credentials(undefined)` would trigger the default
+ * parameter and silently hand back a CONFIGURED record, so the "no OAuth"
+ * tests would assert nothing.
+ */
+const credentialsWithoutOAuth = (): Credentials => ({
+  key: "",
+  source: "",
+  oauth: undefined,
+  path: "/tmp/auth.json"
+})
+
+const report: AnalyticsResponse = {
+  columnHeaders: [{ name: "views" }],
+  rows: [[rawNumber("42")]]
+}
+
+interface RunOptions {
+  readonly credentials?: Credentials | undefined
+  readonly format?: OutputFormat | undefined
+  readonly columns?: ReadonlyArray | undefined
+  readonly quiet?: boolean | undefined
+  readonly reportError?: OytcError | undefined
+  readonly response?: AnalyticsResponse | undefined
+}
+
+const runCommand = async (
+  argv: ReadonlyArray,
+  options: RunOptions = {}
+): Promise<{
+  readonly stdout: string
+  readonly stderr: string
+  readonly exit: Exit.Exit
+  readonly queries: ReadonlyArray
+}> => {
+  const out: Array = []
+  const err: Array = []
+  const queries: Array = []
+  const decode = (i: string | Uint8Array): string =>
+    typeof i === "string" ? i : new TextDecoder().decode(i)
+
+  const stdio = Stdio.layerTest({
+    stdout: () => Sink.forEach((i: string | Uint8Array) => Effect.sync(() => out.push(decode(i)))),
+    stderr: () => Sink.forEach((i: string | Uint8Array) => Effect.sync(() => err.push(decode(i))))
+  })
+
+  const appOptions: AppOptionsShape = {
+    format: options.format ?? "json",
+    columns: options.columns ?? [],
+    noHeader: false,
+    quiet: options.quiet ?? false,
+    timeoutMillis: 20_000,
+    isOutputTTY: false
+  }
+
+  const layers = Layer.mergeAll(
+    Layer.succeed(AppOptions, appOptions),
+    Layer.succeed(CredentialStore, {
+      dir: Effect.succeed("/tmp"),
+      path: Effect.succeed("/tmp/auth.json"),
+      load: Effect.succeed(options.credentials ?? credentials()),
+      save: () => Effect.succeed("/tmp/auth.json"),
+      saveOAuth: () => Effect.succeed("/tmp/auth.json"),
+      saveRefreshedOAuth: () => Effect.succeed(true),
+      clearOAuth: Effect.succeed("/tmp/auth.json"),
+      remove: Effect.succeed({ path: "/tmp/auth.json", removed: true }),
+      fingerprint: () => "sha256:deadbeef0000",
+      envKeySet: Effect.succeed(false),
+      oauthBootstrap: Effect.succeed(["", ""] as const)
+    }),
+    Layer.succeed(AnalyticsApi, {
+      report: (query: AnalyticsQuery) =>
+        Effect.suspend(() => {
+          queries.push(query)
+          return options.reportError === undefined
+            ? Effect.succeed(options.response ?? report)
+            : Effect.fail(options.reportError)
+        }),
+      normalize: () => []
+    }),
+    Layer.succeed(
+      Renderer,
+      makeRendererWith((text) => Effect.sync(() => void out.push(text)))
+    )
+  )
+
+  const root = Command.make("oytc").pipe(
+    Command.withSharedFlags(globalFlags),
+    Command.withSubcommands([analyticsCommand])
+  )
+  const exit = await Effect.runPromiseExit(
+    Command.runWith(root, { version: "test" })(argv).pipe(
+      Effect.provide(Layer.mergeAll(layers, stdio))
+    ) as Effect.Effect
+  )
+  return { stdout: out.join(""), stderr: err.join(""), exit, queries }
+}
+
+const failureOf = (exit: Exit.Exit): OytcError => {
+  if (Exit.isSuccess(exit)) throw new Error("expected a failure")
+  const found = exit.cause.reasons.find((r) => r._tag === "Fail")
+  if (found === undefined) throw new Error(`no Fail reason: ${String(exit.cause)}`)
+  return (found as { readonly error: OytcError }).error
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+describe("csvValues", () => {
+  test("splits, trims and drops empties", () => {
+    expect(csvValues(" a , b ,, c ")).toEqual(["a", "b", "c"])
+  })
+
+  test("a whitespace-only value yields nothing", () => {
+    expect(csvValues(" , ")).toEqual([])
+    expect(csvValues("")).toEqual([])
+  })
+
+  test("a trailing comma contributes no entry", () => {
+    expect(csvValues("views,")).toEqual(["views"])
+  })
+})
+
+describe("validateEnum", () => {
+  test("the empty string always passes", () => {
+    expect(validateEnum("--by", "", ["day", "month"])).toBeUndefined()
+  })
+
+  test("a listed value passes", () => {
+    expect(validateEnum("--by", "day", ["day", "month"])).toBeUndefined()
+  })
+
+  test("an unlisted value fails with Go's comma-space message", () => {
+    expect(validateEnum("--by", "week", ["day", "month"])?.message).toBe(
+      "--by must be one of: day, month"
+    )
+  })
+
+  test("the check is case-sensitive", () => {
+    expect(validateEnum("--by", "Day", ["day", "month"])).toBeDefined()
+  })
+})
+
+describe("parseDateOnly", () => {
+  test("accepts a canonical date", () => {
+    expect(parseDateOnly("2026-01-05")).toBeInstanceOf(Date)
+  })
+
+  test("REJECTS a non-canonical date Go's parser would accept", () => {
+    // 2026-1-05 parses in Go, but reformatting yields 2026-01-05 != input.
+    expect(parseDateOnly("2026-1-05")).toBeUndefined()
+    expect(parseDateOnly("2026-01-5")).toBeUndefined()
+  })
+
+  test("rejects an out-of-range day rather than rolling it over", () => {
+    expect(parseDateOnly("2026-02-31")).toBeUndefined()
+    expect(parseDateOnly("2026-13-01")).toBeUndefined()
+  })
+
+  test("accepts a real leap day and rejects a fake one", () => {
+    expect(parseDateOnly("2024-02-29")).toBeInstanceOf(Date)
+    expect(parseDateOnly("2026-02-29")).toBeUndefined()
+  })
+
+  test("rejects a timestamp or a bare year", () => {
+    expect(parseDateOnly("2026-01-05T00:00:00Z")).toBeUndefined()
+    expect(parseDateOnly("2026")).toBeUndefined()
+    expect(parseDateOnly("")).toBeUndefined()
+  })
+})
+
+describe("validateAnalyticsDates", () => {
+  test("a bad start reports --start first", () => {
+    expect(validateAnalyticsDates("bad", "also-bad")?.message).toBe(
+      "--start must use YYYY-MM-DD"
+    )
+  })
+
+  test("a bad end is reported once start is valid", () => {
+    expect(validateAnalyticsDates("2026-01-01", "bad")?.message).toBe(
+      "--end must use YYYY-MM-DD"
+    )
+  })
+
+  test("start after end is rejected", () => {
+    expect(validateAnalyticsDates("2026-02-01", "2026-01-01")?.message).toBe(
+      "--start cannot be after --end"
+    )
+  })
+
+  test("start equal to end is allowed", () => {
+    expect(validateAnalyticsDates("2026-01-01", "2026-01-01")).toBeUndefined()
+  })
+})
+
+describe("mergeFilters", () => {
+  test("joins with a semicolon, built-in first", () => {
+    expect(mergeFilters("video==ID", "country==US")).toBe("video==ID;country==US")
+  })
+
+  test("either side alone passes through", () => {
+    expect(mergeFilters("video==ID", "")).toBe("video==ID")
+    expect(mergeFilters("", "country==US")).toBe("country==US")
+  })
+
+  test("both empty stays empty", () => {
+    expect(mergeFilters("", "")).toBe("")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Date defaults
+// ---------------------------------------------------------------------------
+
+describe("the default date window", () => {
+  test("is 28 INCLUSIVE UTC days ending yesterday", () => {
+    const end = new Date(`${DEFAULT_RANGE.end}T00:00:00Z`)
+    const start = new Date(`${DEFAULT_RANGE.start}T00:00:00Z`)
+    const days = (end.getTime() - start.getTime()) / 86_400_000
+    // 27 days apart == 28 inclusive days.
+    expect(days).toBe(27)
+  })
+
+  test("ends yesterday in UTC, excluding today's incomplete data", () => {
+    const yesterday = formatDateOnly(addUtcDays(new Date(), -1))
+    expect(DEFAULT_RANGE.end).toBe(yesterday)
+  })
+
+  test("is materialized once, so repeated reads are identical", () => {
+    // The whole point of construction-time materialization: the value is a
+    // constant, not a function re-evaluated per invocation.
+    const first = { ...DEFAULT_RANGE }
+    expect(DEFAULT_RANGE).toEqual(first)
+  })
+
+  test("reaches the API as the query's start and end dates", async () => {
+    const { queries } = await runCommand(["analytics", "overview"])
+    expect(queries[0]!.startDate).toBe(DEFAULT_RANGE.start)
+    expect(queries[0]!.endDate).toBe(DEFAULT_RANGE.end)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// report
+// ---------------------------------------------------------------------------
+
+describe("analytics report", () => {
+  test("--metrics is required", async () => {
+    const { exit, queries } = await runCommand(["analytics", "report"])
+    const error = failureOf(exit)
+    expect(error).toBeInstanceOf(UsageError)
+    expect(error.message).toBe("--metrics is required")
+    expect(queries).toEqual([])
+  })
+
+  test("a whitespace-only --metrics also triggers the required error", async () => {
+    const { exit } = await runCommand(["analytics", "report", "--metrics= , "])
+    expect(failureOf(exit).message).toBe("--metrics is required")
+  })
+
+  test("the required check runs BEFORE the date check", async () => {
+    const { exit } = await runCommand(["analytics", "report", "--start=bogus"])
+    expect(failureOf(exit).message).toBe("--metrics is required")
+  })
+
+  test("metrics and dimensions are comma-joined for the API", async () => {
+    const { queries } = await runCommand([
+      "analytics",
+      "report",
+      "--metrics= views , likes ",
+      "--dimensions=day"
+    ])
+    expect(queries[0]!.metrics).toBe("views,likes")
+    expect(queries[0]!.dimensions).toBe("day")
+  })
+
+  test("the default columns are dimensions first, then metrics", async () => {
+    const { stdout } = await runCommand(
+      ["analytics", "report", "--metrics=views,likes", "--dimensions=day"],
+      { format: "tsv", response: { columnHeaders: [], rows: [] } }
+    )
+    expect(stdout.split("\n")[0]).toBe("DAY\tVIEWS\tLIKES")
+  })
+
+  test("--filters passes straight through", async () => {
+    // Space-separated: see the FRAMEWORK LEXER BUG suite below for why the
+    // `--filters=country==US` spelling cannot be used here.
+    const { queries } = await runCommand([
+      "analytics",
+      "report",
+      "--metrics=views",
+      "--filters",
+      "country==US"
+    ])
+    expect(queries[0]!.filters).toBe("country==US")
+  })
+
+  test("--sort passes straight through", async () => {
+    const { queries } = await runCommand([
+      "analytics",
+      "report",
+      "--metrics=views",
+      "--sort=-views"
+    ])
+    expect(queries[0]!.sort).toBe("-views")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// The presets
+// ---------------------------------------------------------------------------
+
+describe("analytics overview", () => {
+  test("sends the five fixed metrics and no dimension by default", async () => {
+    const { queries } = await runCommand(["analytics", "overview"])
+    expect(queries[0]!.metrics).toBe(
+      "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained"
+    )
+    expect(queries[0]!.dimensions).toBe("")
+  })
+
+  test("--by day adds the dimension", async () => {
+    const { queries } = await runCommand(["analytics", "overview", "--by=day"])
+    expect(queries[0]!.dimensions).toBe("day")
+  })
+
+  test("--by month adds the dimension", async () => {
+    const { queries } = await runCommand(["analytics", "overview", "--by=month"])
+    expect(queries[0]!.dimensions).toBe("month")
+  })
+
+  test("an invalid --by is rejected before any request", async () => {
+    const { exit, queries } = await runCommand(["analytics", "overview", "--by=week"])
+    expect(failureOf(exit).message).toBe("--by must be one of: day, month")
+    expect(queries).toEqual([])
+  })
+
+  test("the --by check runs before the date check", async () => {
+    const { exit } = await runCommand([
+      "analytics",
+      "overview",
+      "--by=week",
+      "--start=bogus"
+    ])
+    expect(failureOf(exit).message).toBe("--by must be one of: day, month")
+  })
+
+  test("--by puts the dimension first in the default columns", async () => {
+    const { stdout } = await runCommand(["analytics", "overview", "--by=day"], {
+      format: "tsv",
+      response: { columnHeaders: [], rows: [] }
+    })
+    expect(stdout.split("\n")[0]!.split("\t")[0]).toBe("DAY")
+  })
+})
+
+describe("analytics video", () => {
+  test("sets the built-in video filter from the positional argument", async () => {
+    const { queries } = await runCommand(["analytics", "video", "VID123"])
+    expect(queries[0]!.filters).toBe("video==VID123")
+  })
+
+  test("MERGES --filters after the built-in one, semicolon-separated", async () => {
+    const { queries } = await runCommand([
+      "analytics",
+      "video",
+      "VID123",
+      "--filters",
+      "country==US"
+    ])
+    expect(queries[0]!.filters).toBe("video==VID123;country==US")
+  })
+
+  test("sends the six fixed metrics and no dimensions", async () => {
+    const { queries } = await runCommand(["analytics", "video", "VID123"])
+    expect(queries[0]!.metrics).toBe(
+      "views,estimatedMinutesWatched,averageViewDuration,likes,comments,subscribersGained"
+    )
+    expect(queries[0]!.dimensions).toBe("")
+  })
+
+  test("a missing VIDEO_ID is a parse failure, not a request", async () => {
+    const { queries, exit } = await runCommand(["analytics", "video"])
+    expect(Exit.isFailure(exit)).toBe(true)
+    expect(queries).toEqual([])
+  })
+})
+
+describe("analytics traffic-sources", () => {
+  test("sends the fixed metric/dimension pair", async () => {
+    const { queries } = await runCommand(["analytics", "traffic-sources"])
+    expect(queries[0]!.metrics).toBe("views,estimatedMinutesWatched")
+    expect(queries[0]!.dimensions).toBe("insightTrafficSourceType")
+  })
+
+  test("--filters is used as-is (no built-in filter to merge)", async () => {
+    const { queries } = await runCommand([
+      "analytics",
+      "traffic-sources",
+      "--filters",
+      "country==US"
+    ])
+    expect(queries[0]!.filters).toBe("country==US")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// FRAMEWORK LEXER BUG — not a defect in this package
+// ---------------------------------------------------------------------------
+
+/**
+ * The CLI framework's lexer splits `--flag=value` with
+ * `arg.slice(2).split("=", 2)`. JavaScript's `split` with a limit DISCARDS the
+ * remainder rather than returning it as the final element, which is what Go's
+ * `strings.SplitN(s, "=", 2)` does. So every `=` after the first TRUNCATES the
+ * value:
+ *
+ *     "--filters=country==US".slice(2).split("=", 2)  // ["filters", "country"]
+ *
+ * `Analytics` filter expressions are all of the form `dimension==value`, so
+ * this silently corrupts the single most likely way a user would write the
+ * flag: `--filters=country==US` reaches the API as `country`, which Google
+ * answers with a 400 rather than an obviously wrong report.
+ *
+ * The fix belongs in the framework's own `cli/internal/lexer.js`
+ * (`indexOf("=")` + two slices, exactly as the short-flag branch a few lines
+ * below it already does), so this package cannot fix it. These tests pin the
+ * CURRENT behaviour so the eventual upstream fix is detected rather than
+ * silently changing what the CLI does.
+ *
+ * Affected across the whole CLI: `--filters` (analytics), `--fields` (any
+ * selector containing `=`), and any flag whose value may embed `=`. The
+ * space-separated spelling (`--filters country==US`) is unaffected and is what
+ * every other test here uses.
+ */
+describe("KNOWN FRAMEWORK BUG: --flag=value truncates at the second '='", () => {
+  test("the lexer's own splitting drops everything after the second =", () => {
+    const [name, value] = "--filters=country==US".slice(2).split("=", 2)
+    expect(name).toBe("filters")
+    // Go's SplitN would give "country==US"; JS's split limit gives "country".
+    expect(value).toBe("country")
+  })
+
+  test("end to end, --filters=a==b reaches the API truncated", async () => {
+    const { queries } = await runCommand([
+      "analytics",
+      "traffic-sources",
+      "--filters=country==US"
+    ])
+    // ASSERTING THE BUG. When the framework is fixed this flips to
+    // "country==US" and the test fails, which is the intent.
+    expect(queries[0]!.filters).toBe("country")
+  })
+
+  test("the space-separated spelling is correct and is the workaround", async () => {
+    const { queries } = await runCommand([
+      "analytics",
+      "traffic-sources",
+      "--filters",
+      "country==US"
+    ])
+    expect(queries[0]!.filters).toBe("country==US")
+  })
+
+  test("a value with no '=' is unaffected by the bug", async () => {
+    const { queries } = await runCommand(["analytics", "overview", "--by=day"])
+    expect(queries[0]!.dimensions).toBe("day")
+  })
+})
+
+/**
+ * KNOWN FRAMEWORK BUG #2 — a flag VALUE that starts with `-`, in the
+ * space-separated spelling, is lexed as a cluster of short flags instead of as
+ * the value of the preceding flag.
+ *
+ * This is the same root cause as the `--limit -1` case already documented in
+ * `playlist.test.ts`, but with a far worse failure mode. For `--limit -1` the
+ * lexer reports "Missing value for flag --limit" and the run fails loudly. For
+ * `--sort -views` the `-v` at the head of the cluster matches the framework's
+ * built-in `--version, -v`, which SHORT-CIRCUITS the whole run: the CLI prints
+ * its version banner and exits **0**, having executed no handler and issued no
+ * request.
+ *
+ * That is the dangerous shape — a silent success. `oytc analytics report
+ * --metrics views --sort -views` looks like it worked (exit 0, output on
+ * stdout) while producing no report at all, so a script piping it to `jq` sees
+ * a version string rather than data and a `set -e` pipeline does not trip.
+ * Go's pflag consumes the next argv token unconditionally for a string flag,
+ * so the real binary accepts `--sort -views` and sorts descending.
+ *
+ * Not fixable from this package: the defect is in the CLI lexer
+ * (`effect/unstable/cli/internal/lexer.js`), which treats any `-x…` token as
+ * flags regardless of whether the previous token was a value-taking flag.
+ * Pinned here so the day it is fixed these tests fail and the workaround notes
+ * can be removed. Workaround: the `=` spelling (`--sort=-views`), which is
+ * lexed correctly for values that contain no second `=`.
+ */
+describe("KNOWN FRAMEWORK BUG: a `-`-leading flag value is lexed as short flags", () => {
+  test("--sort -views silently succeeds without running the command", async () => {
+    const { exit, queries, stdout } = await runCommand([
+      "analytics",
+      "report",
+      "--metrics",
+      "views",
+      "--sort",
+      "-views"
+    ])
+    // ASSERTING THE BUG: a SUCCESS exit with no request issued and nothing
+    // rendered. The framework wrote its version banner straight to the real
+    // console rather than through the injected `Stdio`, so it is not visible
+    // here — which is itself part of why the failure is so quiet.
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(queries).toEqual([])
+    expect(stdout).toBe("")
+  })
+
+  test("the `=` spelling is the workaround and does reach the API", async () => {
+    const { queries } = await runCommand([
+      "analytics",
+      "report",
+      "--metrics",
+      "views",
+      "--sort=-views"
+    ])
+    expect(queries[0]!.sort).toBe("-views")
+  })
+
+  test("a value with no leading dash is unaffected", async () => {
+    const { queries } = await runCommand([
+      "analytics",
+      "report",
+      "--metrics",
+      "views",
+      "--sort",
+      "views"
+    ])
+    expect(queries[0]!.sort).toBe("views")
+  })
+})
+
+describe("analytics demographics", () => {
+  test("sends viewerPercentage by ageGroup and gender", async () => {
+    const { queries } = await runCommand(["analytics", "demographics"])
+    expect(queries[0]!.metrics).toBe("viewerPercentage")
+    expect(queries[0]!.dimensions).toBe("ageGroup,gender")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Shared validation
+// ---------------------------------------------------------------------------
+
+describe("shared analytics validation", () => {
+  test("a bad --start is rejected before any request", async () => {
+    const { exit, queries } = await runCommand([
+      "analytics",
+      "overview",
+      "--start=2026-1-05"
+    ])
+    expect(failureOf(exit).message).toBe("--start must use YYYY-MM-DD")
+    expect(queries).toEqual([])
+  })
+
+  test("a bad --end is rejected", async () => {
+    const { exit } = await runCommand(["analytics", "overview", "--end=nope"])
+    expect(failureOf(exit).message).toBe("--end must use YYYY-MM-DD")
+  })
+
+  test("start after end is rejected", async () => {
+    const { exit } = await runCommand([
+      "analytics",
+      "overview",
+      "--start=2026-02-01",
+      "--end=2026-01-01"
+    ])
+    expect(failureOf(exit).message).toBe("--start cannot be after --end")
+  })
+
+  test("--limit below 1 is rejected", async () => {
+    const { exit, queries } = await runCommand(["analytics", "overview", "--limit=0"])
+    expect(failureOf(exit).message).toBe(`--limit must be between 1 and ${MAX_RESULTS}`)
+    expect(queries).toEqual([])
+  })
+
+  test("--limit above 200 is rejected", async () => {
+    const { exit } = await runCommand(["analytics", "overview", "--limit=201"])
+    expect(failureOf(exit).message).toBe("--limit must be between 1 and 200")
+  })
+
+  test("--limit at both bounds is accepted", async () => {
+    expect(Exit.isSuccess((await runCommand(["analytics", "overview", "--limit=1"])).exit)).toBe(
+      true
+    )
+    expect(
+      Exit.isSuccess((await runCommand(["analytics", "overview", "--limit=200"])).exit)
+    ).toBe(true)
+  })
+
+  test("the default --limit is MaxResults", async () => {
+    const { queries } = await runCommand(["analytics", "overview"])
+    expect(queries[0]!.limit).toBe(MAX_RESULTS)
+  })
+
+  test("the date check runs before the limit check", async () => {
+    const { exit } = await runCommand([
+      "analytics",
+      "overview",
+      "--start=bogus",
+      "--limit=999"
+    ])
+    expect(failureOf(exit).message).toBe("--start must use YYYY-MM-DD")
+  })
+
+  test("the limit check runs before the credential load", async () => {
+    const { exit } = await runCommand(["analytics", "overview", "--limit=0"], {
+      credentials: credentialsWithoutOAuth()
+    })
+    expect(failureOf(exit)).toBeInstanceOf(UsageError)
+  })
+
+  test("no stored OAuth fails with the analytics suffix, exit 3", async () => {
+    const { exit, queries } = await runCommand(["analytics", "overview"], {
+      credentials: credentialsWithoutOAuth()
+    })
+    const error = failureOf(exit)
+    expect(error).toBeInstanceOf(MissingOAuthError)
+    expect(error.message).toBe(
+      "no OAuth credentials configured; run 'oytc login --oauth'; analytics requires OAuth"
+    )
+    expect(queries).toEqual([])
+  })
+
+  test("an upstream failure propagates", async () => {
+    const boom = new OperationalError({ message: "network down" })
+    const { exit } = await runCommand(["analytics", "overview"], { reportError: boom })
+    expect(failureOf(exit)).toBe(boom)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// oauthAuthHint on the report failure
+//
+// Go's `runAnalytics` ends with `return oauthAuthHint(err)`, so EVERY analytics
+// failure is routed through the same helper `status --check` uses. Dropping it
+// is invisible on the happy path and on 5xx/quota errors, and shows up only on
+// the two failures that matter most: an expired grant and a missing scope. In
+// both cases the user needs to be told to re-run `oytc login --oauth`.
+// ---------------------------------------------------------------------------
+
+describe("analytics failures carry the OAuth re-login hint (Go: oauthAuthHint)", () => {
+  const apiError = (httpStatus: number, reasons: ReadonlyArray, apiMessage: string) =>
+    new ApiError({ httpStatus, code: httpStatus, apiMessage, reasons })
+
+  test("a 401 becomes the re-login hint, exit 3", async () => {
+    const { exit } = await runCommand(["analytics", "report", "--metrics=views"], {
+      reportError: apiError(401, ["authError"], "Invalid Credentials")
+    })
+    const error = failureOf(exit)
+    expect(error.message).toBe(
+      "OAuth authorization failed; re-run 'oytc login --oauth': " +
+        "YouTube API error (401, authError): Invalid Credentials"
+    )
+    expect(exitCodeFor(error)).toBe(3)
+  })
+
+  test("insufficientPermissions becomes the scopes hint, exit 3", async () => {
+    const { exit } = await runCommand(["analytics", "overview"], {
+      reportError: apiError(403, ["insufficientPermissions"], "Insufficient Permission")
+    })
+    const error = failureOf(exit)
+    expect(error.message).toBe(
+      "OAuth scopes are insufficient; re-run 'oytc login --oauth': " +
+        "YouTube API error (403, insufficientPermissions): Insufficient Permission"
+    )
+    expect(exitCodeFor(error)).toBe(3)
+  })
+
+  test("an invalid_grant token failure becomes the re-login hint, exit 3", async () => {
+    const { exit } = await runCommand(["analytics", "video", "VID"], {
+      reportError: new OperationalError({ message: "oauth2: cannot fetch token: invalid_grant" })
+    })
+    const error = failureOf(exit)
+    expect(error.message).toStartWith("OAuth authorization failed; re-run 'oytc login --oauth': ")
+    expect(exitCodeFor(error)).toBe(3)
+  })
+
+  // The other half of the contract: oauthAuthHint returns non-matching errors
+  // UNCHANGED, so a 5xx must not gain a hint and must keep its exit code.
+  test("a 5xx passes through unchanged, exit 6", async () => {
+    const boom = apiError(500, ["backendError"], "Backend Error")
+    const { exit } = await runCommand(["analytics", "demographics"], { reportError: boom })
+    expect(failureOf(exit)).toBe(boom)
+    expect(exitCodeFor(failureOf(exit))).toBe(6)
+  })
+
+  test("a quota error passes through unchanged, exit 5", async () => {
+    const boom = apiError(429, ["quotaExceeded"], "Quota exceeded")
+    const { exit } = await runCommand(["analytics", "traffic-sources"], { reportError: boom })
+    expect(failureOf(exit)).toBe(boom)
+    expect(exitCodeFor(failureOf(exit))).toBe(5)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+describe("analytics rendering", () => {
+  test("the envelope always reports exactly one request", async () => {
+    const { stdout } = await runCommand(["analytics", "overview"], { format: "json" })
+    expect(stdout).toContain('"requests": 1')
+  })
+
+  test("the table summary lands on stderr", async () => {
+    const { stderr } = await runCommand(["analytics", "overview"], { format: "table" })
+    expect(stderr).toBe("1 item(s), 1 request(s)\n")
+  })
+
+  test("--quiet suppresses the summary", async () => {
+    const { stderr } = await runCommand(["analytics", "overview"], {
+      format: "table",
+      quiet: true
+    })
+    expect(stderr).toBe("")
+  })
+
+  test("a non-table format never emits the summary", async () => {
+    const { stderr } = await runCommand(["analytics", "overview"], { format: "json" })
+    expect(stderr).toBe("")
+  })
+
+  test("--columns overrides the preset column list", async () => {
+    const { stdout } = await runCommand(["analytics", "overview"], {
+      format: "tsv",
+      columns: ["views"]
+    })
+    expect(stdout.split("\n")[0]).toBe("VIEWS")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+describe("command registration", () => {
+  test("the group carries Go's description and has no handler", () => {
+    expect(analyticsCommand.name).toBe("analytics")
+    expect(analyticsCommand.description).toBe(
+      "Read analytics for your authorized YouTube channel (OAuth required)"
+    )
+  })
+
+  test("all five subcommands are registered under Go's names", () => {
+    const names = analyticsCommand.subcommands.flatMap((g) => g.commands.map((c) => c.name))
+    expect(names).toEqual([
+      "report",
+      "overview",
+      "video",
+      "traffic-sources",
+      "demographics"
+    ])
+  })
+})
diff --git a/src/cli/analyticsCmd.ts b/src/cli/analyticsCmd.ts
index ca14f9a..c59ec5c 100644
--- a/src/cli/analyticsCmd.ts
+++ b/src/cli/analyticsCmd.ts
@@ -1,2 +1,379 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `analytics {report,overview,video,traffic-sources,demographics}` — the port
+ * of `internal/cli/analytics.go`.
+ *
+ * Four subcommands are fixed presets over one shared runner; only `report`
+ * takes user-supplied metrics and dimensions. All five carry the same
+ * `--start/--end/--filters/--sort/--limit` flag set.
+ *
+ * ## The date defaults are materialized at CONSTRUCTION time
+ *
+ * Go computed `end = now().UTC().AddDate(0,0,-1)` and `start = end - 27 days`
+ * inside `addAnalyticsFlags`, i.e. while building the command tree, and passed
+ * the formatted strings as the flag defaults. Two consequences the port must
+ * keep:
+ *
+ *   - the literal dates appear in `--help` output;
+ *   - a long-running process would keep the window it started with.
+ *
+ * `DEFAULT_RANGE` is therefore a module-level constant, evaluated once when the
+ * command module is first imported. The window is 28 INCLUSIVE days ending
+ * yesterday (`end - 27`, not `end - 28`) and is computed in UTC, so a machine
+ * in UTC+13 reports the same window as one in UTC-8.
+ *
+ * ## Filter merging
+ *
+ * `analytics video ` sets a built-in filter `video==`. When `--filters`
+ * is ALSO supplied the two are joined with a semicolon, built-in first:
+ * `video==ID;`. For the other four subcommands the filter is just
+ * `--filters`. An empty built-in filter and an empty user filter both collapse
+ * to no `filters` parameter at all.
+ *
+ * ## Validation order
+ *
+ * Subcommand-specific check (`--metrics` required / `--by` enum) runs FIRST,
+ * then dates, then `--limit`, then the credential load. Every one of those
+ * precedes any network traffic. The date check is a round-trip reformat, so
+ * `2026-1-05` is rejected even though Go's parser accepts it — the reformatted
+ * value differs from the input.
+ */
+
+import { Effect, Stdio, Stream } from "effect"
+import { Command, Flag, Argument } from "../effect.ts"
+import { MissingOAuthError, OperationalError, UsageError } from "../domain/errors.ts"
+import type { ListResult } from "../domain/listResult.ts"
+import { oauthAuthHint } from "./auth.ts"
+import {
+  analyticsListResult,
+  defaultDateRange,
+  MAX_RESULTS
+} from "../impl/analyticsApi.ts"
+import {
+  analyticsDemographicsColumns,
+  analyticsOverviewColumns,
+  analyticsOverviewMetrics,
+  analyticsReportColumns,
+  analyticsTrafficSourcesColumns,
+  analyticsVideoColumns
+} from "../output/columns.ts"
+import {
+  AnalyticsApi,
+  AppOptions,
+  CredentialStore,
+  Renderer,
+  type AppOptionsShape
+} from "../services/index.ts"
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Go's `renderResult`: render, then a one-line stderr summary but ONLY for
+ * `--format table` and only when `--quiet` is absent.
+ *
+ * P8a owns `src/cli/render.ts` and will export the shared version of this; it
+ * is still a stub, so an identical local copy lives here. Analytics results
+ * always carry `nextPageToken === ""` (there is no token pagination on the
+ * reports endpoint), so the "more available" clause is unreachable — it is
+ * kept anyway so the two implementations can be diffed literally.
+ */
+const renderResult = (
+  result: ListResult,
+  defaultColumns: ReadonlyArray,
+  options: AppOptionsShape
+) =>
+  Effect.gen(function* () {
+    const renderer = yield* Renderer
+    yield* renderer.render(result, {
+      format: options.format,
+      columns: options.columns.length > 0 ? options.columns : defaultColumns,
+      noHeader: options.noHeader
+    })
+    if (options.quiet || options.format !== "table") return
+    const more =
+      result.nextPageToken === ""
+        ? ""
+        : `; more available (next token: ${result.nextPageToken})`
+    const stdio = yield* Stdio.Stdio
+    yield* Stream.run(
+      Stream.make(`${result.items.length} item(s), ${result.requests} request(s)${more}\n`),
+      stdio.stderr()
+    ).pipe(
+      Effect.catch((cause) =>
+        Effect.fail(new OperationalError({ message: "could not write output", cause }))
+      )
+    )
+  })
+
+/**
+ * Go's `csvValues`: split on `,`, trim each entry, drop the empties. So
+ * `--metrics " , "` yields zero entries and triggers the required-flag error.
+ */
+export const csvValues = (value: string): ReadonlyArray =>
+  value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== "")
+
+/** Go's `validateEnum`; the empty string always passes. */
+export const validateEnum = (
+  flag: string,
+  value: string,
+  allowed: ReadonlyArray
+): UsageError | undefined =>
+  value === "" || allowed.includes(value)
+    ? undefined
+    : new UsageError({ message: `${flag} must be one of: ${allowed.join(", ")}` })
+
+/**
+ * `time.Parse(time.DateOnly, s)` followed by a reformat equality check.
+ *
+ * Go's parser accepts `2026-1-05`, but reformatting yields `2026-01-05`, which
+ * differs from the input — so the non-canonical form is rejected. Reproduced
+ * exactly: parse strictly on the digit shape, then re-render and compare.
+ */
+export const parseDateOnly = (value: string): Date | undefined => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value)
+  if (match === null) return undefined
+  const [, year, month, day] = match as unknown as [string, string, string, string]
+  const date = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)))
+  // Rejects 2026-02-31 and friends: Date.UTC rolls them over, so the
+  // round-tripped components no longer match the input.
+  if (
+    date.getUTCFullYear() !== Number(year) ||
+    date.getUTCMonth() !== Number(month) - 1 ||
+    date.getUTCDate() !== Number(day)
+  ) {
+    return undefined
+  }
+  return date
+}
+
+/** `validateAnalyticsDates`: start format, end format, then ordering. */
+export const validateAnalyticsDates = (
+  start: string,
+  end: string
+): UsageError | undefined => {
+  const startDate = parseDateOnly(start)
+  if (startDate === undefined) return new UsageError({ message: "--start must use YYYY-MM-DD" })
+  const endDate = parseDateOnly(end)
+  if (endDate === undefined) return new UsageError({ message: "--end must use YYYY-MM-DD" })
+  if (startDate.getTime() > endDate.getTime()) {
+    return new UsageError({ message: "--start cannot be after --end" })
+  }
+  return undefined
+}
+
+/** Built-in filter first, user filter second, joined by `;` when both exist. */
+export const mergeFilters = (builtIn: string, user: string): string => {
+  if (builtIn === "") return user
+  if (user === "") return builtIn
+  return `${builtIn};${user}`
+}
+
+// ---------------------------------------------------------------------------
+// Flags
+// ---------------------------------------------------------------------------
+
+/**
+ * Computed ONCE, at module import. See the header: Go materialized these into
+ * the flag defaults while constructing the command tree, so they show up
+ * verbatim in `--help`.
+ */
+export const DEFAULT_RANGE = defaultDateRange(new Date())
+
+const analyticsFlags = {
+  start: Flag.string("start").pipe(
+    Flag.withDefault(DEFAULT_RANGE.start),
+    Flag.withDescription("report start date (YYYY-MM-DD; default: 28 days ending yesterday)")
+  ),
+  end: Flag.string("end").pipe(
+    Flag.withDefault(DEFAULT_RANGE.end),
+    Flag.withDescription("report end date (YYYY-MM-DD; default: yesterday)")
+  ),
+  filters: Flag.string("filters").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("Analytics filter expression")
+  ),
+  sort: Flag.string("sort").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("comma-separated Analytics sort fields")
+  ),
+  limit: Flag.integer("limit").pipe(
+    Flag.withDefault(MAX_RESULTS),
+    Flag.withDescription(`maximum rows (1-${MAX_RESULTS})`)
+  )
+} as const
+
+interface AnalyticsFlagValues {
+  readonly start: string
+  readonly end: string
+  readonly filters: string
+  readonly sort: string
+  readonly limit: number
+}
+
+// ---------------------------------------------------------------------------
+// The shared runner
+// ---------------------------------------------------------------------------
+
+interface AnalyticsRequest {
+  readonly metrics: ReadonlyArray
+  readonly dimensions: ReadonlyArray
+  /** The subcommand's own filter, before `--filters` is merged in. */
+  readonly builtInFilter: string
+  readonly columns: ReadonlyArray
+}
+
+const runAnalytics = (flags: AnalyticsFlagValues, request: AnalyticsRequest) =>
+  Effect.gen(function* () {
+    const dateError = validateAnalyticsDates(flags.start, flags.end)
+    if (dateError !== undefined) return yield* Effect.fail(dateError)
+
+    if (flags.limit < 1 || flags.limit > MAX_RESULTS) {
+      return yield* Effect.fail(
+        new UsageError({ message: `--limit must be between 1 and ${MAX_RESULTS}` })
+      )
+    }
+
+    const store = yield* CredentialStore
+    const credentials = yield* store.load
+    if (credentials.oauth === undefined) {
+      return yield* Effect.fail(
+        new MissingOAuthError({ suffix: "; analytics requires OAuth" })
+      )
+    }
+
+    const analytics = yield* AnalyticsApi
+    // Go: `if err != nil { return oauthAuthHint(err) }`. Without this a 401 or
+    // an `insufficientPermissions` 403 from the reports endpoint reaches the
+    // user as a bare `YouTube API error (…)` with no "re-run 'oytc login
+    // --oauth'" hint — the single most common analytics failure, and the one
+    // case where the message has to tell the user what to do. `status --check`
+    // already routes its OAuth probe through the same helper.
+    const response = yield* analytics
+      .report({
+        metrics: request.metrics.join(","),
+        dimensions: request.dimensions.join(","),
+        filters: mergeFilters(request.builtInFilter, flags.filters),
+        sort: flags.sort,
+        startDate: flags.start,
+        endDate: flags.end,
+        limit: flags.limit,
+        startIndex: 0
+      })
+      .pipe(Effect.mapError(oauthAuthHint))
+
+    const options = yield* AppOptions
+    yield* renderResult(analyticsListResult(response), request.columns, options)
+  })
+
+// ---------------------------------------------------------------------------
+// Subcommands
+// ---------------------------------------------------------------------------
+
+export const analyticsReportCommand = Command.make(
+  "report",
+  {
+    ...analyticsFlags,
+    metrics: Flag.string("metrics").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("required comma-separated Analytics metrics")
+    ),
+    dimensions: Flag.string("dimensions").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("comma-separated Analytics dimensions")
+    )
+  },
+  (config) =>
+    Effect.gen(function* () {
+      const metrics = csvValues(config.metrics)
+      // Runs before the date and limit checks, and before any credential load.
+      if (metrics.length === 0) {
+        return yield* Effect.fail(new UsageError({ message: "--metrics is required" }))
+      }
+      const dimensions = csvValues(config.dimensions)
+      yield* runAnalytics(config, {
+        metrics,
+        dimensions,
+        builtInFilter: "",
+        columns: analyticsReportColumns(dimensions, metrics)
+      })
+    })
+).pipe(Command.withDescription("Run a raw YouTube Analytics report"))
+
+export const analyticsOverviewCommand = Command.make(
+  "overview",
+  {
+    ...analyticsFlags,
+    by: Flag.string("by").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("group by day or month")
+    )
+  },
+  (config) =>
+    Effect.gen(function* () {
+      const enumError = validateEnum("--by", config.by, ["day", "month"])
+      if (enumError !== undefined) return yield* Effect.fail(enumError)
+      // `--by` goes through csvValues, so a whitespace-only value contributes
+      // no dimension at all rather than an empty one.
+      const dimensions = csvValues(config.by)
+      yield* runAnalytics(config, {
+        metrics: analyticsOverviewMetrics,
+        dimensions,
+        builtInFilter: "",
+        columns: analyticsOverviewColumns(config.by)
+      })
+    })
+).pipe(
+  Command.withDescription("Show channel views, watch time, retention, and subscribers gained")
+)
+
+export const analyticsVideoCommand = Command.make(
+  "video",
+  { ...analyticsFlags, videoId: Argument.string("VIDEO_ID") },
+  (config) =>
+    runAnalytics(config, {
+      metrics: analyticsVideoColumns,
+      dimensions: [],
+      builtInFilter: `video==${config.videoId}`,
+      columns: analyticsVideoColumns
+    })
+).pipe(Command.withDescription("Show core analytics metrics for one owned video"))
+
+export const analyticsTrafficSourcesCommand = Command.make(
+  "traffic-sources",
+  analyticsFlags,
+  (config) =>
+    runAnalytics(config, {
+      metrics: ["views", "estimatedMinutesWatched"],
+      dimensions: ["insightTrafficSourceType"],
+      builtInFilter: "",
+      columns: analyticsTrafficSourcesColumns
+    })
+).pipe(Command.withDescription("Break views and watch time down by traffic source"))
+
+export const analyticsDemographicsCommand = Command.make(
+  "demographics",
+  analyticsFlags,
+  (config) =>
+    runAnalytics(config, {
+      metrics: ["viewerPercentage"],
+      dimensions: ["ageGroup", "gender"],
+      builtInFilter: "",
+      columns: analyticsDemographicsColumns
+    })
+).pipe(Command.withDescription("Break viewer percentage down by age group and gender"))
+
+/** The group; no handler, so a bare `oytc analytics` prints help and exits 0. */
+export const analyticsCommand = Command.make("analytics").pipe(
+  Command.withDescription("Read analytics for your authorized YouTube channel (OAuth required)"),
+  Command.withSubcommands([
+    analyticsReportCommand,
+    analyticsOverviewCommand,
+    analyticsVideoCommand,
+    analyticsTrafficSourcesCommand,
+    analyticsDemographicsCommand
+  ])
+)
diff --git a/src/cli/auth.test.ts b/src/cli/auth.test.ts
new file mode 100644
index 0000000..09e0960
--- /dev/null
+++ b/src/cli/auth.test.ts
@@ -0,0 +1,857 @@
+/**
+ * `login` / `status` / `logout` tests.
+ *
+ * The centrepiece is the redaction contract (DEVIATIONS.md G2). Those tests
+ * are written as ABSENCE assertions over distinctive fixture values rather
+ * than presence assertions over the allowed fields: a future refactor that
+ * accidentally spreads the whole credential record into the state object would
+ * still satisfy "path and fingerprint are present", but it would fail here.
+ *
+ * `status` is additionally compared against `/tmp/goldens/status.txt`, captured
+ * from the real Go binary, when that file is available.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Effect, Exit, Layer, Redacted, Result, Sink, Stdio } from "effect"
+import { Command } from "../effect.ts"
+import {
+  ApiError,
+  MissingKeyError,
+  OperationalError,
+  UsageError,
+  type OytcError
+} from "../domain/errors.ts"
+import type { AnalyticsResponse } from "../schema/analytics.ts"
+import type { DataApiResponse } from "../schema/dataapi.ts"
+import { makeRendererWith } from "../impl/renderer.ts"
+import { statusCheckColumns, statusColumns } from "../output/columns.ts"
+import {
+  AnalyticsApi,
+  AppOptions,
+  CredentialStore,
+  OAuthService,
+  Prompts,
+  Renderer,
+  YouTubeApi,
+  type AppOptionsShape,
+  type Credentials,
+  type CredentialSource,
+  type OutputFormat,
+  type Params,
+  type StoredOAuth
+} from "../services/index.ts"
+import {
+  authCommands,
+  checkVerdict,
+  encodeScopes,
+  loginCommand,
+  logoutCommand,
+  oauthAuthHint,
+  statusCommand,
+  statusState,
+  statusTableText,
+  valueOr
+} from "./auth.ts"
+
+// ---------------------------------------------------------------------------
+// Fixtures — every secret carries a distinctive, greppable value
+// ---------------------------------------------------------------------------
+
+const SECRET_CLIENT_SECRET = "GOCSPX-supersecret-do-not-print"
+const SECRET_ACCESS_TOKEN = "ya29.SECRET-ACCESS-TOKEN"
+const SECRET_REFRESH_TOKEN = "1//SECRET-REFRESH-TOKEN"
+const SECRET_API_KEY = "AIzaSyTESTKEY1234567890abcdefghijklmnop"
+
+/** Every value that must NEVER appear in `status` output, in any format. */
+const FORBIDDEN = [
+  SECRET_CLIENT_SECRET,
+  SECRET_ACCESS_TOKEN,
+  SECRET_REFRESH_TOKEN,
+  SECRET_API_KEY
+] as const
+
+const storedOAuth: StoredOAuth = {
+  clientId: "1234-test.apps.googleusercontent.com",
+  clientSecret: SECRET_CLIENT_SECRET,
+  accessToken: SECRET_ACCESS_TOKEN,
+  refreshToken: SECRET_REFRESH_TOKEN,
+  expiry: "2027-01-01T00:00:00Z",
+  scopes: ["https://www.googleapis.com/auth/youtube.readonly"]
+}
+
+const GOLDEN_PATH = "/tmp/goldens/fakeconf/auth.json"
+/** The fingerprint the Go binary printed for the golden fixture's key. */
+const GOLDEN_FINGERPRINT = "sha256:50793a5e591b"
+
+const credentials = (overrides?: Partial): Credentials => ({
+  key: SECRET_API_KEY,
+  source: "auth.json" as CredentialSource,
+  oauth: storedOAuth,
+  path: GOLDEN_PATH,
+  ...overrides
+})
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+interface Captured {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exit: Exit.Exit
+}
+
+interface HarnessOptions {
+  readonly credentials?: Credentials | undefined
+  readonly loadError?: OperationalError | undefined
+  readonly format?: OutputFormat | undefined
+  readonly columns?: ReadonlyArray | undefined
+  readonly noHeader?: boolean | undefined
+  readonly quiet?: boolean | undefined
+  /** `undefined` = the API-key probe succeeds. */
+  readonly keyProbeError?: OytcError | undefined
+  readonly oauthProbeError?: OytcError | undefined
+  readonly promptLines?: ReadonlyArray | undefined
+  readonly envKeySet?: boolean | undefined
+  readonly bootstrap?: readonly [string, string] | undefined
+  readonly removed?: boolean | undefined
+  readonly loginResult?: StoredOAuth | undefined
+  readonly loginError?: OytcError | undefined
+}
+
+interface Recorder {
+  readonly saved: Array
+  readonly savedOAuth: Array
+  readonly revoked: Array
+  readonly getCalls: Array
+  readonly reportCalls: Array
+  readonly prompts: Array
+  removedCalled: boolean
+}
+
+const emptyResponse: DataApiResponse = { items: [] }
+const emptyReport: AnalyticsResponse = { columnHeaders: [], rows: [] }
+
+const appOptions = (options: HarnessOptions): AppOptionsShape => ({
+  format: options.format ?? "table",
+  columns: options.columns ?? [],
+  noHeader: options.noHeader ?? false,
+  quiet: options.quiet ?? false,
+  timeoutMillis: 20_000,
+  isOutputTTY: false
+})
+
+const run = async (
+  argv: ReadonlyArray,
+  options: HarnessOptions = {}
+): Promise => {
+  const out: Array = []
+  const err: Array = []
+  const recorder: Recorder = {
+    saved: [],
+    savedOAuth: [],
+    revoked: [],
+    getCalls: [],
+    reportCalls: [],
+    prompts: [],
+    removedCalled: false
+  }
+  const creds = options.credentials ?? credentials()
+  let promptIndex = 0
+  const nextLine = (): string => options.promptLines?.[promptIndex++] ?? ""
+
+  const decode = (input: string | Uint8Array): string =>
+    typeof input === "string" ? input : new TextDecoder().decode(input)
+
+  const stdio = Stdio.layerTest({
+    stdout: () => Sink.forEach((i: string | Uint8Array) => Effect.sync(() => out.push(decode(i)))),
+    stderr: () => Sink.forEach((i: string | Uint8Array) => Effect.sync(() => err.push(decode(i))))
+  })
+
+  const layers = Layer.mergeAll(
+    Layer.succeed(AppOptions, appOptions(options)),
+    Layer.succeed(CredentialStore, {
+      dir: Effect.succeed("/tmp/goldens/fakeconf"),
+      path: Effect.succeed(creds.path),
+      load:
+        options.loadError === undefined
+          ? Effect.succeed(creds)
+          : Effect.fail(options.loadError),
+      save: (key: string) =>
+        Effect.sync(() => {
+          recorder.saved.push(key)
+          return creds.path
+        }),
+      saveOAuth: (stored: StoredOAuth) =>
+        Effect.sync(() => {
+          recorder.savedOAuth.push(stored)
+          return creds.path
+        }),
+      saveRefreshedOAuth: () => Effect.succeed(true),
+      clearOAuth: Effect.succeed(creds.path),
+      remove: Effect.sync(() => {
+        recorder.removedCalled = true
+        return { path: creds.path, removed: options.removed ?? true }
+      }),
+      fingerprint: () => GOLDEN_FINGERPRINT,
+      envKeySet: Effect.succeed(options.envKeySet ?? false),
+      oauthBootstrap: Effect.succeed(options.bootstrap ?? (["", ""] as const))
+    }),
+    Layer.succeed(YouTubeApi, {
+      get: (resource: string, params: Params) =>
+        Effect.suspend(() => {
+          recorder.getCalls.push([resource, params])
+          return options.keyProbeError === undefined
+            ? Effect.succeed(emptyResponse)
+            : Effect.fail(options.keyProbeError)
+        }),
+      list: () => Effect.succeed({ items: [], nextPageToken: "", requests: 0 }),
+      resolveChannel: () => Effect.succeed({ id: "", requests: 0 })
+    }),
+    Layer.succeed(AnalyticsApi, {
+      report: (query: unknown) =>
+        Effect.suspend(() => {
+          recorder.reportCalls.push(query)
+          return options.oauthProbeError === undefined
+            ? Effect.succeed(emptyReport)
+            : Effect.fail(options.oauthProbeError)
+        }),
+      normalize: () => []
+    }),
+    Layer.succeed(OAuthService, {
+      login: () =>
+        options.loginError === undefined
+          ? Effect.succeed(options.loginResult ?? storedOAuth)
+          : Effect.fail(options.loginError as never),
+      refresh: () => Effect.succeed(storedOAuth),
+      revoke: (stored: StoredOAuth) =>
+        Effect.sync(() => {
+          recorder.revoked.push(stored)
+        }),
+      tokenSource: () => Effect.succeed(Redacted.make("token"))
+    }),
+    Layer.succeed(Prompts, {
+      readLine: (prompt: string) =>
+        Effect.sync(() => {
+          recorder.prompts.push(prompt)
+          err.push(prompt)
+          return nextLine()
+        }),
+      readSecret: (prompt: string) =>
+        Effect.sync(() => {
+          recorder.prompts.push(prompt)
+          err.push(prompt)
+          const line = nextLine()
+          err.push("\n")
+          return Redacted.make(line)
+        }),
+      confirm: () => Effect.succeed(true)
+    }),
+    Layer.effect(
+      Renderer,
+      Effect.gen(function* () {
+        const service = yield* Stdio.Stdio
+        return makeRendererWith((text) =>
+          Effect.gen(function* () {
+            yield* Effect.sync(() => out.push(text))
+            void service
+          })
+        )
+      })
+    ).pipe(Layer.provide(stdio))
+  )
+
+  const root = Command.make("oytc").pipe(Command.withSubcommands([...authCommands]))
+  const exit = await Effect.runPromiseExit(
+    Command.runWith(root, { version: "test" })(argv).pipe(
+      Effect.provide(Layer.mergeAll(layers, stdio))
+    ) as Effect.Effect
+  )
+
+  return { stdout: out.join(""), stderr: err.join(""), exit, recorder }
+}
+
+const errorOf = (exit: Exit.Exit): OytcError => {
+  if (Exit.isSuccess(exit)) throw new Error("expected a failure")
+  const found = exit.cause.reasons.find((r) => r._tag === "Fail")
+  if (found === undefined) throw new Error(`no Fail reason: ${String(exit.cause)}`)
+  return (found as { readonly error: OytcError }).error
+}
+
+// ---------------------------------------------------------------------------
+// The redaction contract — G2
+// ---------------------------------------------------------------------------
+
+describe("status never leaks a secret (DEVIATIONS.md G2)", () => {
+  const formats: ReadonlyArray = ["table", "json", "jsonl", "tsv"]
+
+  for (const format of formats) {
+    test(`--format ${format} omits every secret`, async () => {
+      const { stdout, exit } = await run(["status", "--format-ignored"].slice(0, 1), { format })
+      expect(Exit.isSuccess(exit)).toBe(true)
+      for (const secret of FORBIDDEN) expect(stdout).not.toContain(secret)
+      // …and the allowed values ARE there, so the test cannot pass vacuously.
+      expect(stdout).toContain(GOLDEN_FINGERPRINT)
+      expect(stdout).toContain(storedOAuth.clientId)
+    })
+
+    test(`--check --format ${format} omits every secret`, async () => {
+      const { stdout, exit } = await run(["status", "--check"], { format })
+      expect(Exit.isSuccess(exit)).toBe(true)
+      for (const secret of FORBIDDEN) expect(stdout).not.toContain(secret)
+      expect(stdout).toContain(GOLDEN_FINGERPRINT)
+    })
+  }
+
+  test("the state object's key set is exactly the allowed one", () => {
+    const state = statusState(credentials(), { key: undefined, oauth: undefined }, false)
+    expect(Object.keys(state).sort()).toEqual(["api_key", "oauth", "path"])
+    expect(Object.keys(state["api_key"] as object).sort()).toEqual([
+      "configured",
+      "fingerprint",
+      "source"
+    ])
+    expect(Object.keys(state["oauth"] as object).sort()).toEqual([
+      "client_id",
+      "configured",
+      "expiry",
+      "scopes"
+    ])
+  })
+
+  test("--check adds exactly `valid` to each block and nothing else", () => {
+    const state = statusState(credentials(), { key: null, oauth: null }, false)
+    expect(Object.keys(state["api_key"] as object).sort()).toEqual([
+      "configured",
+      "fingerprint",
+      "source",
+      "valid"
+    ])
+    expect(Object.keys(state["oauth"] as object).sort()).toEqual([
+      "client_id",
+      "configured",
+      "expiry",
+      "scopes",
+      "valid"
+    ])
+  })
+
+  test("a serialized state object contains no secret substring", () => {
+    const state = statusState(credentials(), { key: null, oauth: null }, true)
+    const serialized = [state]
+      .flatMap((s) => Object.values(s))
+      .flatMap((v) => (typeof v === "object" && v !== null ? Object.values(v) : [v]))
+      .map(String)
+      .join("|")
+    for (const secret of FORBIDDEN) expect(serialized).not.toContain(secret)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// G1 — scopes bracket rendering
+// ---------------------------------------------------------------------------
+
+describe("G1: status scopes render with brackets in row formats", () => {
+  test("tsv pre-encodes the scopes array as JSON text", () => {
+    expect(encodeScopes(["https://a/x"], true)).toBe('["https://a/x"]')
+    expect(encodeScopes(["https://a/x", "https://b/y"], true)).toBe(
+      '["https://a/x","https://b/y"]'
+    )
+  })
+
+  test("json keeps a real array", () => {
+    expect(encodeScopes(["https://a/x"], false)).toEqual(["https://a/x"])
+  })
+
+  test("an empty scope list is the literal null in row formats", () => {
+    // Go marshalled a nil []string as `null`; credentialStore normalizes nil
+    // to [], so the empty case is the one that must map back to null.
+    expect(encodeScopes([], true)).toBe("null")
+    expect(encodeScopes([], false)).toBeNull()
+  })
+
+  test("the tsv row carries the bracketed form end to end", async () => {
+    const { stdout } = await run(["status"], { format: "tsv" })
+    expect(stdout).toContain('["https://www.googleapis.com/auth/youtube.readonly"]')
+    // NOT the comma-joined form cell() would otherwise produce.
+    expect(stdout.split("\n")[1]).not.toMatch(/\thttps:\/\/www\.googleapis[^"]*\t/)
+  })
+
+  test("the TABLE rendering joins with ', ' — a different Go code path", () => {
+    const text = statusTableText(
+      credentials({ oauth: { ...storedOAuth, scopes: ["https://a/x", "https://b/y"] } }),
+      { key: undefined, oauth: undefined }
+    )
+    expect(text).toContain("OAuth scopes: https://a/x, https://b/y")
+    expect(text).not.toContain("[")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Golden comparison
+// ---------------------------------------------------------------------------
+
+describe("status matches the Go binary's golden output", () => {
+  const golden = (() => {
+    try {
+      // The goldens are an external artifact; skip cleanly when absent.
+      return require("node:fs").readFileSync("/tmp/goldens/status.txt", "utf8") as string
+    } catch {
+      return undefined
+    }
+  })()
+
+  const section = (format: string): string | undefined => {
+    if (golden === undefined) return undefined
+    const marker = `=== status --format ${format}\n`
+    const start = golden.indexOf(marker)
+    if (start < 0) return undefined
+    const from = start + marker.length
+    const next = golden.indexOf("=== status --format", from)
+    return next < 0 ? golden.slice(from) : golden.slice(from, next)
+  }
+
+  for (const format of ["table", "json", "jsonl", "tsv"] as const) {
+    test(`--format ${format}`, async () => {
+      const expected = section(format)
+      if (expected === undefined) return
+      const { stdout } = await run(["status"], { format })
+      expect(stdout).toBe(expected)
+    })
+  }
+})
+
+// ---------------------------------------------------------------------------
+// status behaviour
+// ---------------------------------------------------------------------------
+
+describe("status", () => {
+  test("without --check it performs no network call at all", async () => {
+    const { recorder, exit } = await run(["status"], { format: "json" })
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(recorder.getCalls).toEqual([])
+    expect(recorder.reportCalls).toEqual([])
+  })
+
+  test("--check probes the API key with the quota-1 i18nLanguages call", async () => {
+    const { recorder } = await run(["status", "--check"], { format: "json" })
+    expect(recorder.getCalls).toEqual([["i18nLanguages", [["part", "snippet"]]]])
+  })
+
+  test("--check probes OAuth against Analytics with views/limit 1", async () => {
+    const { recorder } = await run(["status", "--check"], { format: "json" })
+    expect(recorder.reportCalls).toHaveLength(1)
+    const query = recorder.reportCalls[0] as { metrics: string; limit: number }
+    expect(query.metrics).toBe("views")
+    expect(query.limit).toBe(1)
+  })
+
+  test("both credentials are validated even when the key fails first", async () => {
+    const { recorder } = await run(["status", "--check"], {
+      format: "json",
+      keyProbeError: new ApiError({
+        httpStatus: 400,
+        code: 400,
+        apiMessage: "API key not valid",
+        reasons: ["badRequest"]
+      })
+    })
+    // The OAuth probe still ran — a stale key must not mask a working grant.
+    expect(recorder.reportCalls).toHaveLength(1)
+  })
+
+  test("--check writes the full state BEFORE failing", async () => {
+    const keyError = new ApiError({
+      httpStatus: 400,
+      code: 400,
+      apiMessage: "API key not valid. Please pass a valid API key.",
+      reasons: ["badRequest", "API_KEY_INVALID"]
+    })
+    const { stdout, exit } = await run(["status", "--check"], {
+      format: "json",
+      keyProbeError: keyError
+    })
+    expect(Exit.isFailure(exit)).toBe(true)
+    expect(errorOf(exit)).toBe(keyError)
+    expect(stdout).toContain('"valid": false')
+    expect(stdout).toContain(GOLDEN_FINGERPRINT)
+  })
+
+  test("the key error wins over an OAuth error", async () => {
+    const keyError = new ApiError({
+      httpStatus: 401,
+      code: 401,
+      apiMessage: "key",
+      reasons: []
+    })
+    const oauthError = new ApiError({
+      httpStatus: 403,
+      code: 403,
+      apiMessage: "oauth",
+      reasons: []
+    })
+    const { exit } = await run(["status", "--check"], {
+      format: "json",
+      keyProbeError: keyError,
+      oauthProbeError: oauthError
+    })
+    expect(errorOf(exit).message).toContain("key")
+  })
+
+  test("the OAuth error surfaces when the key is fine", async () => {
+    const oauthError = new ApiError({
+      httpStatus: 403,
+      code: 403,
+      apiMessage: "oauth is bad",
+      reasons: []
+    })
+    const { exit } = await run(["status", "--check"], {
+      format: "json",
+      oauthProbeError: oauthError
+    })
+    expect(errorOf(exit).message).toContain("oauth is bad")
+  })
+
+  test("--check with neither credential fails with MissingKeyError and no output", async () => {
+    const { stdout, exit } = await run(["status", "--check"], {
+      format: "json",
+      credentials: credentials({ key: "", source: "", oauth: undefined })
+    })
+    expect(errorOf(exit)).toBeInstanceOf(MissingKeyError)
+    expect(stdout).toBe("")
+  })
+
+  test("the table rendering matches Go's line-by-line format", async () => {
+    const { stdout } = await run(["status"], { format: "table" })
+    expect(stdout).toBe(
+      `Path: ${GOLDEN_PATH}\n` +
+        "API key configured: true\n" +
+        "API key source: auth.json\n" +
+        `API key fingerprint: ${GOLDEN_FINGERPRINT}\n` +
+        "OAuth configured: true\n" +
+        `OAuth client ID: ${storedOAuth.clientId}\n` +
+        "OAuth scopes: https://www.googleapis.com/auth/youtube.readonly\n" +
+        "OAuth token expiry: 2027-01-01T00:00:00Z\n"
+    )
+  })
+
+  test("an unconfigured key omits the fingerprint line", async () => {
+    const { stdout } = await run(["status"], {
+      format: "table",
+      credentials: credentials({ key: "", source: "" })
+    })
+    expect(stdout).toContain("API key source: none")
+    expect(stdout).not.toContain("fingerprint")
+  })
+
+  test("no OAuth means the oauth block is `configured` alone", () => {
+    const state = statusState(
+      credentials({ oauth: undefined }),
+      { key: undefined, oauth: undefined },
+      false
+    )
+    expect(state["oauth"]).toEqual({ configured: false })
+  })
+
+  test("an empty expiry renders as `unknown` in the table only", async () => {
+    const { stdout } = await run(["status"], {
+      format: "table",
+      credentials: credentials({ oauth: { ...storedOAuth, expiry: "" } })
+    })
+    expect(stdout).toContain("OAuth token expiry: unknown")
+    const json = await run(["status"], {
+      format: "json",
+      credentials: credentials({ oauth: { ...storedOAuth, expiry: "" } })
+    })
+    // The state object keeps the raw empty string; only the table substitutes.
+    expect(json.stdout).toContain('"expiry": ""')
+  })
+
+  test("the tsv header uses the non-check column set without --check", async () => {
+    const { stdout } = await run(["status"], { format: "tsv" })
+    const header = stdout.split("\n")[0]!
+    expect(header.split("\t")).toEqual(statusColumns.map((c) => c.toUpperCase()))
+  })
+
+  test("the tsv header uses the check column set with --check", async () => {
+    const { stdout } = await run(["status", "--check"], { format: "tsv" })
+    const header = stdout.split("\n")[0]!
+    expect(header.split("\t")).toEqual(statusCheckColumns.map((c) => c.toUpperCase()))
+  })
+
+  test("--columns overrides the default list for tsv", async () => {
+    const { stdout } = await run(["status"], { format: "tsv", columns: ["path"] })
+    expect(stdout).toBe(`PATH\n${GOLDEN_PATH}\n`)
+  })
+
+  test("--columns is IGNORED for the table rendering (Go bypasses RenderObject)", async () => {
+    const { stdout } = await run(["status"], { format: "table", columns: ["path"] })
+    expect(stdout).toContain("API key configured: true")
+  })
+
+  test("checkVerdict renders both outcomes verbatim", () => {
+    expect(checkVerdict(null)).toBe("valid")
+    expect(checkVerdict(new UsageError({ message: "nope" }))).toBe("invalid (nope)")
+  })
+
+  test("valueOr only substitutes for the empty string", () => {
+    expect(valueOr("", "none")).toBe("none")
+    expect(valueOr("auth.json", "none")).toBe("auth.json")
+    expect(valueOr(" ", "none")).toBe(" ")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// The key-scoped probe
+// ---------------------------------------------------------------------------
+
+/**
+ * `status --check` and `login` must validate the API KEY, not whatever
+ * credential the ambient client happens to prefer.
+ *
+ * `HttpCore`'s auth switch is first-match-wins with OAuth strictly ahead of the
+ * key, so with both credentials stored the ambient `YouTubeApi` would send a
+ * bearer token and the "API key check" would actually be a second OAuth check —
+ * exactly the masking Go's comment says must not happen. `keyScopedApi` builds
+ * a one-off client with `tokenSource: undefined` to avoid that, but only when
+ * an `HttpClient` is reachable.
+ *
+ * NOTE FOR THE ORCHESTRATOR: `AppLayer` does not currently export
+ * `HttpClient`, so in production this degrades to the ambient `YouTubeApi` and
+ * the probe is less precise than Go's. Verified empirically against the real
+ * `AppLayer`. Adding `HttpClientLive` to `AppLayer`'s exported set activates
+ * the precise path with no change to this file.
+ */
+describe("the API-key probe is key-scoped", () => {
+  test("it sends the i18nLanguages part=snippet request Go used", async () => {
+    const { recorder } = await run(["status", "--check"], { format: "json" })
+    expect(recorder.getCalls).toEqual([["i18nLanguages", [["part", "snippet"]]]])
+  })
+
+  test("with HttpClient absent it degrades to the ambient client, not to a crash", async () => {
+    // The harness provides no HttpClient, mirroring today's AppLayer.
+    const { exit } = await run(["status", "--check"], { format: "json" })
+    expect(Exit.isSuccess(exit)).toBe(true)
+  })
+
+  test("a key probe failure is distinguishable from an OAuth probe failure", async () => {
+    const keyOnly = await run(["status", "--check"], {
+      format: "json",
+      keyProbeError: new ApiError({
+        httpStatus: 400,
+        code: 400,
+        apiMessage: "key bad",
+        reasons: []
+      })
+    })
+    expect(keyOnly.stdout).toContain('"valid": false')
+    // The OAuth block still reports valid, so the two probes are independent.
+    const oauthBlock = keyOnly.stdout.slice(keyOnly.stdout.indexOf('"oauth"'))
+    expect(oauthBlock).toContain('"valid": true')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// login
+// ---------------------------------------------------------------------------
+
+describe("login (API key)", () => {
+  test("prompts on stderr, validates, then saves", async () => {
+    const { stdout, stderr, recorder, exit } = await run(["login"], {
+      promptLines: ["  my-key  "]
+    })
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(stderr).toContain("YouTube Data API key: ")
+    expect(recorder.getCalls).toEqual([["i18nLanguages", [["part", "snippet"]]]])
+    expect(recorder.saved).toEqual(["my-key"])
+    expect(stdout).toContain(`API key validated and saved to ${GOLDEN_PATH}`)
+    expect(stdout).toContain(GOLDEN_FINGERPRINT)
+  })
+
+  test("an empty key is a UsageError before any network call", async () => {
+    const { recorder, exit } = await run(["login"], { promptLines: ["   "] })
+    const error = errorOf(exit)
+    expect(error).toBeInstanceOf(UsageError)
+    expect(error.message).toBe("API key cannot be empty")
+    expect(recorder.getCalls).toEqual([])
+    expect(recorder.saved).toEqual([])
+  })
+
+  test("a failed validation wraps the cause and saves nothing", async () => {
+    const { recorder, exit } = await run(["login"], {
+      promptLines: ["bad"],
+      keyProbeError: new ApiError({
+        httpStatus: 400,
+        code: 400,
+        apiMessage: "API key not valid",
+        reasons: ["badRequest"]
+      })
+    })
+    expect(errorOf(exit).message).toStartWith("API key validation failed: ")
+    expect(recorder.saved).toEqual([])
+  })
+
+  test("OYTC_API_KEY being set adds the precedence note", async () => {
+    const { stdout } = await run(["login"], { promptLines: ["k"], envKeySet: true })
+    expect(stdout).toContain(
+      "Note: OYTC_API_KEY remains the active, higher-precedence credential."
+    )
+  })
+})
+
+describe("login --oauth", () => {
+  test("prompts for both values, then saves the grant", async () => {
+    const { stdout, recorder, exit } = await run(["login", "--oauth"], {
+      promptLines: ["  cid  ", "  csecret  "]
+    })
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(recorder.prompts).toEqual(["OAuth client ID: ", "OAuth client secret: "])
+    expect(recorder.savedOAuth).toHaveLength(1)
+    expect(stdout).toContain(`OAuth authorization saved to ${GOLDEN_PATH}`)
+    expect(stdout).toContain(
+      "Granted scopes: https://www.googleapis.com/auth/youtube.readonly"
+    )
+  })
+
+  test("a bootstrapped client ID skips ONLY that prompt", async () => {
+    const { recorder } = await run(["login", "--oauth"], {
+      bootstrap: ["env-cid", ""],
+      promptLines: ["env-secret"]
+    })
+    expect(recorder.prompts).toEqual(["OAuth client secret: "])
+  })
+
+  test("both bootstrapped means no prompt at all", async () => {
+    const { recorder, exit } = await run(["login", "--oauth"], {
+      bootstrap: ["env-cid", "env-secret"]
+    })
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(recorder.prompts).toEqual([])
+  })
+
+  test("an empty client ID or secret is a UsageError", async () => {
+    const { exit } = await run(["login", "--oauth"], { promptLines: ["", ""] })
+    const error = errorOf(exit)
+    expect(error).toBeInstanceOf(UsageError)
+    expect(error.message).toBe("OAuth client ID and client secret cannot be empty")
+  })
+
+  test("a login failure is wrapped and nothing is saved", async () => {
+    const { recorder, exit } = await run(["login", "--oauth"], {
+      promptLines: ["cid", "secret"],
+      loginError: new OperationalError({ message: "browser died" })
+    })
+    expect(errorOf(exit).message).toBe("OAuth login failed: browser died")
+    expect(recorder.savedOAuth).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// logout
+// ---------------------------------------------------------------------------
+
+describe("logout", () => {
+  test("revokes then removes, reporting the path", async () => {
+    const { stdout, recorder, exit } = await run(["logout"])
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(recorder.revoked).toEqual([storedOAuth])
+    expect(recorder.removedCalled).toBe(true)
+    expect(stdout).toBe(`Removed stored credentials at ${GOLDEN_PATH}.\n`)
+  })
+
+  test("reports when there was nothing to remove", async () => {
+    const { stdout } = await run(["logout"], { removed: false })
+    expect(stdout).toBe(`No stored credentials at ${GOLDEN_PATH}.\n`)
+  })
+
+  test("no stored OAuth means no revocation attempt", async () => {
+    const { recorder } = await run(["logout"], {
+      credentials: credentials({ oauth: undefined })
+    })
+    expect(recorder.revoked).toEqual([])
+  })
+
+  test("a corrupt auth.json warns on stderr and still removes the file", async () => {
+    const { stdout, stderr, recorder, exit } = await run(["logout"], {
+      loadError: new OperationalError({ message: "invalid character 'x'" })
+    })
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(stderr).toContain(
+      "Warning: could not read stored credentials (skipping OAuth revocation): " +
+        "invalid character 'x'"
+    )
+    expect(recorder.revoked).toEqual([])
+    expect(recorder.removedCalled).toBe(true)
+    expect(stdout).toContain("Removed stored credentials")
+  })
+
+  test("OYTC_API_KEY being set adds the still-active note", async () => {
+    const { stdout } = await run(["logout"], { envKeySet: true })
+    expect(stdout).toContain(
+      "OYTC_API_KEY is still set; environment credentials remain active."
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// oauthAuthHint
+// ---------------------------------------------------------------------------
+
+describe("oauthAuthHint", () => {
+  const apiError = (httpStatus: number, reasons: ReadonlyArray): ApiError =>
+    new ApiError({ httpStatus, code: httpStatus, apiMessage: "boom", reasons })
+
+  test("invalid_grant anywhere in the message triggers the re-login hint", () => {
+    const hinted = oauthAuthHint(new OperationalError({ message: "oauth: INVALID_GRANT here" }))
+    expect(hinted.message).toStartWith(
+      "OAuth authorization failed; re-run 'oytc login --oauth': "
+    )
+  })
+
+  test("a 401 ApiError triggers the re-login hint", () => {
+    expect(oauthAuthHint(apiError(401, [])).message).toStartWith(
+      "OAuth authorization failed; re-run 'oytc login --oauth': "
+    )
+  })
+
+  test("insufficientPermissions triggers the scopes hint, case-insensitively", () => {
+    expect(oauthAuthHint(apiError(403, ["INSUFFICIENTPERMISSIONS"])).message).toStartWith(
+      "OAuth scopes are insufficient; re-run 'oytc login --oauth': "
+    )
+  })
+
+  test("an unrelated error passes through untouched", () => {
+    const original = apiError(500, ["backendError"])
+    expect(oauthAuthHint(original)).toBe(original)
+  })
+
+  test("a non-ApiError without invalid_grant passes through untouched", () => {
+    const original = new OperationalError({ message: "network down" })
+    expect(oauthAuthHint(original)).toBe(original)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+describe("command registration", () => {
+  test("exports the three commands with Go's names", () => {
+    expect(authCommands.map((c) => c.name)).toEqual(["login", "status", "logout"])
+    expect(loginCommand.name).toBe("login")
+    expect(statusCommand.name).toBe("status")
+    expect(logoutCommand.name).toBe("logout")
+  })
+
+  test("descriptions match the Go Short strings", () => {
+    expect(loginCommand.description).toBe(
+      "Validate and save an API key or read-only OAuth authorization"
+    )
+    expect(statusCommand.description).toBe(
+      "Show API-key and OAuth status; optionally validate them"
+    )
+    expect(logoutCommand.description).toBe(
+      "Revoke OAuth best-effort and remove stored credentials"
+    )
+  })
+})
diff --git a/src/cli/auth.ts b/src/cli/auth.ts
index ca14f9a..81a89c0 100644
--- a/src/cli/auth.ts
+++ b/src/cli/auth.ts
@@ -1,2 +1,549 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `login`, `status`, `logout` — the port of `internal/cli/auth.go`.
+ *
+ * ## The redaction contract (DEVIATIONS.md G2)
+ *
+ * `status` renders EXACTLY these fields and nothing else, in every format,
+ * with and without `--check`:
+ *
+ *     path
+ *     api_key.configured, api_key.source, api_key.fingerprint [, api_key.valid]
+ *     oauth.configured, oauth.client_id, oauth.scopes, oauth.expiry [, oauth.valid]
+ *
+ * The access token, the refresh token and the client secret are loaded into
+ * memory (they live on the same `StoredOAuth` record) and must never reach the
+ * state object. This is a security property, not a formatting preference; the
+ * test suite asserts the absence of distinctive fixture values in all four
+ * formats rather than asserting the presence of the allowed ones.
+ *
+ * ## G1 — `status` scopes render WITH brackets in table/tsv
+ *
+ * `internal/output/output.go:cell()` comma-joins a `[]any`, which is what a
+ * list result's items decode to. But `status` renders a typed Go struct whose
+ * `scopes` field is `[]string` — a different dynamic type — so the `[]any`
+ * case does not match and it falls through to `default: json.Marshal`:
+ *
+ *     oytc status --format tsv
+ *     … OAUTH.SCOPES …
+ *     … ["https://www.googleapis.com/auth/youtube.readonly"] …
+ *
+ * and a nil scope slice renders as the literal `null`, not as an empty cell.
+ * Verified against the binary. The TS port has no static types at that
+ * boundary — everything is `JsonValue` — so `cell()` would comma-join here and
+ * silently diverge. The fix is local: for the row-based formats the scopes
+ * value is PRE-ENCODED into its JSON text, so `cell()` sees a string and emits
+ * it verbatim. `json`/`jsonl` keep the real array, because Go's marshaller
+ * produced a real array there.
+ *
+ * ## `--check` renders before it fails
+ *
+ * Full stdout is written first and the non-zero exit follows. That ordering is
+ * deliberate in Go (DEVIATIONS "everything else stays parity") and scripts
+ * depend on it: `oytc status --check --format json | jq .oauth.valid` works
+ * even when the command exits 3. Both credentials are also validated even when
+ * the first one fails, so a stale API key cannot mask a working OAuth grant.
+ */
+
+import { Effect, Option, Redacted, Result, Stdio, Stream } from "effect"
+import { Command, Flag, HttpClient } from "../effect.ts"
+import {
+  ApiError,
+  AuthHintError,
+  MissingKeyError,
+  OperationalError,
+  UsageError,
+  type AuthHintPrefix,
+  type OytcError
+} from "../domain/errors.ts"
+import { encodeGoValue } from "../json/encode.ts"
+import type { JsonObject, JsonValue } from "../json/value.ts"
+import { statusCheckDateRange } from "../impl/analyticsApi.ts"
+import { makeHttpCore } from "../impl/httpCore.ts"
+import { makeYouTubeApi } from "../impl/youtubeApi.ts"
+import { statusCheckColumns, statusColumns } from "../output/columns.ts"
+import {
+  AnalyticsApi,
+  AppOptions,
+  CredentialStore,
+  HttpCore,
+  OAuthService,
+  Prompts,
+  Renderer,
+  YouTubeApi,
+  type AnalyticsApiShape,
+  type Credentials,
+  type StoredOAuth,
+  type YouTubeApiShape
+} from "../services/index.ts"
+
+// ---------------------------------------------------------------------------
+// Stream helpers
+// ---------------------------------------------------------------------------
+
+const write = (
+  pick: "stdout" | "stderr",
+  text: string
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const stdio = yield* Stdio.Stdio
+    const sink = pick === "stdout" ? stdio.stdout() : stdio.stderr()
+    yield* Stream.run(Stream.make(text), sink).pipe(
+      Effect.catch((cause) =>
+        Effect.fail(new OperationalError({ message: "could not write output", cause }))
+      )
+    )
+  })
+
+const writeOut = (text: string) => write("stdout", text)
+const writeErr = (text: string) => write("stderr", text)
+
+// ---------------------------------------------------------------------------
+// Shared auth helpers
+// ---------------------------------------------------------------------------
+
+/** Go's `valueOr(value, fallback)`: the fallback only for the empty string. */
+export const valueOr = (value: string, fallback: string): string =>
+  value === "" ? fallback : value
+
+/**
+ * Go's `oauthAuthHint`.
+ *
+ * Turns three specific upstream failures into an actionable re-login message
+ * while preserving the cause, so the exit code stays 3 and the original text
+ * still appears after the colon. Note the asymmetry preserved from Go: the
+ * `invalid_grant` test is a case-INSENSITIVE substring of the whole rendered
+ * message, while `insufficientPermissions` is matched case-insensitively
+ * against each structured reason.
+ */
+export const oauthAuthHint = (error: OytcError): OytcError => {
+  const hint = (prefix: AuthHintPrefix): AuthHintError => new AuthHintError({ prefix, cause: error })
+
+  if (error.message.toLowerCase().includes("invalid_grant")) {
+    return hint("OAuth authorization failed; re-run 'oytc login --oauth'")
+  }
+  if (!(error instanceof ApiError)) return error
+  if (error.httpStatus === 401) {
+    return hint("OAuth authorization failed; re-run 'oytc login --oauth'")
+  }
+  for (const reason of error.reasons) {
+    if (reason.toLowerCase() === "insufficientpermissions") {
+      return hint("OAuth scopes are insufficient; re-run 'oytc login --oauth'")
+    }
+  }
+  return error
+}
+
+/**
+ * A `YouTubeApi` bound to ONE API key, ignoring any stored OAuth.
+ *
+ * Go built `a.client(key)` for the `login` probe and the `status --check`
+ * key probe, which sends `X-Goog-Api-Key` and no bearer token. The ambient
+ * `YouTubeApi` cannot stand in: its `HttpCore` attaches OAuth strictly ahead of
+ * the key whenever OAuth is stored, so with both credentials present the "API
+ * key check" would actually exercise OAuth — precisely the masking Go's
+ * comment says must not happen.
+ *
+ * `HttpClient` is not exported by `AppLayer` today, so this degrades rather
+ * than fails: when the service is absent the ambient `YouTubeApi` is used and
+ * the probe is merely less precise. Adding `HttpClient` to `AppLayer`'s
+ * exports activates the exact path with no change here.
+ */
+const keyScopedApi = (key: string, timeoutMillis: number) =>
+  Effect.gen(function* () {
+    const client = yield* Effect.serviceOption(HttpClient.HttpClient)
+    if (Option.isNone(client)) return yield* YouTubeApi
+    const core = yield* makeHttpCore({
+      apiKey: key,
+      tokenSource: undefined,
+      timeoutMillis
+    }).pipe(Effect.provideService(HttpClient.HttpClient, client.value))
+    return yield* makeYouTubeApi().pipe(Effect.provideService(HttpCore, core))
+  })
+
+/** The cheapest quota-1 probe Go used to validate an API key. */
+const probeApiKey = (
+  key: string,
+  timeoutMillis: number
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const api = yield* keyScopedApi(key, timeoutMillis)
+    yield* api.get("i18nLanguages", [["part", "snippet"]])
+  })
+
+/**
+ * `App.checkOAuth`: a liveness probe against the Analytics API, which is the
+ * service the analytics commands actually need. The window INCLUDES today,
+ * unlike the analytics flag defaults — it is a probe, not a report.
+ */
+const probeOAuth = (now: Date): Effect.Effect =>
+  Effect.gen(function* () {
+    const analytics = yield* AnalyticsApi
+    const range = statusCheckDateRange(now)
+    yield* analytics
+      .report({
+        metrics: "views",
+        dimensions: "",
+        filters: "",
+        sort: "",
+        startDate: range.start,
+        endDate: range.end,
+        limit: 1,
+        startIndex: 0
+      })
+      .pipe(Effect.mapError(oauthAuthHint))
+  })
+
+// ---------------------------------------------------------------------------
+// status: state assembly
+// ---------------------------------------------------------------------------
+
+export interface StatusChecks {
+  /** `undefined` = not checked; `null` = checked and valid; else the failure. */
+  readonly key: OytcError | null | undefined
+  readonly oauth: OytcError | null | undefined
+}
+
+/**
+ * Encode `scopes` for the target format.
+ *
+ * G1: `json`/`jsonl` get the real array (or `null` for a nil slice), while
+ * `table`/`tsv` get the JSON TEXT of that value, because Go reached those cells
+ * through `json.Marshal` rather than through the array-joining branch.
+ */
+export const encodeScopes = (
+  scopes: ReadonlyArray,
+  rowFormat: boolean
+): JsonValue => {
+  // credentialStore normalizes Go's nil slice to `[]`; Go marshalled nil as
+  // `null`, and an empty-but-non-nil slice is unreachable through `cloneOAuth`.
+  const value: JsonValue = scopes.length === 0 ? null : [...scopes]
+  return rowFormat ? encodeGoValue(value, { indent: "" }) : value
+}
+
+/** The whole `status` state object, and the ONLY place secrets could leak. */
+export const statusState = (
+  credentials: Credentials,
+  checks: StatusChecks,
+  rowFormat: boolean
+): JsonObject => {
+  const keyConfigured = credentials.key !== ""
+  const oauth = credentials.oauth
+
+  const apiKey: Record = {
+    configured: keyConfigured,
+    source: valueOr(credentials.source, "none")
+  }
+  if (keyConfigured) apiKey["fingerprint"] = fingerprintPlaceholder
+  if (checks.key !== undefined) apiKey["valid"] = checks.key === null
+
+  const oauthState: Record =
+    oauth === undefined
+      ? { configured: false }
+      : {
+          configured: true,
+          client_id: oauth.clientId,
+          scopes: encodeScopes(oauth.scopes, rowFormat),
+          expiry: oauth.expiry
+        }
+  if (oauth !== undefined && checks.oauth !== undefined) {
+    oauthState["valid"] = checks.oauth === null
+  }
+
+  return { path: credentials.path, api_key: apiKey, oauth: oauthState }
+}
+
+/**
+ * Sentinel replaced by the caller, which owns the `CredentialStore` needed to
+ * compute a fingerprint. Keeping `statusState` pure makes it directly testable
+ * against the redaction contract.
+ */
+const fingerprintPlaceholder = "fingerprint"
+
+const withFingerprint = (state: JsonObject, fingerprint: string): JsonObject => {
+  const apiKey = state["api_key"] as Record
+  if (apiKey["fingerprint"] !== fingerprintPlaceholder) return state
+  return { ...state, api_key: { ...apiKey, fingerprint } }
+}
+
+/** Go's `checkVerdict`. */
+export const checkVerdict = (error: OytcError | null): string =>
+  error === null ? "valid" : `invalid (${error.message})`
+
+/** The human `table` rendering, byte-for-byte. */
+export const statusTableText = (credentials: Credentials, checks: StatusChecks): string => {
+  const keyConfigured = credentials.key !== ""
+  const oauth = credentials.oauth
+  let out =
+    `Path: ${credentials.path}\n` +
+    `API key configured: ${keyConfigured}\n` +
+    `API key source: ${valueOr(credentials.source, "none")}\n`
+  if (keyConfigured) out += `API key fingerprint: ${fingerprintPlaceholder}\n`
+  out += `OAuth configured: ${oauth !== undefined}\n`
+  if (oauth !== undefined) {
+    out +=
+      `OAuth client ID: ${oauth.clientId}\n` +
+      // The table path joins with ", " — this is `strings.Join`, NOT `cell()`,
+      // so G1's bracket rendering does not apply here.
+      `OAuth scopes: ${oauth.scopes.join(", ")}\n` +
+      `OAuth token expiry: ${valueOr(oauth.expiry, "unknown")}\n`
+  }
+  if (checks.key !== undefined && keyConfigured) {
+    out += `API key remote check: ${checkVerdict(checks.key)}\n`
+  }
+  if (checks.oauth !== undefined && oauth !== undefined) {
+    out += `OAuth remote check: ${checkVerdict(checks.oauth)}\n`
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// login
+// ---------------------------------------------------------------------------
+
+const loginApiKey = Effect.gen(function* () {
+  const prompts = yield* Prompts
+  const store = yield* CredentialStore
+  const options = yield* AppOptions
+
+  // `readSecret` owns the prompt AND the trailing newline, matching Go's
+  // Fprint-then-ReadSecret-then-Fprintln sequence on stderr.
+  const secret = yield* prompts
+    .readSecret("YouTube Data API key: ")
+    .pipe(
+      Effect.catch((error) =>
+        Effect.fail(new OperationalError({ message: `read API key: ${error.message}`, cause: error }))
+      )
+    )
+  const key = Redacted.value(secret).trim()
+  if (key === "") return yield* Effect.fail(new UsageError({ message: "API key cannot be empty" }))
+
+  yield* probeApiKey(key, options.timeoutMillis).pipe(
+    Effect.mapError((error) =>
+      // Go: fmt.Errorf("API key validation failed: %w", err). The wrapper is an
+      // OperationalError, so a bad key exits 6 here where the bare ApiError
+      // would have exited 3 — same as Go, whose exitCode() unwraps %w and DOES
+      // still see the APIError. Preserve the code explicitly.
+      new WrappedError({ prefix: "API key validation failed", cause: error })
+    )
+  )
+
+  const path = yield* store.save(key)
+  yield* writeOut(`API key validated and saved to ${path} (${store.fingerprint(key)})\n`)
+  if (yield* store.envKeySet) {
+    yield* writeOut("Note: OYTC_API_KEY remains the active, higher-precedence credential.\n")
+  }
+})
+
+/**
+ * `fmt.Errorf("%s: %w", prefix, cause)`.
+ *
+ * Go's `exitCode(err)` walks the `%w` chain with `errors.As`, so a wrapped
+ * `APIError` still classified by its own rules. A plain `OperationalError`
+ * wrapper would flatten every such failure to 6, so the wrapper forwards both
+ * the message and the exit code of its cause.
+ */
+class WrappedError extends OperationalError {
+  constructor(args: { readonly prefix: string; readonly cause: OytcError }) {
+    super({ message: `${args.prefix}: ${args.cause.message}`, cause: args.cause })
+  }
+}
+
+const loginOAuth = Effect.gen(function* () {
+  const prompts = yield* Prompts
+  const store = yield* CredentialStore
+  const oauth = yield* OAuthService
+
+  const [bootstrapId, bootstrapSecret] = yield* store.oauthBootstrap
+
+  let clientId = bootstrapId
+  if (clientId === "") {
+    clientId = yield* prompts
+      .readLine("OAuth client ID: ")
+      .pipe(
+        Effect.catch((error) =>
+          Effect.fail(
+            new OperationalError({
+              message: `read OAuth client ID: ${error.message}`,
+              cause: error
+            })
+          )
+        )
+      )
+    clientId = clientId.trim()
+  }
+
+  let clientSecret = bootstrapSecret
+  if (clientSecret === "") {
+    const secret = yield* prompts
+      .readSecret("OAuth client secret: ")
+      .pipe(
+        Effect.catch((error) =>
+          Effect.fail(
+            new OperationalError({
+              message: `read OAuth client secret: ${error.message}`,
+              cause: error
+            })
+          )
+        )
+      )
+    clientSecret = Redacted.value(secret).trim()
+  }
+
+  if (clientId === "" || clientSecret === "") {
+    return yield* Effect.fail(
+      new UsageError({ message: "OAuth client ID and client secret cannot be empty" })
+    )
+  }
+
+  const stored = yield* oauth
+    .login({ clientId, clientSecret: Redacted.make(clientSecret) })
+    .pipe(
+      Effect.mapError((error) => new WrappedError({ prefix: "OAuth login failed", cause: error }))
+    )
+
+  const path = yield* store.saveOAuth(stored)
+  yield* writeOut(
+    `OAuth authorization saved to ${path}\nGranted scopes: ${stored.scopes.join(", ")}\n`
+  )
+})
+
+export const loginCommand = Command.make(
+  "login",
+  {
+    oauth: Flag.boolean("oauth").pipe(
+      Flag.withDescription("authorize read-only access to your channel and Analytics")
+    )
+  },
+  // A ternary between two Effects with DIFFERENT requirement sets produces a
+  // union type that is not assignable to a single Effect; suspending inside a
+  // gen block unifies both arms' R instead.
+  ({ oauth }) =>
+    Effect.gen(function* () {
+      if (oauth) yield* loginOAuth
+      else yield* loginApiKey
+    })
+).pipe(Command.withDescription("Validate and save an API key or read-only OAuth authorization"))
+
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+
+export const statusCommand = Command.make(
+  "status",
+  {
+    check: Flag.boolean("check").pipe(
+      Flag.withDescription("validate configured credentials with the API")
+    )
+  },
+  ({ check }) =>
+    Effect.gen(function* () {
+      const options = yield* AppOptions
+      const store = yield* CredentialStore
+      const credentials = yield* store.load
+
+      const keyConfigured = credentials.key !== ""
+      const oauthConfigured = credentials.oauth !== undefined
+
+      let checks: StatusChecks = { key: undefined, oauth: undefined }
+      if (check) {
+        // Nothing to validate: fail BEFORE any output, as Go did.
+        if (!keyConfigured && !oauthConfigured) {
+          return yield* Effect.fail(new MissingKeyError())
+        }
+        // Both are validated even if the first fails, so a stale API key
+        // cannot mask a working OAuth authorization or vice versa.
+        const keyResult = keyConfigured
+          ? yield* Effect.result(probeApiKey(credentials.key, options.timeoutMillis))
+          : undefined
+        const oauthResult = oauthConfigured
+          ? yield* Effect.result(probeOAuth(new Date()))
+          : undefined
+        checks = { key: failureOf(keyResult), oauth: failureOf(oauthResult) }
+      }
+
+      const fingerprint = keyConfigured ? store.fingerprint(credentials.key) : ""
+
+      if (options.format !== "table") {
+        const rowFormat = options.format === "tsv"
+        const state = withFingerprint(
+          statusState(credentials, checks, rowFormat),
+          fingerprint
+        )
+        const columns =
+          options.columns.length > 0
+            ? options.columns
+            : check
+              ? statusCheckColumns
+              : statusColumns
+        const renderer = yield* Renderer
+        yield* renderer.renderObject(state, {
+          format: options.format,
+          columns,
+          noHeader: options.noHeader
+        })
+      } else {
+        // `--columns` is silently ignored for the table rendering because Go's
+        // runStatus bypasses RenderObject entirely there. Preserved.
+        yield* writeOut(
+          statusTableText(credentials, checks).replace(fingerprintPlaceholder, fingerprint)
+        )
+      }
+
+      // Output first, THEN the non-zero exit. Key error wins over OAuth error.
+      const failure = checks.key ?? checks.oauth
+      if (failure !== null && failure !== undefined) yield* Effect.fail(failure)
+    })
+).pipe(Command.withDescription("Show API-key and OAuth status; optionally validate them"))
+
+/**
+ * A probe outcome flattened to the tri-state `StatusChecks` uses:
+ * `undefined` (not run), `null` (ran and passed), or the error.
+ */
+const failureOf = (
+  result: Result.Result | undefined
+): OytcError | null | undefined => {
+  if (result === undefined) return undefined
+  return Result.isFailure(result) ? result.failure : null
+}
+
+// ---------------------------------------------------------------------------
+// logout
+// ---------------------------------------------------------------------------
+
+export const logoutCommand = Command.make("logout", {}, () =>
+  Effect.gen(function* () {
+    const store = yield* CredentialStore
+    const oauth = yield* OAuthService
+
+    // Removal must still work when auth.json is corrupt. Revocation is
+    // impossible without parsed credentials, so warn and carry on.
+    const loaded = yield* Effect.result(store.load)
+    let stored: StoredOAuth | undefined
+    if (loaded._tag === "Success") {
+      stored = loaded.success.oauth
+    } else {
+      yield* writeErr(
+        "Warning: could not read stored credentials (skipping OAuth revocation): " +
+          `${loaded.failure.message}\n`
+      )
+    }
+
+    // `revoke` is best-effort by contract (`Effect`), so the
+    // "Warning: could not revoke OAuth token" line Go printed on a revoke
+    // failure has no trigger here — the failure is swallowed one layer down.
+    if (stored !== undefined) yield* oauth.revoke(stored)
+
+    const { path, removed } = yield* store.remove
+    yield* writeOut(
+      removed
+        ? `Removed stored credentials at ${path}.\n`
+        : `No stored credentials at ${path}.\n`
+    )
+    if (yield* store.envKeySet) {
+      yield* writeOut("OYTC_API_KEY is still set; environment credentials remain active.\n")
+    }
+  })
+).pipe(Command.withDescription("Revoke OAuth best-effort and remove stored credentials"))
+
+/** Registered by the orchestrator in root.ts. */
+export const authCommands = [loginCommand, statusCommand, logoutCommand] as const
diff --git a/src/cli/catalog.test.ts b/src/cli/catalog.test.ts
new file mode 100644
index 0000000..a66ebab
--- /dev/null
+++ b/src/cli/catalog.test.ts
@@ -0,0 +1,239 @@
+/**
+ * `oytc category list`, `oytc language list`, `oytc region list`.
+ *
+ * The defining property of these three: they take the metadata flags
+ * (`--parts`, `--fields`, `--hl`) but **no pagination flags at all**, and they
+ * send no `maxResults`. `/tmp/oytc-ref language list --page-size 5` answers
+ * `unknown flag: --page-size`, exit 2.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { categoryCommand, catalogCommands, languageCommand, regionCommand } from "./catalog.ts"
+import { expectUsage, listOf, runCli } from "./harness.testutil.ts"
+
+const runCategory = (argv: ReadonlyArray, options?: Parameters[2]) =>
+  runCli(categoryCommand, argv, options)
+const runLanguage = (argv: ReadonlyArray, options?: Parameters[2]) =>
+  runCli(languageCommand, argv, options)
+const runRegion = (argv: ReadonlyArray, options?: Parameters[2]) =>
+  runCli(regionCommand, argv, options)
+
+/** Go's zero-valued `listFlags{}`: no maxResults, no pageToken, one request. */
+const ZERO_PAGE = { all: false, limit: 0, pageSize: 0, pageToken: "" }
+
+// ---------------------------------------------------------------------------
+// category list
+// ---------------------------------------------------------------------------
+
+describe("category list", () => {
+  test("takes no positional arguments", async () => {
+    expectUsage(await runCategory(["category", "list", "extra"]), "expected 0 argument(s), received 1")
+  })
+
+  test("requires exactly one of --region or --id", async () => {
+    expectUsage(await runCategory(["category", "list"]), "provide exactly one of --region or --id")
+    expectUsage(
+      await runCategory(["category", "list", "--region", "US", "--id", "1"]),
+      "provide exactly one of --region or --id"
+    )
+  })
+
+  test("no request is made when validation fails", async () => {
+    const result = await runCategory(["category", "list"])
+    expect(result.calls).toEqual([])
+    expect(result.exitCode).toBe(2)
+  })
+
+  test("--region maps to regionCode", async () => {
+    const result = await runCategory(["category", "list", "--region", "US"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.resource).toBe("videoCategories")
+    expect(result.calls[0]!.params).toEqual({ part: "snippet", regionCode: "US" })
+  })
+
+  test("--id maps to id", async () => {
+    const result = await runCategory(["category", "list", "--id", "1,2"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.params).toEqual({ part: "snippet", id: "1,2" })
+  })
+
+  test("--hl, --parts and --fields are forwarded", async () => {
+    const result = await runCategory(
+      ["category", "list", "--region", "US", "--hl", "es", "--parts", "id", "--fields", "items"],
+      { script: { list: [listOf("[]")] } }
+    )
+    expect(result.calls[0]!.params).toEqual({
+      part: "id",
+      regionCode: "US",
+      hl: "es",
+      fields: "items"
+    })
+  })
+
+  test("SENDS NO maxResults and never follows pages", async () => {
+    const result = await runCategory(["category", "list", "--region", "US"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.page).toEqual(ZERO_PAGE)
+  })
+
+  test("has no pagination flags", async () => {
+    for (const flag of [
+      ["--page-size", "5"],
+      ["--page-token", "T"],
+      ["--all"],
+      ["--limit", "5"]
+    ]) {
+      const result = await runCategory(["category", "list", "--region", "US", ...flag])
+      expect(result.exitCode).toBe(2)
+      expect(result.calls).toEqual([])
+    }
+  })
+
+  test("renders the category default columns", async () => {
+    const result = await runCategory(["category", "list", "--region", "US"], {
+      script: { list: [listOf(`[{"id":"1","snippet":{"title":"Film","assignable":true}}]`)] }
+    })
+    // Byte-for-byte against `output.Render(..., Format: "table")` in Go.
+    expect(result.stdout).toBe("ID  SNIPPET.TITLE  SNIPPET.ASSIGNABLE\n1   Film           true\n")
+  })
+
+  test("the stderr summary reflects the single request", async () => {
+    const result = await runCategory(["category", "list", "--region", "US"], {
+      script: { list: [listOf(`[{"id":"1"},{"id":"2"}]`, 1)] }
+    })
+    expect(result.stderr).toBe("2 item(s), 1 request(s)\n")
+  })
+})
+
+describe("the category group", () => {
+  test("bare `oytc category` prints help and exits 0", async () => {
+    const result = await runCategory(["category"])
+    expect(result.exitCode).toBe(0)
+    expect(result.calls).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// language list
+// ---------------------------------------------------------------------------
+
+describe("language list", () => {
+  test("takes no positional arguments", async () => {
+    expectUsage(await runLanguage(["language", "list", "extra"]), "expected 0 argument(s), received 1")
+  })
+
+  test("needs no filter flags at all", async () => {
+    const result = await runLanguage(["language", "list"], { script: { list: [listOf("[]")] } })
+    expect(result.exitCode).toBe(0)
+    expect(result.calls[0]!.resource).toBe("i18nLanguages")
+    expect(result.calls[0]!.params).toEqual({ part: "snippet" })
+    expect(result.calls[0]!.page).toEqual(ZERO_PAGE)
+  })
+
+  test("--hl, --parts and --fields are forwarded", async () => {
+    const result = await runLanguage(
+      ["language", "list", "--hl", "ja", "--parts", "id", "--fields", "items/id"],
+      { script: { list: [listOf("[]")] } }
+    )
+    expect(result.calls[0]!.params).toEqual({ part: "id", hl: "ja", fields: "items/id" })
+  })
+
+  test("has no --region flag", async () => {
+    const result = await runLanguage(["language", "list", "--region", "US"])
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+
+  test("has no pagination flags", async () => {
+    const result = await runLanguage(["language", "list", "--page-size", "5"])
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+
+  test("renders the language default columns", async () => {
+    const result = await runLanguage(["language", "list"], {
+      script: { list: [listOf(`[{"id":"en","snippet":{"name":"English"}}]`)] }
+    })
+    expect(result.stdout).toBe("ID  SNIPPET.NAME\nen  English\n")
+  })
+})
+
+describe("the language group", () => {
+  test("bare `oytc language` prints help and exits 0", async () => {
+    const result = await runLanguage(["language"])
+    expect(result.exitCode).toBe(0)
+    expect(result.calls).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// region list
+// ---------------------------------------------------------------------------
+
+describe("region list", () => {
+  test("takes no positional arguments", async () => {
+    expectUsage(await runRegion(["region", "list", "extra"]), "expected 0 argument(s), received 1")
+  })
+
+  test("hits i18nRegions with the default part and no pagination", async () => {
+    const result = await runRegion(["region", "list"], { script: { list: [listOf("[]")] } })
+    expect(result.exitCode).toBe(0)
+    expect(result.calls[0]!.resource).toBe("i18nRegions")
+    expect(result.calls[0]!.params).toEqual({ part: "snippet" })
+    expect(result.calls[0]!.page).toEqual(ZERO_PAGE)
+  })
+
+  test("--hl is forwarded", async () => {
+    const result = await runRegion(["region", "list", "--hl", "pt"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.params).toEqual({ part: "snippet", hl: "pt" })
+  })
+
+  test("has no pagination flags", async () => {
+    const result = await runRegion(["region", "list", "--all"])
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+
+  test("renders the region default columns, including snippet.glName", async () => {
+    const result = await runRegion(["region", "list"], {
+      script: { list: [listOf(`[{"id":"US","snippet":{"name":"United States","glName":"US"}}]`)] }
+    })
+    // Byte-for-byte against `output.Render(..., Format: "table")` in Go.
+    expect(result.stdout).toBe("ID  SNIPPET.NAME   SNIPPET.GLNAME\nUS  United States  US\n")
+  })
+
+  test("--format json emits the list envelope", async () => {
+    const result = await runRegion(["region", "list", "--format", "json"], {
+      script: { list: [listOf(`[{"id":"US"}]`, 1)] }
+    })
+    expect(result.stdout).toContain('"items"')
+    expect(result.stdout).toContain('"requests": 1')
+    expect(result.stderr).toBe("")
+  })
+})
+
+describe("the region group", () => {
+  test("bare `oytc region` prints help and exits 0", async () => {
+    const result = await runRegion(["region"])
+    expect(result.exitCode).toBe(0)
+    expect(result.calls).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// registration surface
+// ---------------------------------------------------------------------------
+
+describe("catalogCommands", () => {
+  test("exports the three groups in Go's registration order", () => {
+    expect(catalogCommands).toHaveLength(3)
+    expect(catalogCommands[0]).toBe(categoryCommand)
+    expect(catalogCommands[1]).toBe(languageCommand)
+    expect(catalogCommands[2]).toBe(regionCommand)
+  })
+})
diff --git a/src/cli/catalog.ts b/src/cli/catalog.ts
index ca14f9a..836e982 100644
--- a/src/cli/catalog.ts
+++ b/src/cli/catalog.ts
@@ -1,2 +1,160 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `oytc category list`, `oytc language list`, `oytc region list` — ports
+ * `categoryCommand()`, `languageCommand()` and `regionCommand()` from
+ * `internal/cli/resources.go`.
+ *
+ * These three are the CLI's only list commands with **no pagination flags at
+ * all**: Go passes a zero-valued `listFlags{}` to `runList`, so `--page-size`,
+ * `--page-token`, `--all` and `--limit` do not exist (the reference binary
+ * answers `unknown flag: --page-size`), `maxResults` is never sent, and there is
+ * no PreRunE bounds check to run. They do take the metadata flags — `--parts`,
+ * `--fields` and `--hl` — plus, for `category`, `--region` and `--id`.
+ *
+ * Each is its own TOP-LEVEL group: `oytc category`, `oytc language`,
+ * `oytc region`. They are exported individually and as `catalogCommands` so the
+ * orchestrator can splat all three into root's subcommand list.
+ */
+
+import { Effect } from "effect"
+import { Argument, Command, Flag } from "../effect.ts"
+import { UsageError } from "../domain/errors.ts"
+import type { ListResult } from "../domain/listResult.ts"
+import { categoryListColumns, languageListColumns, regionListColumns } from "../output/columns.ts"
+import { YouTubeApi } from "../services/index.ts"
+import type { OytcError } from "../domain/errors.ts"
+import type { Params } from "../services/index.ts"
+import {
+  apiFlagsWithHl,
+  exactArgs,
+  partsOr,
+  renderResult,
+  setValues,
+  type CommandServices
+} from "./playlist.ts"
+
+/**
+ * `runList` with Go's zero-valued `listFlags{}`.
+ *
+ * Spelled out rather than reusing `pageOptions`, because the point is that
+ * nothing here comes from a flag: `pageSize: 0` means "send no maxResults" and
+ * `all: false` means "one request, never follow nextPageToken".
+ */
+const runCatalogList = (
+  resource: string,
+  params: Params,
+  defaultColumns: ReadonlyArray
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const api = yield* YouTubeApi
+    const result: ListResult = yield* api.list(resource, params, {
+      all: false,
+      limit: 0,
+      pageSize: 0,
+      pageToken: ""
+    })
+    yield* renderResult(result, defaultColumns)
+  })
+
+/**
+ * `category list` — exactly one of `--region` or `--id`.
+ *
+ * Go's `(region == "") == (ids == "")` rejects both-set and neither-set with the
+ * same message.
+ */
+export const categoryListCommand = Command.make(
+  "list",
+  {
+    args: Argument.string("ARG").pipe(Argument.variadic()),
+    region: Flag.string("region").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("ISO 3166-1 alpha-2 region code")
+    ),
+    id: Flag.string("id").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("comma-separated category IDs")
+    ),
+    ...apiFlagsWithHl
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const arity = exactArgs(0, input.args)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      if ((input.region === "") === (input.id === "")) {
+        return yield* Effect.fail(
+          new UsageError({ message: "provide exactly one of --region or --id" })
+        )
+      }
+      const params = setValues(
+        [["part", partsOr(input.parts, "snippet")]],
+        [
+          ["regionCode", input.region],
+          ["id", input.id],
+          ["hl", input.hl],
+          ["fields", input.fields]
+        ]
+      )
+      yield* runCatalogList("videoCategories", params, categoryListColumns)
+    })
+).pipe(Command.withDescription("List categories by region or IDs"))
+
+export const categoryCommand = Command.make("category").pipe(
+  Command.withDescription("Read YouTube video categories"),
+  Command.withSubcommands([categoryListCommand])
+)
+
+/** `language list` — no filters beyond the metadata flags. */
+export const languageListCommand = Command.make(
+  "list",
+  {
+    args: Argument.string("ARG").pipe(Argument.variadic()),
+    ...apiFlagsWithHl
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const arity = exactArgs(0, input.args)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      const params = setValues(
+        [["part", partsOr(input.parts, "snippet")]],
+        [
+          ["hl", input.hl],
+          ["fields", input.fields]
+        ]
+      )
+      yield* runCatalogList("i18nLanguages", params, languageListColumns)
+    })
+).pipe(Command.withDescription("List supported YouTube UI languages"))
+
+export const languageCommand = Command.make("language").pipe(
+  Command.withDescription("Read supported YouTube UI languages"),
+  Command.withSubcommands([languageListCommand])
+)
+
+/** `region list` — identical shape to `language list`, different resource. */
+export const regionListCommand = Command.make(
+  "list",
+  {
+    args: Argument.string("ARG").pipe(Argument.variadic()),
+    ...apiFlagsWithHl
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const arity = exactArgs(0, input.args)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      const params = setValues(
+        [["part", partsOr(input.parts, "snippet")]],
+        [
+          ["hl", input.hl],
+          ["fields", input.fields]
+        ]
+      )
+      yield* runCatalogList("i18nRegions", params, regionListColumns)
+    })
+).pipe(Command.withDescription("List supported YouTube regions"))
+
+export const regionCommand = Command.make("region").pipe(
+  Command.withDescription("Read supported YouTube regions"),
+  Command.withSubcommands([regionListCommand])
+)
+
+/** All three catalog groups, in the order Go's `root.AddCommand` registers them. */
+export const catalogCommands = [categoryCommand, languageCommand, regionCommand] as const
diff --git a/src/cli/channel.test.ts b/src/cli/channel.test.ts
new file mode 100644
index 0000000..77a1c08
--- /dev/null
+++ b/src/cli/channel.test.ts
@@ -0,0 +1,603 @@
+import { describe, expect, test } from "bun:test"
+import {
+  channelActivitiesCommand,
+  channelCommand,
+  channelGetCommand,
+  channelSectionsCommand,
+  channelUploadsCommand
+} from "./channel.ts"
+import { expectUsage, pageOf, responseOf, runCli, summaryLine } from "./p8aHarness.testutil.ts"
+import type { ApiScript, RunResult } from "./p8aHarness.testutil.ts"
+
+/** The five-parameter Command generic differs per command; the harness only mounts it. */
+const cmd = (c: unknown) => c as never
+
+const get = (argv: ReadonlyArray, script: ApiScript = {}): Promise =>
+  runCli(cmd(channelGetCommand), argv, { script })
+
+const activities = (argv: ReadonlyArray, script: ApiScript = {}): Promise =>
+  runCli(cmd(channelActivitiesCommand), argv, { script })
+
+const sections = (argv: ReadonlyArray, script: ApiScript = {}): Promise =>
+  runCli(cmd(channelSectionsCommand), argv, { script })
+
+const uploads = (argv: ReadonlyArray, script: ApiScript = {}): Promise =>
+  runCli(cmd(channelUploadsCommand), argv, { script })
+
+/** A `channels` lookup response carrying an uploads playlist id. */
+const uploadsLookup = (playlistId = "UUxyz") =>
+  responseOf(
+    `[{"id":"UC1","contentDetails":{"relatedPlaylists":{"uploads":${JSON.stringify(playlistId)}}}}]`
+  )
+
+/** A free channel reference: a bare UC… id costs 0 resolution requests. */
+const freeChannel = [{ id: "UC1", requests: 0 }]
+
+/** A @handle costs 1 resolution request. */
+const paidChannel = [{ id: "UC1", requests: 1 }]
+
+// ---------------------------------------------------------------------------
+// channel get
+// ---------------------------------------------------------------------------
+
+describe("channel get — validation", () => {
+  test("at least one reference is required", async () => {
+    expectUsage(await get(["get"]), "expected at least 1 argument(s), received 0")
+  })
+
+  test("owner-only parts are rejected", async () => {
+    expectUsage(
+      await get(["get", "--parts", "auditDetails", "UC1"]),
+      'part "auditDetails" requires owner/OAuth access and is not supported'
+    )
+    expectUsage(
+      await get(["get", "--parts", "snippet,contentOwnerDetails", "UC1"]),
+      'part "contentOwnerDetails" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  test("the video-only forbidden parts are NOT forbidden here", async () => {
+    const result = await get(["get", "--parts", "fileDetails", "UC1"], {
+      get: [responseOf('[{"id":"UC1"}]')],
+      channels: freeChannel
+    })
+    expect(result.exitCode).toBe(0)
+  })
+
+  test("the arg count is checked before the parts", async () => {
+    expectUsage(
+      await get(["get", "--parts", "auditDetails"]),
+      "expected at least 1 argument(s), received 0"
+    )
+  })
+})
+
+describe("channel get — resolution and request accounting", () => {
+  test("every reference is resolved, in order", async () => {
+    const result = await get(["get", "@a", "@b"], {
+      get: [responseOf('[{"id":"UC1"}]')],
+      channels: paidChannel
+    })
+    const resolves = result.calls.filter((c) => c.kind === "resolveChannel")
+    expect(resolves.map((c) => c.resource)).toEqual(["@a", "@b"])
+  })
+
+  test("a bare UC id costs 0 resolution requests: total is just the batch", async () => {
+    const result = await get(["get", "UC1"], {
+      get: [responseOf('[{"id":"UC1"}]')],
+      channels: freeChannel
+    })
+    expect(result.stderr).toBe(summaryLine(1, 1))
+  })
+
+  test("a @handle costs 1: total is resolution + batch", async () => {
+    const result = await get(["get", "@handle"], {
+      get: [responseOf('[{"id":"UC1"}]')],
+      channels: paidChannel
+    })
+    expect(result.stderr).toBe(summaryLine(1, 2))
+  })
+
+  test("two handles cost 2 resolutions plus 1 batch", async () => {
+    const result = await get(["get", "@a", "@b"], {
+      get: [responseOf('[{"id":"UC1"},{"id":"UC1"}]')],
+      channels: paidChannel
+    })
+    expect(result.stderr).toBe(summaryLine(2, 3))
+  })
+
+  test("the RESOLVED ids are what get sent, not the references", async () => {
+    const result = await get(["get", "@handle"], {
+      get: [responseOf('[{"id":"UC1"}]')],
+      channels: paidChannel
+    })
+    const fetch = result.calls.find((c) => c.kind === "get")!
+    expect(fetch.params["id"]).toBe("UC1")
+  })
+})
+
+describe("channel get — request assembly and batching", () => {
+  test("the default parts", async () => {
+    const result = await get(["get", "UC1"], {
+      get: [responseOf('[{"id":"UC1"}]')],
+      channels: freeChannel
+    })
+    const fetch = result.calls.find((c) => c.kind === "get")!
+    expect(fetch.resource).toBe("channels")
+    expect(fetch.params).toEqual({ part: "snippet,contentDetails,statistics", id: "UC1" })
+  })
+
+  test("--hl and --fields are forwarded", async () => {
+    const result = await get(["get", "--hl", "de", "--fields", "items/id", "UC1"], {
+      get: [responseOf('[{"id":"UC1"}]')],
+      channels: freeChannel
+    })
+    const fetch = result.calls.find((c) => c.kind === "get")!
+    expect(fetch.params["hl"]).toBe("de")
+    expect(fetch.params["fields"]).toBe("items/id")
+  })
+
+  test("51 references batch into 2 requests of 50 + 1", async () => {
+    const references = Array.from({ length: 51 }, (_, i) => `UC${i}`)
+    const returned = `[${references.map((id) => `{"id":"${id}"}`).join(",")}]`
+    const result = await get(["get", ...references], {
+      get: [responseOf(returned)],
+      channels: references.map((id) => ({ id, requests: 0 }))
+    })
+    const fetches = result.calls.filter((c) => c.kind === "get")
+    expect(fetches).toHaveLength(2)
+    expect(fetches[0]!.params["id"]!.split(",")).toHaveLength(50)
+    expect(fetches[1]!.params["id"]!.split(",")).toHaveLength(1)
+  })
+})
+
+describe("channel get — validateRequestedItems and --fields", () => {
+  test("a missing channel is exit 4 with the `channels` resource name", async () => {
+    const result = await get(["get", "UC1", "UC2"], {
+      get: [responseOf('[{"id":"UC1"}]')],
+      channels: [
+        { id: "UC1", requests: 0 },
+        { id: "UC2", requests: 0 }
+      ]
+    })
+    expect(result.exitCode).toBe(4)
+    expect(result.message).toBe("channels not found: UC2")
+  })
+
+  test("the equal-cardinality escape hatch applies here too", async () => {
+    const result = await get(["get", "--fields", "items/snippet/title", "UC1", "UC2"], {
+      get: [responseOf('[{"snippet":{"title":"a"}},{"snippet":{"title":"b"}}]')],
+      channels: [
+        { id: "UC1", requests: 0 },
+        { id: "UC2", requests: 0 }
+      ]
+    })
+    expect(result.exitCode).toBe(0)
+  })
+
+  test("an injected items/id is stripped from the output", async () => {
+    const result = await get(
+      ["get", "--fields", "items/snippet/title", "--format", "jsonl", "UC1"],
+      {
+        get: [responseOf('[{"id":"UC1","snippet":{"title":"T"}}]')],
+        channels: freeChannel
+      }
+    )
+    const fetch = result.calls.find((c) => c.kind === "get")!
+    expect(fetch.params["fields"]).toBe("items/snippet/title,items/id")
+    expect(result.stdout).toBe('{"snippet":{"title":"T"}}\n')
+  })
+
+  test("the default columns", async () => {
+    const result = await get(["get", "--format", "tsv", "UC1"], {
+      get: [
+        responseOf(
+          '[{"id":"UC1","snippet":{"title":"T"},"statistics":{"subscriberCount":"1","videoCount":"2","viewCount":"3"}}]'
+        )
+      ],
+      channels: freeChannel
+    })
+    expect(result.stdout).toBe(
+      "ID\tSNIPPET.TITLE\tSTATISTICS.SUBSCRIBERCOUNT\tSTATISTICS.VIDEOCOUNT\tSTATISTICS.VIEWCOUNT\n" +
+        "UC1\tT\t1\t2\t3\n"
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// channel activities
+// ---------------------------------------------------------------------------
+
+describe("channel activities — validation", () => {
+  test("exactly one channel is required", async () => {
+    expectUsage(await activities(["activities"]), "expected 1 argument(s), received 0")
+    expectUsage(await activities(["activities", "a", "b"]), "expected 1 argument(s), received 2")
+  })
+
+  test("--page-size bounds are 1..50", async () => {
+    expectUsage(
+      await activities(["activities", "--page-size", "51", "UC1"]),
+      "--page-size must be between 1 and 50"
+    )
+  })
+
+  test("bad timestamps are rejected BEFORE resolving the channel", async () => {
+    expectUsage(
+      await activities(["activities", "--published-after", "nope", "UC1"]),
+      "--published-after must be an RFC 3339 timestamp"
+    )
+    expectUsage(
+      await activities(["activities", "--published-before", "nope", "UC1"]),
+      "--published-before must be an RFC 3339 timestamp"
+    )
+  })
+
+  test("pagination is checked before the timestamps", async () => {
+    expectUsage(
+      await activities(["activities", "--page-size", "99", "--published-after", "nope", "UC1"]),
+      "--page-size must be between 1 and 50"
+    )
+  })
+
+  test("after is checked before before", async () => {
+    expectUsage(
+      await activities(["activities", "--published-after", "x", "--published-before", "y", "UC1"]),
+      "--published-after must be an RFC 3339 timestamp"
+    )
+  })
+
+  test("a valid RFC 3339 timestamp passes through", async () => {
+    const result = await activities(
+      ["activities", "--published-after", "2024-01-01T00:00:00Z", "UC1"],
+      { pages: [pageOf('[{"id":"a"}]')], channels: freeChannel }
+    )
+    expect(result.exitCode).toBe(0)
+    const list = result.calls.find((c) => c.kind === "list")!
+    expect(list.params["publishedAfter"]).toBe("2024-01-01T00:00:00Z")
+  })
+})
+
+describe("channel activities — requests and assembly", () => {
+  test("the resolved channelId, default parts, and page options", async () => {
+    const result = await activities(["activities", "UC1"], {
+      pages: [pageOf('[{"id":"a"}]')],
+      channels: freeChannel
+    })
+    const list = result.calls.find((c) => c.kind === "list")!
+    expect(list.resource).toBe("activities")
+    expect(list.params).toEqual({ part: "snippet,contentDetails", channelId: "UC1" })
+    expect(list.page!.pageSize).toBe(25)
+  })
+
+  test("the resolution cost is added to the list's own count", async () => {
+    const result = await activities(["activities", "@handle"], {
+      pages: [pageOf('[{"id":"a"}]')],
+      channels: paidChannel
+    })
+    // 1 list request + 1 resolution.
+    expect(result.stderr).toBe(summaryLine(1, 2))
+  })
+
+  test("a free UC id adds nothing", async () => {
+    const result = await activities(["activities", "UC1"], {
+      pages: [pageOf('[{"id":"a"}]')],
+      channels: freeChannel
+    })
+    expect(result.stderr).toBe(summaryLine(1, 1))
+  })
+
+  test("--all accumulates page requests plus resolution", async () => {
+    const result = await activities(["activities", "--all", "@handle"], {
+      pages: [pageOf('[{"id":"a"}]', "N"), pageOf('[{"id":"b"}]')],
+      channels: paidChannel
+    })
+    expect(result.stderr).toBe(summaryLine(2, 3))
+  })
+
+  test("--fields is passed through with NO injection", async () => {
+    const result = await activities(["activities", "--fields", "items/snippet/title", "UC1"], {
+      pages: [pageOf('[{"snippet":{"title":"T"}}]')],
+      channels: freeChannel
+    })
+    const list = result.calls.find((c) => c.kind === "list")!
+    expect(list.params["fields"]).toBe("items/snippet/title")
+  })
+
+  test("the default columns", async () => {
+    const result = await activities(["activities", "--format", "tsv", "UC1"], {
+      pages: [pageOf('[{"id":"a","snippet":{"publishedAt":"P","type":"upload","title":"T"}}]')],
+      channels: freeChannel
+    })
+    expect(result.stdout).toBe(
+      "ID\tSNIPPET.PUBLISHEDAT\tSNIPPET.TYPE\tSNIPPET.TITLE\na\tP\tupload\tT\n"
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// channel sections
+// ---------------------------------------------------------------------------
+
+describe("channel sections — the exactly-one rule", () => {
+  test("neither CHANNEL nor --id fails", async () => {
+    expectUsage(await sections(["sections"]), "provide exactly one of CHANNEL or --id")
+  })
+
+  test("BOTH CHANNEL and --id fails", async () => {
+    expectUsage(
+      await sections(["sections", "--id", "S1", "UC1"]),
+      "provide exactly one of CHANNEL or --id"
+    )
+  })
+
+  test("more than one positional is an arg-count error first", async () => {
+    expectUsage(await sections(["sections", "a", "b"]), "expected at most 1 argument(s), received 2")
+  })
+
+  test("CHANNEL alone works", async () => {
+    const result = await sections(["sections", "UC1"], {
+      get: [responseOf('[{"id":"S1"}]')],
+      channels: freeChannel
+    })
+    expect(result.exitCode).toBe(0)
+  })
+
+  test("--id alone works", async () => {
+    const result = await sections(["sections", "--id", "S1"], { get: [responseOf('[{"id":"S1"}]')] })
+    expect(result.exitCode).toBe(0)
+  })
+})
+
+describe("channel sections — requests and assembly", () => {
+  test("--id sends id and never resolves a channel", async () => {
+    const result = await sections(["sections", "--id", "S1,S2"], {
+      get: [responseOf('[{"id":"S1"}]')]
+    })
+    expect(result.calls.filter((c) => c.kind === "resolveChannel")).toHaveLength(0)
+    const fetch = result.calls.find((c) => c.kind === "get")!
+    expect(fetch.resource).toBe("channelSections")
+    expect(fetch.params).toEqual({ part: "snippet,contentDetails", id: "S1,S2" })
+    // A flat 1 request: no resolution cost.
+    expect(result.stderr).toBe(summaryLine(1, 1))
+  })
+
+  test("CHANNEL sends channelId and pays the resolution cost", async () => {
+    const result = await sections(["sections", "@handle"], {
+      get: [responseOf('[{"id":"S1"}]')],
+      channels: paidChannel
+    })
+    const fetch = result.calls.find((c) => c.kind === "get")!
+    expect(fetch.params["channelId"]).toBe("UC1")
+    expect(fetch.params).not.toHaveProperty("id")
+    expect(result.stderr).toBe(summaryLine(1, 2))
+  })
+
+  test("a free UC id costs a flat 1", async () => {
+    const result = await sections(["sections", "UC1"], {
+      get: [responseOf('[{"id":"S1"}]')],
+      channels: freeChannel
+    })
+    expect(result.stderr).toBe(summaryLine(1, 1))
+  })
+
+  test("it is a Get, so no pagination params are sent", async () => {
+    const result = await sections(["sections", "--id", "S1"], {
+      get: [responseOf('[{"id":"S1"}]')]
+    })
+    const fetch = result.calls.find((c) => c.kind === "get")!
+    expect(fetch.params).not.toHaveProperty("maxResults")
+    expect(fetch.params).not.toHaveProperty("pageToken")
+    expect(fetch.page).toBeUndefined()
+  })
+
+  test("--hl and --fields are forwarded", async () => {
+    const result = await sections(["sections", "--id", "S1", "--hl", "es", "--fields", "items/id"], {
+      get: [responseOf('[{"id":"S1"}]')]
+    })
+    const fetch = result.calls.find((c) => c.kind === "get")!
+    expect(fetch.params["hl"]).toBe("es")
+    expect(fetch.params["fields"]).toBe("items/id")
+  })
+
+  test("sections does NOT strip ids — there is no injection here", async () => {
+    const result = await sections(["sections", "--id", "S1", "--fields", "items/snippet", "--format", "jsonl"], {
+      get: [responseOf('[{"id":"S1","snippet":{"type":"t"}}]')]
+    })
+    const fetch = result.calls.find((c) => c.kind === "get")!
+    expect(fetch.params["fields"]).toBe("items/snippet")
+    expect(result.stdout).toBe('{"id":"S1","snippet":{"type":"t"}}\n')
+  })
+
+  test("the default columns", async () => {
+    const result = await sections(["sections", "--id", "S1", "--format", "tsv"], {
+      get: [responseOf('[{"id":"S1","snippet":{"type":"singlePlaylist","position":0,"title":"T"}}]')]
+    })
+    expect(result.stdout).toBe(
+      "ID\tSNIPPET.TYPE\tSNIPPET.POSITION\tSNIPPET.TITLE\nS1\tsinglePlaylist\t0\tT\n"
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// channel uploads
+// ---------------------------------------------------------------------------
+
+describe("channel uploads — validation", () => {
+  test("exactly one channel is required", async () => {
+    expectUsage(await uploads(["uploads"]), "expected 1 argument(s), received 0")
+    expectUsage(await uploads(["uploads", "a", "b"]), "expected 1 argument(s), received 2")
+  })
+
+  test("its --page-size DEFAULT is 50, not 25", async () => {
+    const result = await uploads(["uploads", "UC1"], {
+      get: [uploadsLookup()],
+      pages: [pageOf('[{"snippet":{"position":0}}]')],
+      channels: freeChannel
+    })
+    const list = result.calls.find((c) => c.kind === "list")!
+    expect(list.page!.pageSize).toBe(50)
+  })
+
+  test("its max is still 50", async () => {
+    expectUsage(
+      await uploads(["uploads", "--page-size", "51", "UC1"]),
+      "--page-size must be between 1 and 50"
+    )
+  })
+
+  test("--limit cannot be negative", async () => {
+    expectUsage(await uploads(["uploads", "--limit=-1", "UC1"]), "--limit cannot be negative")
+  })
+})
+
+describe("channel uploads — the +1 channels lookup", () => {
+  test("the lookup sends ONLY part=contentDetails and the resolved id", async () => {
+    const result = await uploads(["uploads", "--parts", "snippet", "--fields", "items/x", "UC1"], {
+      get: [uploadsLookup()],
+      pages: [pageOf('[{"snippet":{"position":0}}]')],
+      channels: freeChannel
+    })
+    const lookup = result.calls.find((c) => c.kind === "get")!
+    expect(lookup.resource).toBe("channels")
+    // The user's --parts and --fields must NOT leak into this internal probe.
+    expect(lookup.params).toEqual({ part: "contentDetails", id: "UC1" })
+  })
+
+  test("a free UC id costs 1 lookup + 1 list", async () => {
+    const result = await uploads(["uploads", "UC1"], {
+      get: [uploadsLookup()],
+      pages: [pageOf('[{"snippet":{"position":0}}]')],
+      channels: freeChannel
+    })
+    expect(result.stderr).toBe(summaryLine(1, 2))
+  })
+
+  test("a @handle costs 1 resolution + 1 lookup + 1 list", async () => {
+    const result = await uploads(["uploads", "@handle"], {
+      get: [uploadsLookup()],
+      pages: [pageOf('[{"snippet":{"position":0}}]')],
+      channels: paidChannel
+    })
+    expect(result.stderr).toBe(summaryLine(1, 3))
+  })
+
+  test("--all adds each extra page on top", async () => {
+    const result = await uploads(["uploads", "--all", "@handle"], {
+      get: [uploadsLookup()],
+      pages: [pageOf('[{"snippet":{"position":0}}]', "N"), pageOf('[{"snippet":{"position":1}}]')],
+      channels: paidChannel
+    })
+    // 1 resolution + 1 lookup + 2 list pages.
+    expect(result.stderr).toBe(summaryLine(2, 4))
+  })
+
+  test("the uploads playlist id becomes playlistId", async () => {
+    const result = await uploads(["uploads", "UC1"], {
+      get: [uploadsLookup("UUmyuploads")],
+      pages: [pageOf('[{"snippet":{"position":0}}]')],
+      channels: freeChannel
+    })
+    const list = result.calls.find((c) => c.kind === "list")!
+    expect(list.resource).toBe("playlistItems")
+    expect(list.params["playlistId"]).toBe("UUmyuploads")
+    expect(list.params["part"]).toBe("snippet,contentDetails")
+  })
+
+  test("--parts and --fields DO reach the playlistItems call", async () => {
+    const result = await uploads(["uploads", "--parts", "snippet", "--fields", "items/x", "UC1"], {
+      get: [uploadsLookup()],
+      pages: [pageOf('[{"snippet":{"position":0}}]')],
+      channels: freeChannel
+    })
+    const list = result.calls.find((c) => c.kind === "list")!
+    expect(list.params["part"]).toBe("snippet")
+    expect(list.params["fields"]).toBe("items/x")
+  })
+})
+
+describe("channel uploads — failure modes", () => {
+  test("an empty channels lookup is exit 4, quoting the ORIGINAL reference", async () => {
+    const result = await uploads(["uploads", "@handle"], {
+      get: [responseOf("[]")],
+      channels: paidChannel
+    })
+    expect(result.exitCode).toBe(4)
+    expect(result.message).toBe('channel "@handle" not found')
+  })
+
+  test("no relatedPlaylists is exit 4 with the uploads message", async () => {
+    const result = await uploads(["uploads", "@handle"], {
+      get: [responseOf('[{"id":"UC1","contentDetails":{}}]')],
+      channels: paidChannel
+    })
+    expect(result.exitCode).toBe(4)
+    expect(result.message).toBe('channel "@handle" has no public uploads playlist')
+  })
+
+  test("an EMPTY uploads id is also 'no public uploads playlist'", async () => {
+    const result = await uploads(["uploads", "UC1"], {
+      get: [uploadsLookup("")],
+      channels: freeChannel
+    })
+    expect(result.exitCode).toBe(4)
+    expect(result.message).toBe('channel "UC1" has no public uploads playlist')
+  })
+
+  test("a non-string uploads value is treated as absent", async () => {
+    const result = await uploads(["uploads", "UC1"], {
+      get: [responseOf('[{"contentDetails":{"relatedPlaylists":{"uploads":42}}}]')],
+      channels: freeChannel
+    })
+    expect(result.exitCode).toBe(4)
+  })
+
+  test("neither failure issues a playlistItems request", async () => {
+    const result = await uploads(["uploads", "UC1"], {
+      get: [responseOf("[]")],
+      channels: freeChannel
+    })
+    expect(result.calls.filter((c) => c.kind === "list")).toHaveLength(0)
+  })
+
+  test("the default columns on success", async () => {
+    const result = await uploads(["uploads", "--format", "tsv", "UC1"], {
+      get: [uploadsLookup()],
+      pages: [
+        pageOf(
+          '[{"snippet":{"position":0,"title":"T","publishedAt":"P"},"contentDetails":{"videoId":"V"}}]'
+        )
+      ],
+      channels: freeChannel
+    })
+    expect(result.stdout).toBe(
+      "SNIPPET.POSITION\tCONTENTDETAILS.VIDEOID\tSNIPPET.TITLE\tSNIPPET.PUBLISHEDAT\n0\tV\tT\tP\n"
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// the group
+// ---------------------------------------------------------------------------
+
+describe("channel — the group command", () => {
+  test("bare `oytc channel` prints help and exits 0", async () => {
+    const result = await runCli(cmd(channelCommand), ["channel"])
+    expect(result.exitCode).toBe(0)
+    expect(result.calls).toHaveLength(0)
+  })
+
+  test("every leaf is reachable through the group", async () => {
+    for (const [argv, script] of [
+      [["channel", "get", "UC1"], { get: [responseOf('[{"id":"UC1"}]')], channels: freeChannel }],
+      [["channel", "activities", "UC1"], { pages: [pageOf("[]")], channels: freeChannel }],
+      [["channel", "sections", "--id", "S1"], { get: [responseOf("[]")] }],
+      [
+        ["channel", "uploads", "UC1"],
+        { get: [uploadsLookup()], pages: [pageOf("[]")], channels: freeChannel }
+      ]
+    ] as ReadonlyArray, ApiScript]>) {
+      const result = await runCli(cmd(channelCommand), argv, { script })
+      expect(result.exitCode).toBe(0)
+    }
+  })
+})
diff --git a/src/cli/channel.ts b/src/cli/channel.ts
index ca14f9a..df0e28f 100644
--- a/src/cli/channel.ts
+++ b/src/cli/channel.ts
@@ -1,2 +1,332 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `oytc channel {get,activities,sections,uploads}`.
+ *
+ * Ports `channelGetCommand`, `channelActivitiesCommand`, `channelSectionsCommand`
+ * and `channelUploadsCommand` from `internal/cli/channel_video.go`.
+ *
+ * REQUEST ACCOUNTING is the theme of this file. Three of the four commands
+ * resolve a `@handle` / URL / `UC…` reference before they can do anything, and
+ * `ResolveChannel` costs 0 requests for a bare `UC…` id but 1 for everything
+ * else. Each command adds that cost to whatever its own fetch spent:
+ *
+ *   get         resolveCost per reference, + 1 per 50-id batch
+ *   activities  resolveCost + whatever List spent
+ *   sections    resolveCost (0 when --id was used) + 1
+ *   uploads     resolveCost + 1 (the channels lookup) + whatever List spent
+ */
+
+import { Effect, Option } from "effect"
+import { Argument, Command, Flag } from "../effect.ts"
+import { NotFoundError } from "../domain/errors.ts"
+import { isJsonObject } from "../json/value.ts"
+import type { JsonObject, JsonValue } from "../json/value.ts"
+import { goQuote } from "../impl/resolveChannel.ts"
+import {
+  channelActivitiesColumns,
+  channelGetColumns,
+  channelSectionsColumns,
+  channelUploadsColumns
+} from "../output/columns.ts"
+import { YouTubeApi } from "../services/index.ts"
+import type { Params } from "../services/index.ts"
+import { fieldsWithRequired, stripItemIds } from "./fields.ts"
+import { renderResult } from "./render.ts"
+import {
+  apiFlags,
+  apiFlagsWithHl,
+  BATCH_SIZE,
+  batch,
+  exactArgs,
+  firstFailure,
+  listFlags,
+  maximumArgs,
+  minimumArgs,
+  pageOptionsOf,
+  partsOr,
+  publishedFlags,
+  raise,
+  requireExactlyOne,
+  setValues,
+  validatePagination,
+  validateParts,
+  validateRequestedItems,
+  validateTimestamp
+} from "./validate.ts"
+
+/** Parts on `channels` that require owner/OAuth access. */
+const FORBIDDEN_CHANNEL_PARTS = ["auditDetails", "contentOwnerDetails"]
+
+/** `mapPathString(item, …path)` — a string at a nested path, or undefined. */
+const nestedString = (item: JsonObject, ...path: ReadonlyArray): string | undefined => {
+  let value: JsonValue = item
+  for (const key of path) {
+    if (!isJsonObject(value)) return undefined
+    const next: JsonValue | undefined = value[key]
+    if (next === undefined) return undefined
+    value = next
+  }
+  return typeof value === "string" ? value : undefined
+}
+
+// ---------------------------------------------------------------------------
+// channel get
+// ---------------------------------------------------------------------------
+
+/**
+ * References are resolved one at a time, IN ORDER, and the running cost is kept
+ * even when a later resolution fails — Go accumulates `requests += used` before
+ * checking `err`. That partial count is then discarded along with the result, so
+ * it is only observable as "the failure happened after N requests"; the
+ * behaviour is preserved anyway because a future caller might surface it.
+ */
+export const channelGetCommand = Command.make(
+  "get",
+  {
+    references: Argument.string("REFERENCE").pipe(
+      Argument.withDescription("Channel IDs, @handles, or channel URLs"),
+      Argument.variadic()
+    ),
+    ...apiFlagsWithHl
+  },
+  ({ references, ...api }) =>
+    Effect.gen(function* () {
+      const parts = partsOr(api.parts, "snippet,contentDetails,statistics")
+      const invalid = firstFailure([
+        minimumArgs(1, references.length),
+        validateParts(parts, FORBIDDEN_CHANNEL_PARTS)
+      ])
+      if (Option.isSome(invalid)) return yield* raise(invalid.value)
+
+      const youtube = yield* YouTubeApi
+      const ids: Array = []
+      let requests = 0
+      for (const reference of references) {
+        const resolved = yield* youtube.resolveChannel(reference)
+        requests += resolved.requests
+        ids.push(resolved.id)
+      }
+
+      const { fields: requestFields, preserve: preserveId } = fieldsWithRequired(
+        api.fields,
+        "items/id"
+      )
+      const collected: Array = []
+      for (const group of batch(ids, BATCH_SIZE)) {
+        const params: Params = setValues(
+          [
+            ["part", parts],
+            ["id", group.join(",")]
+          ],
+          { hl: api.hl, fields: requestFields }
+        )
+        const response = yield* youtube.get("channels", params)
+        requests++
+        collected.push(...((response.items ?? []) as ReadonlyArray))
+      }
+
+      // Note the resource name is the API's, `channels`, not `channel`.
+      yield* validateRequestedItems("channels", ids, collected)
+
+      yield* renderResult(
+        { items: stripItemIds(collected, preserveId), nextPageToken: "", requests },
+        channelGetColumns
+      )
+    })
+).pipe(Command.withDescription("Get channels by ID, @handle, or common channel URL"))
+
+// ---------------------------------------------------------------------------
+// channel activities
+// ---------------------------------------------------------------------------
+
+/**
+ * Both timestamp checks run BEFORE the channel is resolved, so a malformed
+ * `--published-after` costs no quota.
+ *
+ * `--fields` is passed through untouched: there is no injected field to strip,
+ * because activities are not fetched by ID.
+ */
+export const channelActivitiesCommand = Command.make(
+  "activities",
+  {
+    channels: Argument.string("CHANNEL").pipe(
+      Argument.withDescription("Channel ID, @handle, or channel URL"),
+      Argument.variadic()
+    ),
+    ...listFlags({ pageSize: 25 }),
+    ...apiFlags,
+    ...publishedFlags
+  },
+  ({ channels, publishedAfter, publishedBefore, ...rest }) =>
+    Effect.gen(function* () {
+      const invalid = firstFailure([
+        exactArgs(1, channels.length),
+        validatePagination(rest, 50),
+        validateTimestamp("--published-after", publishedAfter),
+        validateTimestamp("--published-before", publishedBefore)
+      ])
+      if (Option.isSome(invalid)) return yield* raise(invalid.value)
+
+      const youtube = yield* YouTubeApi
+      const resolved = yield* youtube.resolveChannel(channels[0]!)
+
+      const params: Params = setValues(
+        [
+          ["part", partsOr(rest.parts, "snippet,contentDetails")],
+          ["channelId", resolved.id]
+        ],
+        { publishedAfter, publishedBefore, fields: rest.fields }
+      )
+      const result = yield* youtube.list("activities", params, pageOptionsOf(rest))
+      yield* renderResult(
+        { ...result, requests: result.requests + resolved.requests },
+        channelActivitiesColumns
+      )
+    })
+).pipe(Command.withDescription("List a channel's public activities"))
+
+// ---------------------------------------------------------------------------
+// channel sections
+// ---------------------------------------------------------------------------
+
+/**
+ * Exactly one of the positional CHANNEL or `--id` — Go's test is
+ * `(ids == "") == (len(args) == 0)`, which fails when both are given AND when
+ * neither is.
+ *
+ * This is a `Get`, not a `List`: no `maxResults`, no `pageToken`, no `--all`,
+ * and the request count is a flat 1 plus whatever resolution cost.
+ */
+export const channelSectionsCommand = Command.make(
+  "sections",
+  {
+    channels: Argument.string("CHANNEL").pipe(
+      Argument.withDescription("Channel ID, @handle, or channel URL"),
+      Argument.variadic()
+    ),
+    ...apiFlagsWithHl,
+    id: Flag.string("id").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("comma-separated channel section IDs")
+    )
+  },
+  ({ channels, id, ...api }) =>
+    Effect.gen(function* () {
+      const invalid = firstFailure([
+        maximumArgs(1, channels.length),
+        requireExactlyOne(id === "", channels.length === 0, "provide exactly one of CHANNEL or --id")
+      ])
+      if (Option.isSome(invalid)) return yield* raise(invalid.value)
+
+      const youtube = yield* YouTubeApi
+      let params: Params = [["part", partsOr(api.parts, "snippet,contentDetails")]]
+      let requests = 0
+      if (id !== "") {
+        params = [...params, ["id", id]]
+      } else {
+        const resolved = yield* youtube.resolveChannel(channels[0]!)
+        requests += resolved.requests
+        params = [...params, ["channelId", resolved.id]]
+      }
+      params = setValues(params, { hl: api.hl, fields: api.fields })
+
+      const response = yield* youtube.get("channelSections", params)
+      yield* renderResult(
+        {
+          items: (response.items ?? []) as ReadonlyArray,
+          nextPageToken: "",
+          requests: requests + 1
+        },
+        channelSectionsColumns
+      )
+    })
+).pipe(Command.withDescription("List a channel's sections or get section IDs"))
+
+// ---------------------------------------------------------------------------
+// channel uploads
+// ---------------------------------------------------------------------------
+
+/**
+ * The most expensive command in the package: resolve the reference, look the
+ * channel up to read `contentDetails.relatedPlaylists.uploads`, then paginate
+ * that playlist. The lookup is a hard `+1` on top of the resolution cost.
+ *
+ * Both failure messages quote the ORIGINAL reference (`args[0]`), not the
+ * resolved `UC…` id, so `oytc channel uploads @handle` says `@handle`. Both are
+ * bare `fmt.Errorf`s in Go, classified to exit 4 by their message text
+ * ("not found" and "no public uploads" are both in the substring table); a
+ * `NotFoundError` carries that code directly.
+ *
+ * The channel lookup deliberately sends only `part=contentDetails` — NOT the
+ * user's `--parts`, and NOT their `--fields`, because it is an internal probe
+ * whose result is never rendered.
+ */
+export const channelUploadsCommand = Command.make(
+  "uploads",
+  {
+    channels: Argument.string("CHANNEL").pipe(
+      Argument.withDescription("Channel ID, @handle, or channel URL"),
+      Argument.variadic()
+    ),
+    ...listFlags({ pageSize: 50 }),
+    ...apiFlags
+  },
+  ({ channels, ...rest }) =>
+    Effect.gen(function* () {
+      const invalid = firstFailure([exactArgs(1, channels.length), validatePagination(rest, 50)])
+      if (Option.isSome(invalid)) return yield* raise(invalid.value)
+
+      const reference = channels[0]!
+      const youtube = yield* YouTubeApi
+      const resolved = yield* youtube.resolveChannel(reference)
+      let requests = resolved.requests
+
+      const lookup = yield* youtube.get("channels", [
+        ["part", "contentDetails"],
+        ["id", resolved.id]
+      ])
+      requests++
+
+      const first = (lookup.items ?? [])[0] as JsonObject | undefined
+      if (first === undefined) {
+        return yield* Effect.fail(
+          new NotFoundError({ message: `channel ${goQuote(reference)} not found` })
+        )
+      }
+      const uploads = nestedString(first, "contentDetails", "relatedPlaylists", "uploads")
+      if (uploads === undefined || uploads === "") {
+        return yield* Effect.fail(
+          new NotFoundError({
+            message: `channel ${goQuote(reference)} has no public uploads playlist`
+          })
+        )
+      }
+
+      const params: Params = setValues(
+        [
+          ["part", partsOr(rest.parts, "snippet,contentDetails")],
+          ["playlistId", uploads]
+        ],
+        { fields: rest.fields }
+      )
+      const result = yield* youtube.list("playlistItems", params, pageOptionsOf(rest))
+      yield* renderResult(
+        { ...result, requests: result.requests + requests },
+        channelUploadsColumns
+      )
+    })
+).pipe(Command.withDescription("Resolve and enumerate a channel's uploads playlist"))
+
+// ---------------------------------------------------------------------------
+// The group
+// ---------------------------------------------------------------------------
+
+/** A group command with NO handler: `oytc channel` prints help and exits 0. */
+export const channelCommand = Command.make("channel").pipe(
+  Command.withDescription("Read channels, activities, sections, and uploads"),
+  Command.withSubcommands([
+    channelGetCommand,
+    channelActivitiesCommand,
+    channelSectionsCommand,
+    channelUploadsCommand
+  ])
+)
diff --git a/src/cli/comment.test.ts b/src/cli/comment.test.ts
new file mode 100644
index 0000000..55a1738
--- /dev/null
+++ b/src/cli/comment.test.ts
@@ -0,0 +1,434 @@
+/**
+ * `oytc comment {get,replies,threads}`.
+ *
+ * The two facts this suite exists to pin:
+ *   - `comment get` batches in **100s**, not 50s.
+ *   - `--order` is compared against the LITERAL DEFAULT `"time"`, so
+ *     `--id X --order time` passes and `--id X --order ""` fails.
+ *
+ * Both, plus every message below, were captured from `/tmp/oytc-ref`.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { NotFoundError } from "../domain/errors.ts"
+import { commentCommand } from "./comment.ts"
+import { expectUsage, listOf, responseOf, runCli, summaryLine } from "./harness.testutil.ts"
+
+const run = (argv: ReadonlyArray, options?: Parameters[2]) =>
+  runCli(commentCommand, argv, options)
+
+// ---------------------------------------------------------------------------
+// comment get
+// ---------------------------------------------------------------------------
+
+describe("comment get", () => {
+  test("requires at least one id, before any request", async () => {
+    const result = await run(["comment", "get"])
+    expectUsage(result, "expected at least 1 argument(s), received 0")
+    expect(result.calls).toEqual([])
+  })
+
+  test("the arity check precedes the --text-format enum", async () => {
+    const result = await run(["comment", "get", "--text-format", "bogus"])
+    expectUsage(result, "expected at least 1 argument(s), received 0")
+  })
+
+  test("rejects an unknown --text-format", async () => {
+    const result = await run(["comment", "get", "C1", "--text-format", "bogus"])
+    expectUsage(result, "--text-format must be one of: plainText, html")
+    expect(result.calls).toEqual([])
+  })
+
+  test("accepts both allowed text formats", async () => {
+    for (const format of ["plainText", "html"]) {
+      const result = await run(["comment", "get", "C1", "--text-format", format], {
+        script: { get: [responseOf(`[{"id":"C1"}]`)] }
+      })
+      expect(result.exitCode).toBe(0)
+      expect(result.calls[0]!.params["textFormat"]).toBe(format)
+    }
+  })
+
+  test("defaults part to snippet and textFormat to plainText", async () => {
+    const result = await run(["comment", "get", "C1"], {
+      script: { get: [responseOf(`[{"id":"C1"}]`)] }
+    })
+    expect(result.calls[0]!.resource).toBe("comments")
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet",
+      id: "C1",
+      textFormat: "plainText"
+    })
+  })
+
+  test("BATCHES IN 100s, not 50s", async () => {
+    const ids = Array.from({ length: 250 }, (_, index) => `C${index}`)
+    const script = {
+      get: [
+        responseOf(JSON.stringify(ids.slice(0, 100).map((id) => ({ id })))),
+        responseOf(JSON.stringify(ids.slice(100, 200).map((id) => ({ id })))),
+        responseOf(JSON.stringify(ids.slice(200).map((id) => ({ id }))))
+      ]
+    }
+    const result = await run(["comment", "get", ...ids], { script })
+    expect(result.exitCode).toBe(0)
+    expect(result.calls).toHaveLength(3)
+    expect(result.calls[0]!.params["id"]!.split(",")).toHaveLength(100)
+    expect(result.calls[1]!.params["id"]!.split(",")).toHaveLength(100)
+    expect(result.calls[2]!.params["id"]!.split(",")).toHaveLength(50)
+    expect(result.stderr).toBe(summaryLine(250, 3))
+  })
+
+  test("exactly 100 ids is a single request", async () => {
+    const ids = Array.from({ length: 100 }, (_, index) => `C${index}`)
+    const result = await run(["comment", "get", ...ids], {
+      script: { get: [responseOf(JSON.stringify(ids.map((id) => ({ id }))))] }
+    })
+    expect(result.calls).toHaveLength(1)
+  })
+
+  test("101 ids is two requests", async () => {
+    const ids = Array.from({ length: 101 }, (_, index) => `C${index}`)
+    const result = await run(["comment", "get", ...ids], {
+      script: {
+        get: [
+          responseOf(JSON.stringify(ids.slice(0, 100).map((id) => ({ id })))),
+          responseOf(JSON.stringify(ids.slice(100).map((id) => ({ id }))))
+        ]
+      }
+    })
+    expect(result.calls).toHaveLength(2)
+    expect(result.calls[1]!.params["id"]).toBe("C100")
+  })
+
+  test("widens --fields to keep items/id and strips it before rendering", async () => {
+    const result = await run(["comment", "get", "C1", "--fields", "items/snippet"], {
+      script: { get: [responseOf(`[{"id":"C1","snippet":{"textDisplay":"hi"}}]`)] }
+    })
+    expect(result.calls[0]!.params["fields"]).toBe("items/snippet,items/id")
+    expect(result.stdout).not.toContain("C1")
+    expect(result.stdout).toContain("hi")
+  })
+
+  test("a missing id is a NotFoundError with exit 4", async () => {
+    const result = await run(["comment", "get", "C1", "C2"], {
+      script: { get: [responseOf(`[{"id":"C1"}]`)] }
+    })
+    expect(result.error).toBeInstanceOf(NotFoundError)
+    expect(result.message).toBe("comments not found: C2")
+    expect(result.exitCode).toBe(4)
+  })
+
+  test("has no pagination flags and no --hl", async () => {
+    for (const flag of [
+      ["--page-size", "5"],
+      ["--hl", "en"],
+      ["--all"]
+    ]) {
+      const result = await run(["comment", "get", "C1", ...flag])
+      expect(result.exitCode).toBe(2)
+      expect(result.calls).toEqual([])
+    }
+  })
+
+  test("renders the shared comment columns", async () => {
+    const result = await run(["comment", "get", "C1"], {
+      script: {
+        get: [
+          responseOf(
+            `[{"id":"C1","snippet":{"authorDisplayName":"A","textDisplay":"T","likeCount":2,"publishedAt":"2024-01-01T00:00:00Z"}}]`
+          )
+        ]
+      }
+    })
+    // Byte-for-byte against `output.Render(..., Format: "table")` in Go.
+    expect(result.stdout).toBe(
+      "ID  SNIPPET.AUTHORDISPLAYNAME  SNIPPET.TEXTDISPLAY  SNIPPET.LIKECOUNT  SNIPPET.PUBLISHEDAT\n" +
+        "C1  A                          T                    2                  2024-01-01T00:00:00Z\n"
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// comment replies
+// ---------------------------------------------------------------------------
+
+describe("comment replies", () => {
+  test("requires exactly one parent id", async () => {
+    expectUsage(await run(["comment", "replies"]), "expected 1 argument(s), received 0")
+    expectUsage(await run(["comment", "replies", "a", "b"]), "expected 1 argument(s), received 2")
+  })
+
+  test("the arity check precedes the page-size bound", async () => {
+    const result = await run(["comment", "replies", "--page-size", "999"])
+    expectUsage(result, "expected 1 argument(s), received 0")
+  })
+
+  test("page size defaults to 20", async () => {
+    const result = await run(["comment", "replies", "C1"], { script: { list: [listOf("[]")] } })
+    expect(result.calls[0]!.page?.pageSize).toBe(20)
+  })
+
+  test("page size maxes at 100, NOT 50", async () => {
+    const ok = await run(["comment", "replies", "C1", "--page-size", "100"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(ok.exitCode).toBe(0)
+    expect(ok.calls[0]!.page?.pageSize).toBe(100)
+
+    const over = await run(["comment", "replies", "C1", "--page-size", "101"])
+    expectUsage(over, "--page-size must be between 1 and 100")
+  })
+
+  test("page size 0 is rejected", async () => {
+    expectUsage(
+      await run(["comment", "replies", "C1", "--page-size", "0"]),
+      "--page-size must be between 1 and 100"
+    )
+  })
+
+  test("the page-size bound precedes the --text-format enum", async () => {
+    const result = await run([
+      "comment",
+      "replies",
+      "C1",
+      "--text-format",
+      "bogus",
+      "--page-size",
+      "101"
+    ])
+    expectUsage(result, "--page-size must be between 1 and 100")
+  })
+
+  test("--limit cannot be negative, and that precedes --text-format", async () => {
+    const result = await run([
+      "comment",
+      "replies",
+      "C1",
+      "--limit=-1",
+      "--text-format",
+      "bogus"
+    ])
+    expectUsage(result, "--limit cannot be negative")
+  })
+
+  test("rejects an unknown --text-format", async () => {
+    expectUsage(
+      await run(["comment", "replies", "C1", "--text-format", "bogus"]),
+      "--text-format must be one of: plainText, html"
+    )
+  })
+
+  test("assembles parentId and forwards textFormat and fields", async () => {
+    const result = await run(
+      ["comment", "replies", "C1", "--text-format", "html", "--fields", "items"],
+      { script: { list: [listOf("[]")] } }
+    )
+    expect(result.calls[0]!.resource).toBe("comments")
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet",
+      parentId: "C1",
+      textFormat: "html",
+      fields: "items"
+    })
+  })
+
+  test("--parts overrides the default part", async () => {
+    const result = await run(["comment", "replies", "C1", "--parts", "id"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.params["part"]).toBe("id")
+  })
+
+  test("has no --hl flag", async () => {
+    const result = await run(["comment", "replies", "C1", "--hl", "en"])
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// comment threads
+// ---------------------------------------------------------------------------
+
+describe("comment threads", () => {
+  test("takes no positional arguments", async () => {
+    expectUsage(await run(["comment", "threads", "extra"]), "expected 0 argument(s), received 1")
+  })
+
+  test("the arity check precedes the page-size bound", async () => {
+    const result = await run(["comment", "threads", "extra", "--page-size", "999"])
+    expectUsage(result, "expected 0 argument(s), received 1")
+  })
+
+  test("page size defaults to 20 and maxes at 100", async () => {
+    const ok = await run(["comment", "threads", "--video", "V1"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(ok.calls[0]!.page?.pageSize).toBe(20)
+
+    expectUsage(
+      await run(["comment", "threads", "--video", "V1", "--page-size", "101"]),
+      "--page-size must be between 1 and 100"
+    )
+  })
+
+  test("the page-size bound precedes every semantic check", async () => {
+    // No filter is set AND --order is bogus, yet the page size still wins.
+    const result = await run(["comment", "threads", "--order", "bogus", "--page-size", "999"])
+    expectUsage(result, "--page-size must be between 1 and 100")
+  })
+
+  test("--text-format is checked before --order", async () => {
+    const result = await run([
+      "comment",
+      "threads",
+      "--order",
+      "bogus",
+      "--text-format",
+      "bogus"
+    ])
+    expectUsage(result, "--text-format must be one of: plainText, html")
+  })
+
+  test("rejects an unknown --order with the golden message", async () => {
+    const result = await run(["comment", "threads", "--order", "bogus"])
+    expectUsage(result, "--order must be one of: time, relevance")
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+
+  test("--order is checked before the filter XOR", async () => {
+    // Both would fail; --order comes first in Go's RunE.
+    const result = await run(["comment", "threads", "--order", "bogus", "--video", "V", "--channel", "C"])
+    expectUsage(result, "--order must be one of: time, relevance")
+  })
+
+  test("requires exactly one of --video, --channel or --id", async () => {
+    expectUsage(
+      await run(["comment", "threads"]),
+      "provide exactly one of --video, --channel, or --id"
+    )
+    expectUsage(
+      await run(["comment", "threads", "--video", "V", "--channel", "C"]),
+      "provide exactly one of --video, --channel, or --id"
+    )
+    expectUsage(
+      await run(["comment", "threads", "--video", "V", "--channel", "C", "--id", "I"]),
+      "provide exactly one of --video, --channel, or --id"
+    )
+  })
+
+  test("a valid --order alone still fails the filter check", async () => {
+    expectUsage(
+      await run(["comment", "threads", "--order", "relevance"]),
+      "provide exactly one of --video, --channel, or --id"
+    )
+  })
+
+  test("--id with a non-default --order is rejected", async () => {
+    expectUsage(
+      await run(["comment", "threads", "--id", "T1", "--order", "relevance"]),
+      "--order and --search are incompatible with --id"
+    )
+  })
+
+  test("--id with --search is rejected", async () => {
+    expectUsage(
+      await run(["comment", "threads", "--id", "T1", "--search", "foo"]),
+      "--order and --search are incompatible with --id"
+    )
+  })
+
+  test("LITERAL DEFAULT: --id with an explicit --order time is ACCEPTED", async () => {
+    const result = await run(["comment", "threads", "--id", "T1", "--order", "time"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.exitCode).toBe(0)
+    expect(result.calls[0]!.params["order"]).toBe("time")
+  })
+
+  test("LITERAL DEFAULT: --id with an empty --order is REJECTED", async () => {
+    // "" passes validateEnum but is != "time", so the --id check fires.
+    expectUsage(
+      await run(["comment", "threads", "--id", "T1", "--order="]),
+      "--order and --search are incompatible with --id"
+    )
+  })
+
+  test("--id alone is accepted and sends id, not videoId", async () => {
+    const result = await run(["comment", "threads", "--id", "T1,T2"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.resource).toBe("commentThreads")
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet,replies",
+      id: "T1,T2",
+      order: "time",
+      textFormat: "plainText"
+    })
+  })
+
+  test("--video maps to videoId", async () => {
+    const result = await run(["comment", "threads", "--video", "V1", "--search", "hi"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet,replies",
+      videoId: "V1",
+      order: "time",
+      searchTerms: "hi",
+      textFormat: "plainText"
+    })
+  })
+
+  test("--channel maps to allThreadsRelatedToChannelId", async () => {
+    const result = await run(["comment", "threads", "--channel", "UC1"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.params["allThreadsRelatedToChannelId"]).toBe("UC1")
+    expect(result.calls[0]!.params["channelId"]).toBeUndefined()
+  })
+
+  test("the default part is snippet,replies", async () => {
+    const result = await run(["comment", "threads", "--video", "V1"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.params["part"]).toBe("snippet,replies")
+  })
+
+  test("renders the thread default columns", async () => {
+    const result = await run(["comment", "threads", "--video", "V1"], {
+      script: {
+        list: [
+          listOf(
+            `[{"id":"T1","snippet":{"topLevelComment":{"snippet":{"authorDisplayName":"A","textDisplay":"D"}},"totalReplyCount":4}}]`
+          )
+        ]
+      }
+    })
+    // Byte-for-byte against `output.Render(..., Format: "table")` in Go.
+    expect(result.stdout).toBe(
+      "ID  SNIPPET.TOPLEVELCOMMENT.SNIPPET.AUTHORDISPLAYNAME  SNIPPET.TOPLEVELCOMMENT.SNIPPET.TEXTDISPLAY  SNIPPET.TOTALREPLYCOUNT\n" +
+        "T1  A                                                  D                                            4\n"
+    )
+  })
+
+  test("has no --hl flag", async () => {
+    const result = await run(["comment", "threads", "--video", "V1", "--hl", "en"])
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// group command
+// ---------------------------------------------------------------------------
+
+describe("the comment group", () => {
+  test("bare `oytc comment` prints help and exits 0", async () => {
+    const result = await run(["comment"])
+    expect(result.exitCode).toBe(0)
+    expect(result.calls).toEqual([])
+  })
+})
diff --git a/src/cli/comment.ts b/src/cli/comment.ts
index ca14f9a..c487c2c 100644
--- a/src/cli/comment.ts
+++ b/src/cli/comment.ts
@@ -1,2 +1,189 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `oytc comment {get,replies,threads}` — ports `commentCommand()` and friends
+ * from `internal/cli/resources.go`.
+ *
+ * Two things here are easy to get wrong and are both pinned by tests:
+ *
+ *  1. **Batch size is 100, not 50.** `comment get` groups ids in hundreds;
+ *     every other by-ID command in the CLI uses 50.
+ *  2. **`--order` is compared against the literal default string**, not against
+ *     "was the flag changed". `comment threads --id X --order time` is accepted
+ *     because the VALUE equals the default, so explicitly passing the default
+ *     alongside `--id` is legal — and `--order ""` is REJECTED even though it
+ *     means "unset", because `"" != "time"`. Verified against the reference
+ *     binary both ways.
+ *
+ * Shared helpers come from `./playlist.ts` — see the header there for why they
+ * live in this package rather than in P8a's `validate.ts`/`fields.ts`.
+ */
+
+import { Effect } from "effect"
+import { Argument, Command, Flag } from "../effect.ts"
+import { UsageError } from "../domain/errors.ts"
+import { commentColumns, commentThreadsColumns } from "../output/columns.ts"
+import {
+  apiFlags,
+  exactArgs,
+  listFlags,
+  minimumArgs,
+  partsOr,
+  runBatchGet,
+  runList,
+  setValues,
+  validateEnum,
+  validateListFlags
+} from "./playlist.ts"
+
+/** `--text-format`, shared by all three leaves. Default `plainText`. */
+const textFormatFlag = Flag.string("text-format").pipe(
+  Flag.withDefault("plainText"),
+  Flag.withDescription("plainText or html (default \"plainText\")")
+)
+
+/** `comment get ...` — batch size **100**, `minimumArgs(1)`. */
+export const commentGetCommand = Command.make(
+  "get",
+  {
+    args: Argument.string("COMMENT_ID").pipe(Argument.variadic()),
+    textFormat: textFormatFlag,
+    ...apiFlags
+  },
+  (input) =>
+    Effect.gen(function* () {
+      // Go checks arity (cobra Args) before RunE, so the arity error wins over
+      // a bad --text-format: `comment get` with no ids reports the argument
+      // count even when --text-format is also invalid.
+      const arity = minimumArgs(1, input.args)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      const format = validateEnum("--text-format", input.textFormat, "plainText", "html")
+      if (format !== undefined) return yield* Effect.fail(format)
+
+      yield* runBatchGet({
+        resource: "comments",
+        ids: input.args,
+        batchSize: 100,
+        part: partsOr(input.parts, "snippet"),
+        fields: input.fields,
+        extra: [["textFormat", input.textFormat]],
+        defaultColumns: commentColumns
+      })
+    })
+).pipe(Command.withDescription("Get comments by ID"))
+
+/**
+ * `comment replies ` — page size 1..**100**, default **20**.
+ */
+export const commentRepliesCommand = Command.make(
+  "replies",
+  {
+    args: Argument.string("PARENT_COMMENT_ID").pipe(Argument.variadic()),
+    textFormat: textFormatFlag,
+    ...listFlags(20, 100),
+    ...apiFlags
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const arity = exactArgs(1, input.args)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      const bounds = validateListFlags(input, 100)
+      if (bounds !== undefined) return yield* Effect.fail(bounds)
+      const format = validateEnum("--text-format", input.textFormat, "plainText", "html")
+      if (format !== undefined) return yield* Effect.fail(format)
+
+      const params = setValues(
+        [
+          ["part", partsOr(input.parts, "snippet")],
+          ["parentId", input.args[0]!]
+        ],
+        [
+          ["textFormat", input.textFormat],
+          ["fields", input.fields]
+        ]
+      )
+      yield* runList("comments", params, input, commentColumns)
+    })
+).pipe(Command.withDescription("List replies to a top-level comment"))
+
+/**
+ * `comment threads` — page size 1..**100**, default **20**.
+ *
+ * RunE check order (each verified against the reference binary):
+ *   1. `--text-format` enum        (beats a bad `--order`)
+ *   2. `--order` enum
+ *   3. exactly one of `--video` / `--channel` / `--id`
+ *   4. `--id` incompatibility with `--order`/`--search`
+ *
+ * Step 4 uses `order != "time"` — the DEFAULT STRING — so `--id X --order time`
+ * passes while `--id X --order ""` fails.
+ */
+export const commentThreadsCommand = Command.make(
+  "threads",
+  {
+    args: Argument.string("ARG").pipe(Argument.variadic()),
+    video: Flag.string("video").pipe(Flag.withDefault(""), Flag.withDescription("video ID")),
+    channel: Flag.string("channel").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("channel ID")
+    ),
+    id: Flag.string("id").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("comma-separated thread IDs")
+    ),
+    order: Flag.string("order").pipe(
+      Flag.withDefault("time"),
+      Flag.withDescription("time or relevance (default \"time\")")
+    ),
+    search: Flag.string("search").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("restrict to comments containing these terms")
+    ),
+    textFormat: textFormatFlag,
+    ...listFlags(20, 100),
+    ...apiFlags
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const arity = exactArgs(0, input.args)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      const bounds = validateListFlags(input, 100)
+      if (bounds !== undefined) return yield* Effect.fail(bounds)
+
+      const format = validateEnum("--text-format", input.textFormat, "plainText", "html")
+      if (format !== undefined) return yield* Effect.fail(format)
+      const order = validateEnum("--order", input.order, "time", "relevance")
+      if (order !== undefined) return yield* Effect.fail(order)
+
+      const filters = [input.video, input.channel, input.id].filter((v) => v !== "").length
+      if (filters !== 1) {
+        return yield* Effect.fail(
+          new UsageError({ message: "provide exactly one of --video, --channel, or --id" })
+        )
+      }
+      // Literal-default comparison, deliberately not "flag was changed".
+      if (input.id !== "" && (input.order !== "time" || input.search !== "")) {
+        return yield* Effect.fail(
+          new UsageError({ message: "--order and --search are incompatible with --id" })
+        )
+      }
+
+      const params = setValues(
+        [["part", partsOr(input.parts, "snippet,replies")]],
+        [
+          ["videoId", input.video],
+          ["allThreadsRelatedToChannelId", input.channel],
+          ["id", input.id],
+          ["order", input.order],
+          ["searchTerms", input.search],
+          ["textFormat", input.textFormat],
+          ["fields", input.fields]
+        ]
+      )
+      yield* runList("commentThreads", params, input, commentThreadsColumns)
+    })
+).pipe(Command.withDescription("List comment threads by video, channel, or IDs"))
+
+/** The `comment` group. Bare `oytc comment` prints help and exits 0. */
+export const commentCommand = Command.make("comment").pipe(
+  Command.withDescription("Read public comments and comment threads"),
+  Command.withSubcommands([commentGetCommand, commentRepliesCommand, commentThreadsCommand])
+)
diff --git a/src/cli/fields.test.ts b/src/cli/fields.test.ts
new file mode 100644
index 0000000..a78d386
--- /dev/null
+++ b/src/cli/fields.test.ts
@@ -0,0 +1,272 @@
+import { describe, expect, test } from "bun:test"
+import { parseJson } from "../json/parse.ts"
+import { Result } from "effect"
+import type { JsonObject } from "../json/value.ts"
+import {
+  fieldSelectorIncludes,
+  fieldSelectorPaths,
+  fieldsWithRequired,
+  stripItemIds,
+  stripSearchKind,
+  stripSearchKinds
+} from "./fields.ts"
+
+const obj = (text: string): JsonObject => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as JsonObject
+}
+
+const objs = (text: string): ReadonlyArray => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as ReadonlyArray
+}
+
+describe("fieldSelectorPaths", () => {
+  test("a flat comma list", () => {
+    expect(fieldSelectorPaths("items,nextPageToken")).toEqual(["items", "nextPageToken"])
+  })
+
+  test("slash nesting builds one path", () => {
+    expect(fieldSelectorPaths("items/id/videoId")).toEqual(["items/id/videoId"])
+  })
+
+  test("parenthesised groups distribute the prefix", () => {
+    expect(fieldSelectorPaths("items(id/videoId,snippet/title),nextPageToken")).toEqual([
+      "items/id/videoId",
+      "items/snippet/title",
+      "nextPageToken"
+    ])
+  })
+
+  test("nested groups", () => {
+    expect(fieldSelectorPaths("items(id(kind,videoId))")).toEqual([
+      "items/id/kind",
+      "items/id/videoId"
+    ])
+  })
+
+  test("whitespace around every delimiter is skipped", () => {
+    expect(fieldSelectorPaths("items ( id / kind , snippet/title ) , nextPageToken")).toEqual([
+      "items/id/kind",
+      "items/snippet/title",
+      "nextPageToken"
+    ])
+  })
+
+  test("tabs, CR and LF count as whitespace", () => {
+    expect(fieldSelectorPaths("items\t(\r\nid/kind\n)")).toEqual(["items/id/kind"])
+  })
+
+  test("an empty selector produces no paths", () => {
+    expect(fieldSelectorPaths("")).toEqual([])
+  })
+
+  test("a stray delimiter is consumed and contributes nothing", () => {
+    expect(fieldSelectorPaths("/items")).toEqual(["items"])
+    expect(fieldSelectorPaths(")")).toEqual([])
+  })
+
+  test("a wildcard is just a name", () => {
+    expect(fieldSelectorPaths("items/*")).toEqual(["items/*"])
+    expect(fieldSelectorPaths("*")).toEqual(["*"])
+  })
+
+  test("an unterminated group still yields its members", () => {
+    expect(fieldSelectorPaths("items(id/kind")).toEqual(["items/id/kind"])
+  })
+
+  test("a multi-byte name survives; Go slices bytes, JS slices UTF-16 units", () => {
+    // Every delimiter is ASCII, so the two agree on every boundary.
+    expect(fieldSelectorPaths("items/naïve,items/日本")).toEqual([
+      "items/naïve",
+      "items/日本"
+    ])
+  })
+})
+
+/**
+ * The exact table from `internal/cli/fields_test.go:TestFieldSelectorIncludes`.
+ */
+describe("fieldSelectorIncludes(_, 'items/id') — the Go table", () => {
+  const cases: ReadonlyArray = [
+    ["", false],
+    ["items", true],
+    ["items/*", true],
+    ["items/id", true],
+    ["items(id/videoId,snippet/title),nextPageToken", true],
+    ["items(snippet/title),nextPageToken", false],
+    ["items/snippet/resourceId/channelId", false]
+  ]
+  for (const [selector, want] of cases) {
+    test(`${JSON.stringify(selector)} -> ${want}`, () => {
+      expect(fieldSelectorIncludes(selector, "items/id")).toBe(want)
+    })
+  }
+})
+
+/** `TestFieldSelectorIncludesNestedSearchKind`, verbatim. */
+describe("fieldSelectorIncludes(_, 'items/id/kind') — the Go table", () => {
+  const cases: ReadonlyArray = [
+    ["items", true],
+    ["items/id", true],
+    ["items/id/*", true],
+    ["items/id/kind", true],
+    ["items(id/kind,snippet/title)", true],
+    ["items(id/*,snippet/title)", true],
+    ["items(id/channelId,snippet/title)", false],
+    ["items(id/videoId,snippet/title)", false]
+  ]
+  for (const [selector, want] of cases) {
+    test(`${JSON.stringify(selector)} -> ${want}`, () => {
+      expect(fieldSelectorIncludes(selector, "items/id/kind")).toBe(want)
+    })
+  }
+})
+
+describe("fieldSelectorIncludes — the five match rules individually", () => {
+  test("rule 1: a bare '*' covers everything", () => {
+    expect(fieldSelectorIncludes("*", "items/id")).toBe(true)
+    expect(fieldSelectorIncludes("*", "items/id/kind")).toBe(true)
+  })
+
+  test("rule 1: a bare 'items' covers everything under items", () => {
+    expect(fieldSelectorIncludes("nextPageToken,items", "items/id/kind")).toBe(true)
+  })
+
+  test("rule 2: exact equality", () => {
+    expect(fieldSelectorIncludes("items/id", "items/id")).toBe(true)
+  })
+
+  test("rule 3: the selector asks for something DEEPER than the target", () => {
+    expect(fieldSelectorIncludes("items/id/videoId", "items/id")).toBe(true)
+  })
+
+  test("rule 4: the selector asks for an ANCESTOR of the target", () => {
+    expect(fieldSelectorIncludes("items/id", "items/id/kind")).toBe(true)
+  })
+
+  test("rule 5: a trailing /* covers everything below its parent", () => {
+    expect(fieldSelectorIncludes("items/id/*", "items/id/kind")).toBe(true)
+    // The wildcard parent must be a STRICT prefix; "items/id/*" does not make
+    // "items/idOther/x" match.
+    expect(fieldSelectorIncludes("items/id/*", "items/idOther/kind")).toBe(false)
+  })
+
+  test("a sibling path does not match", () => {
+    expect(fieldSelectorIncludes("items/snippet", "items/id")).toBe(false)
+  })
+
+  test("a prefix that is not a path boundary does not match", () => {
+    expect(fieldSelectorIncludes("items/idx", "items/id")).toBe(false)
+  })
+})
+
+describe("fieldsWithRequired", () => {
+  test("an empty selector is left alone and preserves", () => {
+    expect(fieldsWithRequired("", "items/id")).toEqual({ fields: "", preserve: true })
+  })
+
+  test("an already-covering selector is left alone and preserves", () => {
+    expect(fieldsWithRequired("items/id,items/snippet", "items/id")).toEqual({
+      fields: "items/id,items/snippet",
+      preserve: true
+    })
+  })
+
+  test("a non-covering selector gets the required path appended", () => {
+    expect(fieldsWithRequired("items/snippet/title", "items/id")).toEqual({
+      fields: "items/snippet/title,items/id",
+      preserve: false
+    })
+  })
+
+  test("search injects items/id/kind, not items/id", () => {
+    expect(fieldsWithRequired("items(id/videoId)", "items/id/kind")).toEqual({
+      fields: "items(id/videoId),items/id/kind",
+      preserve: false
+    })
+  })
+
+  test("a selector asking for id/videoId still covers items/id", () => {
+    // Rule 3: deeper than the target. So the batch-get commands do NOT inject.
+    expect(fieldsWithRequired("items(id/videoId)", "items/id").preserve).toBe(true)
+  })
+})
+
+describe("stripItemIds", () => {
+  test("preserve=true returns the items untouched, identically", () => {
+    const items = objs('[{"id":"a","snippet":{"title":"t"}}]')
+    expect(stripItemIds(items, true)).toBe(items)
+  })
+
+  test("preserve=false deletes id from every item", () => {
+    const items = objs('[{"id":"a","snippet":{"title":"t"}},{"id":"b"}]')
+    expect(stripItemIds(items, false)).toEqual([{ snippet: { title: "t" } }, {}])
+  })
+
+  test("an item without an id is unharmed", () => {
+    expect(stripItemIds(objs('[{"snippet":{"title":"t"}}]'), false)).toEqual([
+      { snippet: { title: "t" } }
+    ])
+  })
+
+  test("the input array is not mutated", () => {
+    const items = objs('[{"id":"a"}]')
+    stripItemIds(items, false)
+    expect(items).toEqual([{ id: "a" }])
+  })
+
+  test("non-id keys keep their relative order", () => {
+    const [stripped] = stripItemIds(objs('[{"z":"1","id":"a","b":"2"}]'), false)
+    expect(Object.keys(stripped!)).toEqual(["z", "b"])
+  })
+})
+
+describe("stripSearchKind", () => {
+  test("kind is removed but siblings keep id alive", () => {
+    expect(stripSearchKind(obj('{"id":{"kind":"youtube#video","videoId":"v"}}'))).toEqual({
+      id: { videoId: "v" }
+    })
+  })
+
+  test("id is dropped entirely when kind was its only key", () => {
+    expect(stripSearchKind(obj('{"id":{"kind":"youtube#video"},"snippet":{"title":"t"}}'))).toEqual(
+      { snippet: { title: "t" } }
+    )
+  })
+
+  test("an id that is a plain string is left alone", () => {
+    // channels/videos return a string id; only search returns an object.
+    expect(stripSearchKind(obj('{"id":"UC123"}'))).toEqual({ id: "UC123" })
+  })
+
+  test("a missing id is left alone", () => {
+    expect(stripSearchKind(obj('{"snippet":{"title":"t"}}'))).toEqual({
+      snippet: { title: "t" }
+    })
+  })
+
+  test("an id object without a kind is left with its other keys", () => {
+    expect(stripSearchKind(obj('{"id":{"videoId":"v"}}'))).toEqual({ id: { videoId: "v" } })
+  })
+
+  test("an id that is null is left alone", () => {
+    expect(stripSearchKind(obj('{"id":null}'))).toEqual({ id: null })
+  })
+})
+
+describe("stripSearchKinds", () => {
+  test("preserve=true is a no-op returning the same array", () => {
+    const items = objs('[{"id":{"kind":"youtube#video","videoId":"v"}}]')
+    expect(stripSearchKinds(items, true)).toBe(items)
+  })
+
+  test("preserve=false strips every item", () => {
+    const items = objs(
+      '[{"id":{"kind":"youtube#video","videoId":"v"}},{"id":{"kind":"youtube#channel"}}]'
+    )
+    expect(stripSearchKinds(items, false)).toEqual([{ id: { videoId: "v" } }, {}])
+  })
+})
diff --git a/src/cli/fields.ts b/src/cli/fields.ts
index ca14f9a..dc45eb1 100644
--- a/src/cli/fields.ts
+++ b/src/cli/fields.ts
@@ -1,2 +1,211 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Google partial-response `--fields` selector support.
+ *
+ * Ports `internal/cli/fields.go` (the grammar parser) plus the three call-site
+ * helpers that live in `internal/cli/app.go`: `fieldsWithRequired`,
+ * `stripItemIDs`, and the id/kind deletion half of `searchResultFilter`.
+ *
+ * The shape of the problem: several commands need a field in the response that
+ * the user's own selector may have excluded — `items/id` for the batch-get
+ * commands, `items/id/kind` for `search`'s client-side kind filter. So the
+ * outbound selector is rewritten to append the required path, and the injected
+ * key is deleted from every item again before rendering, leaving the user with
+ * exactly what they asked for.
+ *
+ * SHARED HELPER — P8b and P8c import from here read-only. Do not edit outside
+ * P8a.
+ */
+
+import { isJsonObject } from "../json/value.ts"
+import type { JsonObject, JsonValue } from "../json/value.ts"
+
+// ---------------------------------------------------------------------------
+// The grammar parser
+// ---------------------------------------------------------------------------
+
+/**
+ * The delimiter set `readName` stops on, and (minus `/`, `(`, `)`, `,`) the set
+ * `skipSpaces` consumes. Transcribed from `strings.ContainsRune("/(), \t\r\n", …)`.
+ *
+ * Go indexes the selector by BYTE while JS indexes by UTF-16 code unit. Every
+ * delimiter here is ASCII, so both slice at identical boundaries and any
+ * multi-byte name survives intact either way.
+ */
+const NAME_TERMINATORS = new Set(["/", "(", ")", ",", " ", "\t", "\r", "\n"])
+const SPACES = new Set([" ", "\t", "\r", "\n"])
+
+class FieldSelectorParser {
+  position = 0
+  constructor(readonly selector: string) {}
+
+  /**
+   * `terminator` of `""` is Go's zero byte: no terminator, run to the end.
+   */
+  parseList(prefix: ReadonlyArray, terminator: string): ReadonlyArray {
+    const paths: Array = []
+    while (this.position < this.selector.length) {
+      this.skipSpacesAndCommas()
+      if (this.position >= this.selector.length) break
+      if (terminator !== "" && this.selector[this.position] === terminator) {
+        this.position++
+        break
+      }
+      paths.push(...this.parseField(prefix))
+    }
+    return paths
+  }
+
+  parseField(prefix: ReadonlyArray): ReadonlyArray {
+    const name = this.readName()
+    if (name === "") {
+      // A stray `/`, `(` or `)`; consume it and contribute nothing.
+      this.position++
+      return []
+    }
+    const path = [...prefix, name]
+    this.skipSpaces()
+    if (this.position >= this.selector.length) return [path.join("/")]
+    switch (this.selector[this.position]) {
+      case "/":
+        this.position++
+        this.skipSpaces()
+        return this.parseField(path)
+      case "(":
+        this.position++
+        return this.parseList(path, ")")
+      default:
+        return [path.join("/")]
+    }
+  }
+
+  readName(): string {
+    const start = this.position
+    while (
+      this.position < this.selector.length &&
+      !NAME_TERMINATORS.has(this.selector[this.position]!)
+    ) {
+      this.position++
+    }
+    return this.selector.slice(start, this.position)
+  }
+
+  skipSpacesAndCommas(): void {
+    while (this.position < this.selector.length) {
+      const ch = this.selector[this.position]!
+      if (ch !== "," && !SPACES.has(ch)) break
+      this.position++
+    }
+  }
+
+  skipSpaces(): void {
+    while (this.position < this.selector.length && SPACES.has(this.selector[this.position]!)) {
+      this.position++
+    }
+  }
+}
+
+/** Every `a/b/c` path a selector expands to, groups flattened. */
+export const fieldSelectorPaths = (selector: string): ReadonlyArray =>
+  new FieldSelectorParser(selector).parseList([], "")
+
+/**
+ * Does `selector` already cover `target`?
+ *
+ * True when ANY expanded path satisfies one of:
+ *   - the path is `*` or the bare `items` (everything under items is returned)
+ *   - the path IS the target
+ *   - the path is deeper than the target (`items/id/kind` covers `items/id`)
+ *   - the path is an ancestor of the target (`items/id` covers `items/id/kind`)
+ *   - the path ends in `/*` and the target is under that parent
+ *
+ * All five rules are load-bearing; `internal/cli/fields_test.go` pins them.
+ */
+export const fieldSelectorIncludes = (selector: string, target: string): boolean => {
+  for (const path of fieldSelectorPaths(selector)) {
+    const wildcardParent = path.endsWith("/*") ? path.slice(0, -2) : path
+    if (
+      path === "*" ||
+      path === "items" ||
+      path === target ||
+      path.startsWith(`${target}/`) ||
+      target.startsWith(`${path}/`) ||
+      (wildcardParent !== path && target.startsWith(`${wildcardParent}/`))
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// Request rewriting
+// ---------------------------------------------------------------------------
+
+export interface RequiredFields {
+  /** The selector to actually send; `""` still means "send no fields param". */
+  readonly fields: string
+  /**
+   * True when the required path was already covered (or no selector was given
+   * at all), so nothing has to be stripped from the response afterwards.
+   */
+  readonly preserve: boolean
+}
+
+/**
+ * `fieldsWithRequired` — append `,` unless the user's selector
+ * already covers it.
+ *
+ * An empty selector reports `preserve: true`: no partial response was
+ * requested, so every field is present and nothing is injected.
+ */
+export const fieldsWithRequired = (fields: string, required: string): RequiredFields =>
+  fields === "" || fieldSelectorIncludes(fields, required)
+    ? { fields, preserve: true }
+    : { fields: `${fields},${required}`, preserve: false }
+
+// ---------------------------------------------------------------------------
+// Response stripping
+// ---------------------------------------------------------------------------
+
+const omit = (object: JsonObject, key: string): JsonObject => {
+  const next: Record = {}
+  for (const name of Object.keys(object)) {
+    if (name !== key) next[name] = object[name]!
+  }
+  return next
+}
+
+/**
+ * `stripItemIDs` — drop the injected `items/id` from every item.
+ *
+ * Go mutates the maps in place; here `JsonObject` is deeply readonly, so a new
+ * item is produced. Nested key order is irrelevant: the JSON encoder sorts
+ * every nested object and the table/TSV writers address cells by path.
+ */
+export const stripItemIds = (
+  items: ReadonlyArray,
+  preserve: boolean
+): ReadonlyArray => (preserve ? items : items.map((item) => omit(item, "id")))
+
+/**
+ * The deletion half of `searchResultFilter`: drop the injected `id.kind`, and
+ * drop `id` entirely when that emptied it.
+ *
+ * Go performs this inside the page filter, on accepted items only. Doing it
+ * after the list returns is equivalent — the accepted items ARE the result
+ * items — and is the only option here, because a filter predicate over readonly
+ * values cannot mutate.
+ */
+export const stripSearchKind = (item: JsonObject): JsonObject => {
+  const id = item["id"]
+  if (id === undefined || !isJsonObject(id)) return item
+  const nextId = omit(id, "kind")
+  if (Object.keys(nextId).length === 0) return omit(item, "id")
+  return { ...item, id: nextId }
+}
+
+/** `stripSearchKind` over a page, skipped wholesale when the kind is preserved. */
+export const stripSearchKinds = (
+  items: ReadonlyArray,
+  preserve: boolean
+): ReadonlyArray => (preserve ? items : items.map(stripSearchKind))
diff --git a/src/cli/globals.ts b/src/cli/globals.ts
index 78b8eb5..d0accf7 100644
--- a/src/cli/globals.ts
+++ b/src/cli/globals.ts
@@ -48,7 +48,7 @@ export const resolveGlobals = (
     return Result.fail(new UsageError({ message: timeout.failure.message }))
   }
   if (timeout.success <= 0) {
-    return Result.fail(new UsageError({ message: "--timeout must be greater than zero" }))
+    return Result.fail(new UsageError({ message: "--timeout must be positive" }))
   }
 
   const fallback: OutputFormat =
diff --git a/src/cli/harness.testutil.ts b/src/cli/harness.testutil.ts
new file mode 100644
index 0000000..31c0a22
--- /dev/null
+++ b/src/cli/harness.testutil.ts
@@ -0,0 +1,274 @@
+/**
+ * Test harness for the P8b command tests.
+ *
+ * Not a `.test.ts` — bun would try to run it as a suite. It is imported by
+ * `playlist.test.ts`, `comment.test.ts`, `subscription.test.ts` and
+ * `catalog.test.ts`.
+ *
+ * `runCli` drives a command through the REAL `Command.runWith` with explicit
+ * argv, a real `RendererLive` over a capturing `Stdio`, and a scripted
+ * `YouTubeApi` that records every request. That means flag parsing, defaulting,
+ * validation order, param assembly, pagination options and rendering are all
+ * under test end-to-end — only the network is faked.
+ *
+ * A local root command mirrors `src/cli/root.ts` (which this package must not
+ * edit and which does not yet register these subcommands): same shared global
+ * flags, same `Command.provide` order, same `resolveGlobals`. `isOutputTTY`
+ * defaults to true so the default format is `table` and the stderr summary line
+ * is exercised.
+ */
+
+import { Cause, Effect, Exit, Layer, Result, Runtime, Sink, Stdio } from "effect"
+import { Command } from "../effect.ts"
+import { exitCodeFor, UsageError } from "../domain/errors.ts"
+import type { OytcError } from "../domain/errors.ts"
+import type { ListResult, PageOptions } from "../domain/listResult.ts"
+import { parseJson } from "../json/parse.ts"
+import type { JsonObject } from "../json/value.ts"
+import { RendererLive } from "../impl/renderer.ts"
+import { AppOptions, YouTubeApi } from "../services/index.ts"
+import type { Params, ResolvedChannel, YouTubeApiShape } from "../services/index.ts"
+import type { DataApiResponse } from "../schema/dataapi.ts"
+import { globalFlags } from "./flags.ts"
+import { resolveGlobals } from "./globals.ts"
+
+/** One recorded call into the fake YouTube API. */
+export interface RecordedCall {
+  readonly kind: "get" | "list" | "resolveChannel"
+  readonly resource: string
+  /** Params as a plain object; every command sends each key at most once. */
+  readonly params: Record
+  readonly page?: PageOptions | undefined
+}
+
+export interface ApiScript {
+  /** Consumed in order by `get`; the last entry repeats. */
+  readonly get?: ReadonlyArray | undefined
+  /** Consumed in order by `list`; the last entry repeats. */
+  readonly list?: ReadonlyArray | undefined
+  /** When set, every call fails with this error instead. */
+  readonly fail?: OytcError | undefined
+}
+
+export interface RunResult {
+  readonly stdout: string
+  readonly stderr: string
+  /** 0 on success, else the error's `exitCodeFor`. */
+  readonly exitCode: number
+  /** `undefined` on success. */
+  readonly error: OytcError | undefined
+  /** The error message exactly as `main.ts` would print it after `oytc: `. */
+  readonly message: string | undefined
+  readonly calls: ReadonlyArray
+}
+
+/** Parse a JSON literal into items, for building fake responses concisely. */
+export const items = (text: string): ReadonlyArray => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as ReadonlyArray
+}
+
+/** A `ListResult` from a JSON array literal. */
+export const listOf = (text: string, requests = 1, nextPageToken = ""): ListResult => ({
+  items: items(text),
+  nextPageToken,
+  requests
+})
+
+/** A `DataApiResponse` from a JSON array literal. */
+export const responseOf = (text: string): DataApiResponse => ({
+  items: items(text) as DataApiResponse["items"]
+})
+
+const paramsToObject = (params: Params): Record => {
+  const out: Record = {}
+  for (const [key, value] of params) out[key] = value
+  return out
+}
+
+export interface RunOptions {
+  /** Defaults to true, so the default format is `table`. */
+  readonly isOutputTTY?: boolean | undefined
+  readonly script?: ApiScript | undefined
+}
+
+/**
+ * Run one command with explicit argv.
+ *
+ * The command under test is mounted under a root that reproduces root.ts's
+ * mandatory composition order: `withSharedFlags` -> `withSubcommands` ->
+ * `provide`.
+ */
+export const runCli = (
+  // The concrete Command type is a five-parameter generic whose Input differs
+  // per command; the harness only ever passes it to `withSubcommands`.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  command: any,
+  argv: ReadonlyArray,
+  options: RunOptions = {}
+): Promise => {
+  const isOutputTTY = options.isOutputTTY ?? true
+  const script = options.script ?? {}
+  const calls: Array = []
+  const stdout: Array = []
+  const stderr: Array = []
+
+  let getIndex = 0
+  let listIndex = 0
+
+  const pick = (source: ReadonlyArray | undefined, index: number, fallback: A): A => {
+    if (source === undefined || source.length === 0) return fallback
+    return source[Math.min(index, source.length - 1)]!
+  }
+
+  const api: YouTubeApiShape = {
+    get: (resource, params) =>
+      Effect.suspend(() => {
+        calls.push({ kind: "get", resource, params: paramsToObject(params) })
+        if (script.fail !== undefined) return Effect.fail(script.fail)
+        const response = pick(script.get, getIndex, { items: [] } as DataApiResponse)
+        getIndex++
+        return Effect.succeed(response)
+      }),
+    list: (resource, params, page) =>
+      Effect.suspend(() => {
+        calls.push({ kind: "list", resource, params: paramsToObject(params), page })
+        if (script.fail !== undefined) return Effect.fail(script.fail)
+        const result = pick(script.list, listIndex, {
+          items: [],
+          nextPageToken: "",
+          requests: 1
+        } as ListResult)
+        listIndex++
+        return Effect.succeed(result)
+      }),
+    resolveChannel: (reference) =>
+      Effect.suspend(() => {
+        calls.push({ kind: "resolveChannel", resource: reference, params: {} })
+        if (script.fail !== undefined) return Effect.fail(script.fail)
+        return Effect.succeed({ id: reference, requests: 1 } satisfies ResolvedChannel)
+      })
+  }
+
+  const stdio = Stdio.layerTest({
+    stdout: () =>
+      Sink.forEach((input: string | Uint8Array) =>
+        Effect.sync(() => {
+          stdout.push(typeof input === "string" ? input : new TextDecoder().decode(input))
+        })
+      ),
+    stderr: () =>
+      Sink.forEach((input: string | Uint8Array) =>
+        Effect.sync(() => {
+          stderr.push(typeof input === "string" ? input : new TextDecoder().decode(input))
+        })
+      )
+  })
+
+  const testLayer = Layer.mergeAll(
+    stdio,
+    Layer.succeed(YouTubeApi, api),
+    RendererLive.pipe(Layer.provide(stdio))
+  )
+
+  const root = mountRoot(command, isOutputTTY)
+
+  return Effect.runPromise(
+    Effect.exit(
+      Command.runWith(root, { version: "test" })(argv).pipe(
+        Effect.provide(testLayer)
+      ) as Effect.Effect
+    )
+  ).then((exit) => {
+    if (Exit.isSuccess(exit)) {
+      return {
+        stdout: stdout.join(""),
+        stderr: stderr.join(""),
+        exitCode: 0,
+        error: undefined,
+        message: undefined,
+        calls
+      }
+    }
+    const squashed = Cause.squash(exit.cause) as {
+      readonly _tag?: string
+      readonly message?: string
+      readonly [Runtime.errorExitCode]?: number
+    }
+    const tagged = isOytcError(squashed) ? squashed : undefined
+    return {
+      stdout: stdout.join(""),
+      stderr: stderr.join(""),
+      exitCode: tagged === undefined ? frameworkExitCode(squashed) : exitCodeFor(tagged),
+      error: tagged,
+      message: tagged?.message ?? squashed.message,
+      calls
+    }
+  })
+}
+
+/**
+ * Exit code for an error raised by the CLI framework rather than by a handler.
+ *
+ * `CliError.ShowHelp` carries `Runtime.errorExitCode` directly, and it is **0**
+ * when `errors` is empty — that is the `oytc playlist` / `--help` path, which
+ * Go also exits 0 on. A non-empty `errors` list (unknown flag, unknown
+ * subcommand, bad choice) is exit 1 in the framework where Go exits 2, so it is
+ * translated here.
+ */
+const frameworkExitCode = (error: { readonly [Runtime.errorExitCode]?: number }): number => {
+  const code = error[Runtime.errorExitCode]
+  if (code === 0) return 0
+  return 2
+}
+
+const OYTC_TAGS = new Set([
+  "UsageError",
+  "MissingKeyError",
+  "MissingOAuthError",
+  "ApiError",
+  "OAuthError",
+  "AuthHintError",
+  "NotFoundError",
+  "OperationalError",
+  "CancelledError"
+])
+
+const isOytcError = (u: { readonly _tag?: string }): u is OytcError =>
+  typeof u._tag === "string" && OYTC_TAGS.has(u._tag)
+
+/** The local stand-in for `src/cli/root.ts`. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const mountRoot = (command: any, isOutputTTY: boolean) =>
+  Command.make("oytc").pipe(
+    Command.withSharedFlags(globalFlags),
+    Command.withSubcommands([command]),
+    Command.provide((input) =>
+      Layer.effect(
+        AppOptions,
+        Effect.suspend(() => {
+          const resolved = resolveGlobals(input, { isOutputTTY })
+          return Result.isFailure(resolved)
+            ? Effect.fail(resolved.failure)
+            : Effect.succeed(resolved.success)
+        })
+      )
+    )
+  )
+
+/** Assert helper: the single stderr line a table render appends. */
+export const summaryLine = (itemCount: number, requests: number, nextPageToken = ""): string =>
+  `${itemCount} item(s), ${requests} request(s)${
+    nextPageToken === "" ? "" : `; more available (next token: ${nextPageToken})`
+  }\n`
+
+/** Every usage failure in this package must precede any HTTP call. */
+export const expectUsage = (result: RunResult, message: string): void => {
+  if (!(result.error instanceof UsageError)) {
+    throw new Error(`expected UsageError, got ${String(result.error?._tag)}: ${String(result.message)}`)
+  }
+  if (result.message !== message) {
+    throw new Error(`expected message ${JSON.stringify(message)}, got ${JSON.stringify(result.message)}`)
+  }
+}
diff --git a/src/cli/livechat.test.ts b/src/cli/livechat.test.ts
new file mode 100644
index 0000000..f7bd521
--- /dev/null
+++ b/src/cli/livechat.test.ts
@@ -0,0 +1,937 @@
+/**
+ * `live-chat list` / `live-chat stream` tests.
+ *
+ * The stream loop's seams are all injected (`StreamDeps`), so the dedup rules,
+ * the header rule, the interval fallback and the four clean-exit conditions are
+ * tested directly against `pollLiveChat` without a process, a socket or a
+ * signal. The command wrapper is then driven through `Command.runWith` for the
+ * validation order, the jsonl override and the resolution path.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Effect, Exit, Layer, Sink, Stdio } from "effect"
+import { Command } from "../effect.ts"
+import {
+  ApiError,
+  NotFoundError,
+  OperationalError,
+  UsageError,
+  type OytcError
+} from "../domain/errors.ts"
+import type { ListResult } from "../domain/listResult.ts"
+import type { JsonObject } from "../json/value.ts"
+import { rawNumber } from "../json/value.ts"
+import type { DataApiResponse } from "../schema/dataapi.ts"
+import { makeRendererWith } from "../impl/renderer.ts"
+import { liveChatColumns } from "../output/columns.ts"
+import { globalFlags } from "./flags.ts"
+import {
+  AppOptions,
+  ProcessEnv,
+  Renderer,
+  YouTubeApi,
+  type AppOptionsShape,
+  type OutputFormat,
+  type Params,
+  type RenderOptions,
+  type RendererShape
+} from "../services/index.ts"
+import {
+  dedupeBatch,
+  formatFlagProvided,
+  isLiveChatEnded,
+  liveChatCommand,
+  liveChatListCommand,
+  liveChatParams,
+  liveChatStreamCommand,
+  pollInterval,
+  pollLiveChat,
+  resolveChatId,
+  resolveStreamFormat,
+  validateLiveChatFlags,
+  type LiveChatFlagValues
+} from "./livechat.ts"
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const flags = (overrides?: Partial): LiveChatFlagValues => ({
+  video: "",
+  chatId: "chat-1",
+  pageSize: 500,
+  pageToken: "",
+  limit: 0,
+  profileSize: 88,
+  parts: "snippet,authorDetails",
+  fields: "",
+  ...overrides
+})
+
+const message = (id: string, text = "hi"): JsonObject => ({
+  id,
+  snippet: { publishedAt: "2026-01-01T00:00:00Z", displayMessage: text, type: "textMessageEvent" },
+  authorDetails: { displayName: "Ann" }
+})
+
+/** A `Renderer` that records every (result, options) pair instead of writing. */
+const recordingRenderer = (): {
+  readonly renderer: RendererShape
+  readonly calls: Array<{ result: ListResult; options: RenderOptions }>
+} => {
+  const calls: Array<{ result: ListResult; options: RenderOptions }> = []
+  return {
+    calls,
+    renderer: {
+      render: (result, options) => Effect.sync(() => void calls.push({ result, options })),
+      renderObject: () => Effect.void
+    }
+  }
+}
+
+/** A scripted API: each call returns the next scripted page (or error). */
+const scriptedApi = (
+  pages: ReadonlyArray
+): {
+  readonly get: (resource: string, params: Params) => Effect.Effect
+  readonly calls: Array
+} => {
+  const calls: Array = []
+  let index = 0
+  return {
+    calls,
+    get: (resource, params) =>
+      Effect.suspend(() => {
+        calls.push([resource, params])
+        const page = pages[Math.min(index, pages.length - 1)]
+        index++
+        if (page === undefined) return Effect.succeed({ items: [] })
+        return page instanceof Error
+          ? Effect.fail(page as OytcError)
+          : Effect.succeed(page as DataApiResponse)
+      })
+  }
+}
+
+const streamDeps = (
+  api: { readonly get: (r: string, p: Params) => Effect.Effect },
+  renderer: RendererShape,
+  overrides?: {
+    readonly format?: OutputFormat
+    readonly columns?: ReadonlyArray
+    readonly noHeader?: boolean
+    readonly stopped?: () => boolean
+  }
+) => ({
+  api: {
+    get: api.get,
+    list: () => Effect.succeed({ items: [], nextPageToken: "", requests: 0 }),
+    resolveChannel: () => Effect.succeed({ id: "", requests: 0 })
+  },
+  renderer,
+  format: overrides?.format ?? ("jsonl" as OutputFormat),
+  columns: overrides?.columns ?? liveChatColumns,
+  noHeader: overrides?.noHeader ?? false,
+  stopped: overrides?.stopped ?? (() => false)
+})
+
+// ---------------------------------------------------------------------------
+// Flag validation — Go's PreRunE order
+// ---------------------------------------------------------------------------
+
+describe("validateLiveChatFlags", () => {
+  test("neither --video nor --chat-id is rejected", () => {
+    const error = validateLiveChatFlags(flags({ chatId: "" }))
+    expect(error?.message).toBe("provide exactly one of --video or --chat-id")
+  })
+
+  test("both --video and --chat-id is rejected", () => {
+    const error = validateLiveChatFlags(flags({ video: "v", chatId: "c" }))
+    expect(error?.message).toBe("provide exactly one of --video or --chat-id")
+  })
+
+  test("either alone is accepted", () => {
+    expect(validateLiveChatFlags(flags({ chatId: "c" }))).toBeUndefined()
+    expect(validateLiveChatFlags(flags({ video: "v", chatId: "" }))).toBeUndefined()
+  })
+
+  test("--page-size bounds are 200..2000 inclusive, NOT 1..50", () => {
+    expect(validateLiveChatFlags(flags({ pageSize: 199 }))?.message).toBe(
+      "--page-size must be between 200 and 2000"
+    )
+    expect(validateLiveChatFlags(flags({ pageSize: 2001 }))?.message).toBe(
+      "--page-size must be between 200 and 2000"
+    )
+    expect(validateLiveChatFlags(flags({ pageSize: 200 }))).toBeUndefined()
+    expect(validateLiveChatFlags(flags({ pageSize: 2000 }))).toBeUndefined()
+  })
+
+  test("--profile-image-size bounds are 16..720 inclusive", () => {
+    expect(validateLiveChatFlags(flags({ profileSize: 15 }))?.message).toBe(
+      "--profile-image-size must be between 16 and 720"
+    )
+    expect(validateLiveChatFlags(flags({ profileSize: 721 }))?.message).toBe(
+      "--profile-image-size must be between 16 and 720"
+    )
+    expect(validateLiveChatFlags(flags({ profileSize: 16 }))).toBeUndefined()
+  })
+
+  test("a negative --limit is rejected", () => {
+    expect(validateLiveChatFlags(flags({ limit: -1 }))?.message).toBe(
+      "--limit cannot be negative"
+    )
+    expect(validateLiveChatFlags(flags({ limit: 0 }))).toBeUndefined()
+  })
+
+  test("the mutual-exclusion check runs BEFORE the range checks", () => {
+    // Both invalid: Go reports the exclusion error, not the page-size one.
+    const error = validateLiveChatFlags(flags({ chatId: "", pageSize: 5 }))
+    expect(error?.message).toBe("provide exactly one of --video or --chat-id")
+  })
+
+  test("page-size is checked before profile-image-size", () => {
+    const error = validateLiveChatFlags(flags({ pageSize: 5, profileSize: 5 }))
+    expect(error?.message).toBe("--page-size must be between 200 and 2000")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Params
+// ---------------------------------------------------------------------------
+
+describe("liveChatParams", () => {
+  test("always sends part, liveChatId, maxResults and profileImageSize", () => {
+    expect(liveChatParams("c1", flags(), "")).toEqual([
+      ["part", "snippet,authorDetails"],
+      ["liveChatId", "c1"],
+      ["maxResults", "500"],
+      ["profileImageSize", "88"]
+    ])
+  })
+
+  test("omits an empty pageToken and an empty fields", () => {
+    const params = liveChatParams("c1", flags(), "")
+    expect(params.map(([k]) => k)).not.toContain("pageToken")
+    expect(params.map(([k]) => k)).not.toContain("fields")
+  })
+
+  test("includes pageToken and fields when set", () => {
+    const params = liveChatParams("c1", flags({ fields: "items/id" }), "tok")
+    expect(params).toContainEqual(["pageToken", "tok"])
+    expect(params).toContainEqual(["fields", "items/id"])
+  })
+
+  test("the resource carries an embedded slash", () => {
+    // Documented in SPEC_CLI §5.3: liveChat/messages, unlike every other
+    // single-segment resource.
+    expect("liveChat/messages").toContain("/")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Chat-ID resolution
+// ---------------------------------------------------------------------------
+
+describe("resolveChatId", () => {
+  const api = (pages: ReadonlyArray) => {
+    const scripted = scriptedApi(pages)
+    return {
+      service: {
+        get: scripted.get,
+        list: () => Effect.succeed({ items: [], nextPageToken: "", requests: 0 }),
+        resolveChannel: () => Effect.succeed({ id: "", requests: 0 })
+      },
+      calls: scripted.calls
+    }
+  }
+
+  test("--chat-id costs zero requests and is used verbatim", async () => {
+    const { service, calls } = api([])
+    const result = await Effect.runPromise(resolveChatId(service, flags({ chatId: "given" })))
+    expect(result).toEqual({ chatId: "given", requests: 0 })
+    expect(calls).toEqual([])
+  })
+
+  test("--video costs one request and reads activeLiveChatId", async () => {
+    const { service, calls } = api([
+      { items: [{ liveStreamingDetails: { activeLiveChatId: "resolved" } }] }
+    ])
+    const result = await Effect.runPromise(
+      resolveChatId(service, flags({ video: "vid", chatId: "" }))
+    )
+    expect(result).toEqual({ chatId: "resolved", requests: 1 })
+    expect(calls).toEqual([
+      ["videos", [["part", "liveStreamingDetails"], ["id", "vid"]]]
+    ])
+  })
+
+  test("an empty item list is `video %q not found` (exit 4)", async () => {
+    const { service } = api([{ items: [] }])
+    const exit = await Effect.runPromiseExit(
+      resolveChatId(service, flags({ video: "vid", chatId: "" }))
+    )
+    expect(Exit.isFailure(exit)).toBe(true)
+    const error = failureOf(exit)
+    expect(error).toBeInstanceOf(NotFoundError)
+    expect(error.message).toBe('video "vid" not found')
+  })
+
+  test("a missing activeLiveChatId is `has no active public live chat`", async () => {
+    const { service } = api([{ items: [{ liveStreamingDetails: {} }] }])
+    const exit = await Effect.runPromiseExit(
+      resolveChatId(service, flags({ video: "vid", chatId: "" }))
+    )
+    expect(failureOf(exit).message).toBe('video "vid" has no active public live chat')
+  })
+
+  test("a whitespace-only activeLiveChatId is also `no active public live chat`", async () => {
+    const { service } = api([
+      { items: [{ liveStreamingDetails: { activeLiveChatId: "   " } }] }
+    ])
+    const exit = await Effect.runPromiseExit(
+      resolveChatId(service, flags({ video: "vid", chatId: "" }))
+    )
+    expect(failureOf(exit).message).toBe('video "vid" has no active public live chat')
+  })
+
+  test("the video ID is quoted with Go's %q, escapes included", async () => {
+    const { service } = api([{ items: [] }])
+    const exit = await Effect.runPromiseExit(
+      resolveChatId(service, flags({ video: 'a"b', chatId: "" }))
+    )
+    expect(failureOf(exit).message).toBe('video "a\\"b" not found')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Dedup
+// ---------------------------------------------------------------------------
+
+describe("dedupeBatch", () => {
+  test("suppresses an id already seen", () => {
+    const seen = new Set(["a"])
+    const batch = dedupeBatch([message("a"), message("b")], seen, 0, 0)
+    expect(batch.map((m) => m["id"])).toEqual(["b"])
+  })
+
+  test("an EMPTY id is ALWAYS emitted, however many times it appears", () => {
+    const seen = new Set()
+    const batch = dedupeBatch([message(""), message(""), message("")], seen, 0, 0)
+    expect(batch).toHaveLength(3)
+    // …and it is never recorded, so it cannot suppress a later one.
+    expect(seen.size).toBe(0)
+  })
+
+  test("a MISSING id behaves like an empty one", () => {
+    const seen = new Set()
+    const withoutId: JsonObject = { snippet: { displayMessage: "x" } }
+    const batch = dedupeBatch([withoutId, withoutId], seen, 0, 0)
+    expect(batch).toHaveLength(2)
+  })
+
+  test("a non-string id is treated as empty", () => {
+    const seen = new Set()
+    const numericId: JsonObject = { id: rawNumber("7") }
+    expect(dedupeBatch([numericId, numericId], seen, 0, 0)).toHaveLength(2)
+  })
+
+  test("the limit stops the batch AFTER the item that reached it", () => {
+    const seen = new Set()
+    const batch = dedupeBatch([message("a"), message("b"), message("c")], seen, 0, 2)
+    expect(batch.map((m) => m["id"])).toEqual(["a", "b"])
+  })
+
+  test("the limit accounts for items emitted on earlier pages", () => {
+    const seen = new Set()
+    const batch = dedupeBatch([message("a"), message("b")], seen, 1, 2)
+    expect(batch.map((m) => m["id"])).toEqual(["a"])
+  })
+
+  test("limit 0 means unlimited", () => {
+    const seen = new Set()
+    expect(dedupeBatch([message("a"), message("b")], seen, 99, 0)).toHaveLength(2)
+  })
+
+  test("dedup is across pages, via the shared seen-set", () => {
+    const seen = new Set()
+    dedupeBatch([message("a")], seen, 0, 0)
+    expect(dedupeBatch([message("a"), message("b")], seen, 1, 0)).toHaveLength(1)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Interval
+// ---------------------------------------------------------------------------
+
+describe("pollInterval", () => {
+  test("uses a positive pollingIntervalMillis", () => {
+    expect(pollInterval({ pollingIntervalMillis: rawNumber("2500") })).toBe(2500)
+  })
+
+  test("an absent value falls back to 1000ms", () => {
+    expect(pollInterval({})).toBe(1000)
+  })
+
+  test("zero falls back to 1000ms", () => {
+    expect(pollInterval({ pollingIntervalMillis: rawNumber("0") })).toBe(1000)
+  })
+
+  test("a negative value falls back to 1000ms", () => {
+    expect(pollInterval({ pollingIntervalMillis: rawNumber("-5") })).toBe(1000)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// liveChatEnded
+// ---------------------------------------------------------------------------
+
+describe("isLiveChatEnded", () => {
+  const withReasons = (reasons: ReadonlyArray): ApiError =>
+    new ApiError({ httpStatus: 403, code: 403, apiMessage: "gone", reasons })
+
+  test("matches the exact reason", () => {
+    expect(isLiveChatEnded(withReasons(["liveChatEnded"]))).toBe(true)
+  })
+
+  test("is case-SENSITIVE — this is control flow, not classification", () => {
+    expect(isLiveChatEnded(withReasons(["LIVECHATENDED"]))).toBe(false)
+    expect(isLiveChatEnded(withReasons(["livechatended"]))).toBe(false)
+    expect(isLiveChatEnded(withReasons(["live_chat_ended"]))).toBe(false)
+  })
+
+  test("matches when it is one of several reasons", () => {
+    expect(isLiveChatEnded(withReasons(["forbidden", "liveChatEnded"]))).toBe(true)
+  })
+
+  test("a non-ApiError is never a chat-ended signal", () => {
+    expect(isLiveChatEnded(new OperationalError({ message: "liveChatEnded" }))).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Format resolution
+// ---------------------------------------------------------------------------
+
+describe("formatFlagProvided", () => {
+  test("detects --format and --format=", () => {
+    expect(formatFlagProvided(["live-chat", "stream", "--format", "tsv"])).toBe(true)
+    expect(formatFlagProvided(["--format=json", "live-chat", "stream"])).toBe(true)
+  })
+
+  test("detects the -f alias", () => {
+    expect(formatFlagProvided(["-f", "tsv", "live-chat", "stream"])).toBe(true)
+    expect(formatFlagProvided(["-f=tsv"])).toBe(true)
+  })
+
+  test("is false when absent", () => {
+    expect(formatFlagProvided(["live-chat", "stream", "--chat-id", "c"])).toBe(false)
+  })
+
+  test("stops at a -- terminator", () => {
+    expect(formatFlagProvided(["live-chat", "stream", "--", "--format", "json"])).toBe(false)
+  })
+
+  test("is not confused by a similarly-named flag", () => {
+    expect(formatFlagProvided(["--formatter", "x"])).toBe(false)
+  })
+})
+
+describe("resolveStreamFormat", () => {
+  test("an omitted --format becomes jsonl even when the TTY resolved to table", () => {
+    expect(resolveStreamFormat("table", false)).toBe("jsonl")
+  })
+
+  test("an omitted --format becomes jsonl even when a pipe resolved to json", () => {
+    // The critical case: a piped `oytc live-chat stream` must NOT error.
+    expect(resolveStreamFormat("json", false)).toBe("jsonl")
+  })
+
+  test("an EXPLICIT --format json is the only path to the error", () => {
+    const result = resolveStreamFormat("json", true)
+    expect(result).toBeInstanceOf(UsageError)
+    expect((result as UsageError).message).toBe(
+      "--format json is not valid for an unbounded stream; use jsonl, tsv, or table"
+    )
+  })
+
+  test("explicit tsv, table and jsonl all pass through", () => {
+    expect(resolveStreamFormat("tsv", true)).toBe("tsv")
+    expect(resolveStreamFormat("table", true)).toBe("table")
+    expect(resolveStreamFormat("jsonl", true)).toBe("jsonl")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// The poll loop
+// ---------------------------------------------------------------------------
+
+describe("pollLiveChat", () => {
+  const runLoop = (
+    pages: ReadonlyArray,
+    overrides?: Parameters[2],
+    flagOverrides?: Partial
+  ) => {
+    const api = scriptedApi(pages)
+    const { calls, renderer } = recordingRenderer()
+    const exit = Effect.runPromiseExit(
+      pollLiveChat(streamDeps(api, renderer, overrides), flags(flagOverrides), "chat-1", 0)
+    )
+    return { exit, renders: calls, apiCalls: api.calls }
+  }
+
+  test("stops cleanly when nextPageToken is empty", async () => {
+    const { exit, renders } = runLoop([{ items: [message("a")], nextPageToken: "" }])
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    expect(renders).toHaveLength(1)
+  })
+
+  test("stops cleanly when offlineAt is non-empty, even with a token", async () => {
+    const { exit, apiCalls } = runLoop([
+      { items: [message("a")], nextPageToken: "t2", offlineAt: "2026-01-01T00:00:00Z" }
+    ])
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    expect(await exit).toBeDefined()
+    expect(apiCalls).toHaveLength(1)
+  })
+
+  test("stops cleanly on a liveChatEnded ApiError", async () => {
+    const ended = new ApiError({
+      httpStatus: 403,
+      code: 403,
+      apiMessage: "ended",
+      reasons: ["liveChatEnded"]
+    })
+    const { exit } = runLoop([ended])
+    expect(Exit.isSuccess(await exit)).toBe(true)
+  })
+
+  test("propagates any OTHER API error", async () => {
+    const boom = new ApiError({
+      httpStatus: 500,
+      code: 500,
+      apiMessage: "boom",
+      reasons: ["backendError"]
+    })
+    const { exit } = runLoop([boom])
+    const result = await exit
+    expect(Exit.isFailure(result)).toBe(true)
+    expect(failureOf(result)).toBe(boom)
+  })
+
+  test("stops immediately when `stopped` is already true — SIGINT before poll 1", async () => {
+    const { exit, apiCalls } = runLoop([{ items: [message("a")] }], { stopped: () => true })
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    expect(apiCalls).toEqual([])
+  })
+
+  test("stops between pages when `stopped` flips", async () => {
+    let polls = 0
+    const api = {
+      get: (_r: string, _p: Params) =>
+        Effect.sync(() => {
+          polls++
+          return {
+            items: [message(`m${polls}`)],
+            nextPageToken: "next",
+            pollingIntervalMillis: rawNumber("1")
+          } as DataApiResponse
+        })
+    }
+    const { renderer, calls } = recordingRenderer()
+    const exit = await Effect.runPromiseExit(
+      pollLiveChat(
+        streamDeps(api, renderer, { stopped: () => polls >= 2 }),
+        flags(),
+        "chat-1",
+        0
+      )
+    )
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(calls).toHaveLength(2)
+  })
+
+  test("the header prints ONLY for the first NON-EMPTY batch", async () => {
+    const { exit, renders } = runLoop([
+      { items: [], nextPageToken: "t1", pollingIntervalMillis: rawNumber("1") },
+      { items: [], nextPageToken: "t2", pollingIntervalMillis: rawNumber("1") },
+      { items: [message("a")], nextPageToken: "t3", pollingIntervalMillis: rawNumber("1") },
+      { items: [message("b")], nextPageToken: "" }
+    ])
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    // Two renders: the two empty pages produced none at all.
+    expect(renders).toHaveLength(2)
+    expect(renders[0]!.options.noHeader).toBe(false)
+    expect(renders[1]!.options.noHeader).toBe(true)
+  })
+
+  test("--no-header suppresses the header on the first batch too", async () => {
+    const { exit, renders } = runLoop(
+      [
+        { items: [message("a")], nextPageToken: "t", pollingIntervalMillis: rawNumber("1") },
+        { items: [message("b")], nextPageToken: "" }
+      ],
+      { noHeader: true }
+    )
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    expect(renders.map((r) => r.options.noHeader)).toEqual([true, true])
+  })
+
+  test("an empty batch renders NOTHING (no empty jsonl line)", async () => {
+    const { exit, renders } = runLoop([{ items: [], nextPageToken: "" }])
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    expect(renders).toEqual([])
+  })
+
+  test("duplicate ids across pages are emitted once", async () => {
+    const { exit, renders } = runLoop([
+      {
+        items: [message("a"), message("b")],
+        nextPageToken: "t",
+        pollingIntervalMillis: rawNumber("1")
+      },
+      { items: [message("b"), message("c")], nextPageToken: "" }
+    ])
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    const ids = renders.flatMap((r) => r.result.items.map((i) => i["id"]))
+    expect(ids).toEqual(["a", "b", "c"])
+  })
+
+  test("--limit stops the loop once reached", async () => {
+    const { exit, renders, apiCalls } = runLoop(
+      [
+        {
+          items: [message("a"), message("b")],
+          nextPageToken: "t",
+          pollingIntervalMillis: rawNumber("1")
+        },
+        { items: [message("c")], nextPageToken: "t2" }
+      ],
+      undefined,
+      { limit: 2 }
+    )
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    expect(apiCalls).toHaveLength(1)
+    expect(renders.flatMap((r) => r.result.items.map((i) => i["id"]))).toEqual(["a", "b"])
+  })
+
+  test("the page token is carried forward", async () => {
+    const { exit, apiCalls } = runLoop([
+      { items: [], nextPageToken: "TOKEN-2", pollingIntervalMillis: rawNumber("1") },
+      { items: [], nextPageToken: "" }
+    ])
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    expect(apiCalls[0]![1].map(([k]) => k)).not.toContain("pageToken")
+    expect(apiCalls[1]![1]).toContainEqual(["pageToken", "TOKEN-2"])
+  })
+
+  test("an explicit --page-token seeds the first request", async () => {
+    const { exit, apiCalls } = runLoop([{ items: [], nextPageToken: "" }], undefined, {
+      pageToken: "SEED"
+    })
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    expect(apiCalls[0]![1]).toContainEqual(["pageToken", "SEED"])
+  })
+
+  test("the request counter increments across pages and reaches the envelope", async () => {
+    const { exit, renders } = runLoop([
+      {
+        items: [message("a")],
+        nextPageToken: "t",
+        pollingIntervalMillis: rawNumber("1")
+      },
+      { items: [message("b")], nextPageToken: "" }
+    ])
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    expect(renders.map((r) => r.result.requests)).toEqual([1, 2])
+  })
+
+  test("the initial request count from --video resolution is carried in", async () => {
+    const api = scriptedApi([{ items: [message("a")], nextPageToken: "" }])
+    const { renderer, calls } = recordingRenderer()
+    await Effect.runPromise(pollLiveChat(streamDeps(api, renderer), flags(), "c", 1))
+    expect(calls[0]!.result.requests).toBe(2)
+  })
+
+  test("every batch envelope has an empty nextPageToken (streams have no resume)", async () => {
+    const { exit, renders } = runLoop([
+      { items: [message("a")], nextPageToken: "t", pollingIntervalMillis: rawNumber("1") },
+      { items: [message("b")], nextPageToken: "" }
+    ])
+    expect(Exit.isSuccess(await exit)).toBe(true)
+    expect(renders.every((r) => r.result.nextPageToken === "")).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Command wiring
+// ---------------------------------------------------------------------------
+
+interface RunOptions {
+  readonly format?: OutputFormat | undefined
+  readonly columns?: ReadonlyArray | undefined
+  readonly noHeader?: boolean | undefined
+  readonly quiet?: boolean | undefined
+  readonly pages?: ReadonlyArray | undefined
+  /** What `ProcessEnv.argv` reports; defaults to the argv under test. */
+  readonly argv?: ReadonlyArray | undefined
+}
+
+const runCommand = async (
+  argv: ReadonlyArray,
+  options: RunOptions = {}
+): Promise<{
+  readonly stdout: string
+  readonly stderr: string
+  readonly exit: Exit.Exit
+  readonly apiCalls: ReadonlyArray
+}> => {
+  const out: Array = []
+  const err: Array = []
+  const api = scriptedApi(options.pages ?? [{ items: [], nextPageToken: "" }])
+  const decode = (i: string | Uint8Array): string =>
+    typeof i === "string" ? i : new TextDecoder().decode(i)
+
+  const stdio = Stdio.layerTest({
+    stdout: () => Sink.forEach((i: string | Uint8Array) => Effect.sync(() => out.push(decode(i)))),
+    stderr: () => Sink.forEach((i: string | Uint8Array) => Effect.sync(() => err.push(decode(i))))
+  })
+
+  const appOptions: AppOptionsShape = {
+    format: options.format ?? "table",
+    columns: options.columns ?? [],
+    noHeader: options.noHeader ?? false,
+    quiet: options.quiet ?? false,
+    timeoutMillis: 20_000,
+    isOutputTTY: true
+  }
+
+  const layers = Layer.mergeAll(
+    Layer.succeed(AppOptions, appOptions),
+    Layer.succeed(YouTubeApi, {
+      get: api.get,
+      list: () => Effect.succeed({ items: [], nextPageToken: "", requests: 0 }),
+      resolveChannel: () => Effect.succeed({ id: "", requests: 0 })
+    }),
+    Layer.succeed(ProcessEnv, {
+      env: () => ({ _tag: "None" }) as never,
+      platform: "darwin",
+      arch: "arm64",
+      argv: options.argv ?? argv,
+      executablePath: Effect.succeed("/usr/local/bin/oytc"),
+      isOutputTTY: true,
+      homeDir: Effect.succeed("/home/test")
+    }),
+    Layer.succeed(
+      Renderer,
+      makeRendererWith((text) => Effect.sync(() => void out.push(text)))
+    )
+  )
+
+  // The shared global flags are declared on the root exactly as production's
+  // root.ts does, so `--format` parses here the way it does in the real CLI.
+  // `AppOptions` is supplied directly rather than resolved from them, which is
+  // what lets a test set the resolved format independently of argv — the very
+  // distinction `formatFlagProvided` exists to recover.
+  const root = Command.make("oytc").pipe(
+    Command.withSharedFlags(globalFlags),
+    Command.withSubcommands([liveChatCommand])
+  )
+  const exit = await Effect.runPromiseExit(
+    Command.runWith(root, { version: "test" })(argv).pipe(
+      Effect.provide(Layer.mergeAll(layers, stdio))
+    ) as Effect.Effect
+  )
+  return { stdout: out.join(""), stderr: err.join(""), exit, apiCalls: api.calls }
+}
+
+describe("live-chat list", () => {
+  test("renders one page and stops", async () => {
+    const { stdout, exit, apiCalls } = await runCommand(
+      ["live-chat", "list", "--chat-id", "c1"],
+      { format: "jsonl", pages: [{ items: [message("a")], nextPageToken: "t" }] }
+    )
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(apiCalls).toHaveLength(1)
+    expect(stdout).toContain('"id":"a"')
+  })
+
+  test("--all is rejected with Go's exact message", async () => {
+    const { exit, apiCalls } = await runCommand([
+      "live-chat",
+      "list",
+      "--chat-id",
+      "c1",
+      "--all"
+    ])
+    const error = failureOf(exit)
+    expect(error).toBeInstanceOf(UsageError)
+    expect(error.message).toBe(
+      "--all is not supported for live chat because its next token represents future " +
+        "polling; use 'live-chat stream'"
+    )
+    // …and nothing was requested.
+    expect(apiCalls).toEqual([])
+  })
+
+  test("the PreRunE checks fire BEFORE the --all check", async () => {
+    // Both are wrong; Go reports the flag-pair error.
+    const { exit } = await runCommand(["live-chat", "list", "--all"])
+    expect(failureOf(exit).message).toBe("provide exactly one of --video or --chat-id")
+  })
+
+  test("--limit truncates the single page client-side", async () => {
+    const { stdout } = await runCommand(
+      ["live-chat", "list", "--chat-id", "c1", "--limit=1"],
+      {
+        format: "jsonl",
+        pages: [{ items: [message("a"), message("b")], nextPageToken: "" }]
+      }
+    )
+    expect(stdout).toContain('"id":"a"')
+    expect(stdout).not.toContain('"id":"b"')
+  })
+
+  test("the table summary lands on stderr and counts requests", async () => {
+    const { stderr } = await runCommand(["live-chat", "list", "--chat-id", "c1"], {
+      format: "table",
+      pages: [{ items: [message("a")], nextPageToken: "" }]
+    })
+    expect(stderr).toBe("1 item(s), 1 request(s)\n")
+  })
+
+  test("--quiet suppresses the summary", async () => {
+    const { stderr } = await runCommand(["live-chat", "list", "--chat-id", "c1"], {
+      format: "table",
+      quiet: true,
+      pages: [{ items: [message("a")], nextPageToken: "" }]
+    })
+    expect(stderr).toBe("")
+  })
+
+  test("a resume token appears in the summary", async () => {
+    const { stderr } = await runCommand(["live-chat", "list", "--chat-id", "c1"], {
+      format: "table",
+      pages: [{ items: [message("a")], nextPageToken: "NEXT" }]
+    })
+    expect(stderr).toBe("1 item(s), 1 request(s); more available (next token: NEXT)\n")
+  })
+
+  test("--video resolution costs a request, reflected in the summary", async () => {
+    const { stderr } = await runCommand(["live-chat", "list", "--video", "v1"], {
+      format: "table",
+      pages: [
+        { items: [{ liveStreamingDetails: { activeLiveChatId: "resolved" } }] },
+        { items: [message("a")], nextPageToken: "" }
+      ]
+    })
+    expect(stderr).toBe("1 item(s), 2 request(s)\n")
+  })
+})
+
+describe("live-chat stream", () => {
+  test("silently forces jsonl on a TTY when --format is absent", async () => {
+    const { stdout, exit } = await runCommand(["live-chat", "stream", "--chat-id", "c1"], {
+      // AppOptions resolved to table because isOutputTTY is true…
+      format: "table",
+      pages: [{ items: [message("a")], nextPageToken: "" }]
+    })
+    expect(Exit.isSuccess(exit)).toBe(true)
+    // …but the output is JSONL, not a table.
+    expect(stdout).toStartWith('{"authorDetails"')
+    expect(stdout).not.toContain("SNIPPET.PUBLISHEDAT")
+  })
+
+  test("an explicit --format json is rejected before any request", async () => {
+    const { exit, apiCalls } = await runCommand(
+      ["live-chat", "stream", "--chat-id", "c1", "--format", "json"],
+      { format: "json", argv: ["live-chat", "stream", "--chat-id", "c1", "--format", "json"] }
+    )
+    const error = failureOf(exit)
+    expect(error).toBeInstanceOf(UsageError)
+    expect(error.message).toBe(
+      "--format json is not valid for an unbounded stream; use jsonl, tsv, or table"
+    )
+    expect(apiCalls).toEqual([])
+  })
+
+  test("a PIPED stream with no --format does NOT error, it emits jsonl", async () => {
+    // The regression this guards: AppOptions.format is "json" here because
+    // stdout is a pipe, but the flag was never passed, so Go streamed jsonl.
+    const { stdout, exit } = await runCommand(["live-chat", "stream", "--chat-id", "c1"], {
+      format: "json",
+      argv: ["live-chat", "stream", "--chat-id", "c1"],
+      pages: [{ items: [message("a")], nextPageToken: "" }]
+    })
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(stdout).toContain('"id":"a"')
+    // A json ENVELOPE would have "items"; jsonl has bare objects.
+    expect(stdout).not.toContain('"items"')
+  })
+
+  test("an explicit --format tsv is honoured", async () => {
+    const { stdout, exit } = await runCommand(
+      ["live-chat", "stream", "--chat-id", "c1", "--format", "tsv"],
+      {
+        format: "tsv",
+        argv: ["live-chat", "stream", "--chat-id", "c1", "--format", "tsv"],
+        pages: [{ items: [message("a")], nextPageToken: "" }]
+      }
+    )
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(stdout).toStartWith("SNIPPET.PUBLISHEDAT\t")
+  })
+
+  test("flag validation runs before the format check", async () => {
+    const { exit } = await runCommand(["live-chat", "stream", "--format", "json"], {
+      format: "json",
+      argv: ["live-chat", "stream", "--format", "json"]
+    })
+    expect(failureOf(exit).message).toBe("provide exactly one of --video or --chat-id")
+  })
+
+  test("--columns overrides the default column set", async () => {
+    const { stdout } = await runCommand(
+      ["live-chat", "stream", "--chat-id", "c1", "--format", "tsv"],
+      {
+        format: "tsv",
+        columns: ["id"],
+        argv: ["live-chat", "stream", "--chat-id", "c1", "--format", "tsv"],
+        pages: [{ items: [message("a")], nextPageToken: "" }]
+      }
+    )
+    expect(stdout).toBe("ID\na\n")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+describe("command registration", () => {
+  test("the group has Go's name and description", () => {
+    expect(liveChatCommand.name).toBe("live-chat")
+    expect(liveChatCommand.description).toBe("Read public live chat using REST polling")
+  })
+
+  test("both subcommands are registered", () => {
+    expect(liveChatListCommand.name).toBe("list")
+    expect(liveChatStreamCommand.name).toBe("stream")
+    const names = liveChatCommand.subcommands.flatMap((g) => g.commands.map((c) => c.name))
+    expect(names).toEqual(["list", "stream"])
+  })
+
+  test("a bare `live-chat` has no handler, so it prints help and exits 0", async () => {
+    const { exit } = await runCommand(["live-chat"])
+    // The framework surfaces "help requested" rather than running anything.
+    expect(Exit.isFailure(exit)).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+
+const failureOf = (exit: Exit.Exit): OytcError => {
+  if (Exit.isSuccess(exit)) throw new Error("expected a failure")
+  const found = exit.cause.reasons.find((r) => r._tag === "Fail")
+  if (found === undefined) throw new Error(`no Fail reason: ${String(exit.cause)}`)
+  return (found as { readonly error: OytcError }).error
+}
diff --git a/src/cli/livechat.ts b/src/cli/livechat.ts
index ca14f9a..9f74fc9 100644
--- a/src/cli/livechat.ts
+++ b/src/cli/livechat.ts
@@ -1,2 +1,543 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `live-chat {list,stream}` — the port of `internal/cli/live_chat.go`.
+ *
+ * `list` fetches exactly one page. `stream` is a hand-rolled polling loop; it
+ * is the only command in the CLI that renders more than once, and almost every
+ * detail of it is observable:
+ *
+ *   - **Dedup by `id`, but an EMPTY id is always emitted.** An item whose `id`
+ *     is missing or blank is never recorded in the seen-set and never
+ *     suppressed, so a partial-response selector that strips ids degrades to
+ *     "emit everything" rather than to "emit the first item and nothing else".
+ *   - **The header prints for the first NON-EMPTY batch only.** `firstPage`
+ *     flips inside the `if items.length > 0` branch, so a run that polls three
+ *     empty pages before its first message still gets its header.
+ *   - **1000 ms is the fallback interval.** `pollingIntervalMillis` is used
+ *     when positive; zero, negative and absent all mean one second.
+ *   - **Four clean-exit conditions, all exit code 0:** a non-empty `offlineAt`,
+ *     an empty `nextPageToken`, an API error carrying the reason
+ *     `liveChatEnded` (exact, case-SENSITIVE — it is a control-flow signal, not
+ *     a classification heuristic), and SIGINT. DEVIATIONS.md lists the SIGINT
+ *     case as deliberate parity even though it contradicts "130 = interrupted".
+ *   - **`--format` silently becomes `jsonl` when the user did not pass it**,
+ *     even on a TTY. Only an EXPLICIT `--format json` reaches the error.
+ *
+ * ## Why the explicit-flag test reads argv
+ *
+ * Go branched on `a.format == ""`, i.e. on whether the flag was supplied, not
+ * on its resolved value. `AppOptions.format` has already collapsed that
+ * distinction: on a TTY an omitted flag and an explicit `--format table` both
+ * arrive as `"table"`, and when piped an omitted flag and an explicit
+ * `--format json` both arrive as `"json"` — yet Go streams JSONL for the first
+ * and errors for the second. The distinction therefore has to come from
+ * somewhere else, and `ProcessEnv.argv` is the seam that has it. Redeclaring
+ * `--format` on the leaf does NOT work: the root's shared flag consumes the
+ * value and the leaf's copy is always `None` (verified against the framework).
+ *
+ * ## Why the loop installs its own SIGINT handler
+ *
+ * `runMain` interrupts the main fiber on SIGINT and its teardown maps an
+ * interrupt-only cause to exit **130**. Catching the interrupt inside the
+ * handler does not help — the fiber is already unwinding and the teardown has
+ * already decided. Taking the signal over for the duration of the loop, and
+ * restoring the previous listeners afterwards, is what produces the exit 0 Go
+ * produced. Verified end-to-end under Bun.
+ */
+
+import { Effect, Option, Stdio, Stream } from "effect"
+import { Command, Flag } from "../effect.ts"
+import {
+  ApiError,
+  NotFoundError,
+  OperationalError,
+  UsageError,
+  type OytcError
+} from "../domain/errors.ts"
+import type { ListResult } from "../domain/listResult.ts"
+import type { JsonObject } from "../json/value.ts"
+import { goQuote } from "../impl/resolveChannel.ts"
+import { pollingIntervalMillis, videoActiveLiveChatId } from "../schema/accessors.ts"
+import type { DataApiResponse } from "../schema/dataapi.ts"
+import { liveChatColumns } from "../output/columns.ts"
+import {
+  AppOptions,
+  ProcessEnv,
+  Renderer,
+  YouTubeApi,
+  type AppOptionsShape,
+  type OutputFormat,
+  type Params,
+  type RendererShape,
+  type YouTubeApiShape
+} from "../services/index.ts"
+
+// ---------------------------------------------------------------------------
+// Flags
+// ---------------------------------------------------------------------------
+
+/**
+ * `addLiveChatFlags`. A DISTINCT set from `addListFlags`/`addAPIFlags`: note
+ * the 500 page size with a 200-2000 range, and the non-empty `--parts` default.
+ */
+const liveChatFlags = {
+  video: Flag.string("video").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("live video ID (resolved to activeLiveChatId)")
+  ),
+  chatId: Flag.string("chat-id").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("live chat ID")
+  ),
+  pageSize: Flag.integer("page-size").pipe(
+    Flag.withDefault(500),
+    Flag.withDescription("messages per request (200-2000)")
+  ),
+  pageToken: Flag.string("page-token").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("resume at this live chat page token")
+  ),
+  limit: Flag.integer("limit").pipe(
+    Flag.withDefault(0),
+    Flag.withDescription("stop after this many emitted messages (0 means unlimited)")
+  ),
+  profileSize: Flag.integer("profile-image-size").pipe(
+    Flag.withDefault(88),
+    Flag.withDescription("author image size in pixels (16-720)")
+  ),
+  parts: Flag.string("parts").pipe(
+    Flag.withDefault("snippet,authorDetails"),
+    Flag.withDescription("comma-separated API resource parts")
+  ),
+  fields: Flag.string("fields").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("Google partial-response fields selector")
+  )
+} as const
+
+export interface LiveChatFlagValues {
+  readonly video: string
+  readonly chatId: string
+  readonly pageSize: number
+  readonly pageToken: string
+  readonly limit: number
+  readonly profileSize: number
+  readonly parts: string
+  readonly fields: string
+}
+
+/**
+ * The `PreRunE` block both subcommands share, in Go's exact order. Runs before
+ * the `RunE` semantic checks and before anything touches the network.
+ */
+export const validateLiveChatFlags = (flags: LiveChatFlagValues): UsageError | undefined => {
+  if ((flags.video === "") === (flags.chatId === "")) {
+    return new UsageError({ message: "provide exactly one of --video or --chat-id" })
+  }
+  if (flags.pageSize < 200 || flags.pageSize > 2000) {
+    return new UsageError({ message: "--page-size must be between 200 and 2000" })
+  }
+  if (flags.profileSize < 16 || flags.profileSize > 720) {
+    return new UsageError({ message: "--profile-image-size must be between 16 and 720" })
+  }
+  if (flags.limit < 0) {
+    return new UsageError({ message: "--limit cannot be negative" })
+  }
+  return undefined
+}
+
+/** `liveChatParams` — `pageToken` and `fields` only when non-empty. */
+export const liveChatParams = (
+  chatId: string,
+  flags: LiveChatFlagValues,
+  pageToken: string
+): Params => {
+  const params: Array = [
+    ["part", flags.parts],
+    ["liveChatId", chatId],
+    ["maxResults", String(flags.pageSize)],
+    ["profileImageSize", String(flags.profileSize)]
+  ]
+  if (pageToken !== "") params.push(["pageToken", pageToken])
+  if (flags.fields !== "") params.push(["fields", flags.fields])
+  return params
+}
+
+// ---------------------------------------------------------------------------
+// Chat-ID resolution
+// ---------------------------------------------------------------------------
+
+export interface ResolvedChat {
+  readonly chatId: string
+  /** Requests already spent resolving: 0 for `--chat-id`, 1 for `--video`. */
+  readonly requests: number
+}
+
+/**
+ * `liveChatClientAndID`. Both failure messages are matched by the exit-code
+ * classifier's substring rules (`not found`, `no active public live chat`), so
+ * both are `NotFoundError` / exit 4.
+ */
+export const resolveChatId = (
+  api: YouTubeApiShape,
+  flags: LiveChatFlagValues
+): Effect.Effect =>
+  Effect.gen(function* () {
+    if (flags.chatId !== "") return { chatId: flags.chatId, requests: 0 }
+
+    const response = yield* api.get("videos", [
+      ["part", "liveStreamingDetails"],
+      ["id", flags.video]
+    ])
+    const items = (response.items ?? []) as ReadonlyArray
+    if (items.length === 0) {
+      return yield* Effect.fail(
+        new NotFoundError({ message: `video ${goQuote(flags.video)} not found` })
+      )
+    }
+    // The accessor already rejects a missing key, a non-string, and an empty
+    // string; Go additionally trimmed, so a whitespace-only id is "no chat".
+    const resolved = videoActiveLiveChatId(items[0]!)
+    if (Option.isNone(resolved) || resolved.value.trim() === "") {
+      return yield* Effect.fail(
+        new NotFoundError({
+          message: `video ${goQuote(flags.video)} has no active public live chat`
+        })
+      )
+    }
+    return { chatId: resolved.value, requests: 1 }
+  })
+
+// ---------------------------------------------------------------------------
+// live-chat list
+// ---------------------------------------------------------------------------
+
+const writeErr = (text: string): Effect.Effect =>
+  Effect.gen(function* () {
+    const stdio = yield* Stdio.Stdio
+    yield* Stream.run(Stream.make(text), stdio.stderr()).pipe(
+      Effect.catch((cause) =>
+        Effect.fail(new OperationalError({ message: "could not write output", cause }))
+      )
+    )
+  })
+
+/**
+ * `renderResult` — render, then the stderr summary for `--format table` only,
+ * and only without `--quiet`. P8a owns the shared copy in `render.ts`; it is
+ * still a stub, so an identical local one lives here.
+ */
+const renderResult = (
+  result: ListResult,
+  defaultColumns: ReadonlyArray,
+  options: AppOptionsShape
+) =>
+  Effect.gen(function* () {
+    const renderer = yield* Renderer
+    yield* renderer.render(result, {
+      format: options.format,
+      columns: options.columns.length > 0 ? options.columns : defaultColumns,
+      noHeader: options.noHeader
+    })
+    if (options.quiet || options.format !== "table") return
+    const more =
+      result.nextPageToken === ""
+        ? ""
+        : `; more available (next token: ${result.nextPageToken})`
+    yield* writeErr(`${result.items.length} item(s), ${result.requests} request(s)${more}\n`)
+  })
+
+export const liveChatListCommand = Command.make(
+  "list",
+  {
+    ...liveChatFlags,
+    all: Flag.boolean("all").pipe(
+      Flag.withDescription("not supported for finite live chat; use stream")
+    )
+  },
+  (config) =>
+    Effect.gen(function* () {
+      // PreRunE first…
+      const invalid = validateLiveChatFlags(config)
+      if (invalid !== undefined) return yield* Effect.fail(invalid)
+      // …then RunE's own check. `--all` exists ONLY to produce this message.
+      if (config.all) {
+        return yield* Effect.fail(
+          new UsageError({
+            message:
+              "--all is not supported for live chat because its next token represents " +
+              "future polling; use 'live-chat stream'"
+          })
+        )
+      }
+
+      const api = yield* YouTubeApi
+      const { chatId, requests } = yield* resolveChatId(api, config)
+      const response = yield* api.get(
+        "liveChat/messages",
+        liveChatParams(chatId, config, config.pageToken)
+      )
+
+      let items = (response.items ?? []) as ReadonlyArray
+      if (config.limit > 0 && items.length > config.limit) items = items.slice(0, config.limit)
+
+      const options = yield* AppOptions
+      yield* renderResult(
+        {
+          items,
+          nextPageToken: response.nextPageToken ?? "",
+          requests: requests + 1
+        },
+        liveChatColumns,
+        options
+      )
+    })
+).pipe(
+  Command.withDescription(
+    "Fetch one finite page of public live chat messages. Use stream for continuous, " +
+      "polling-aware output."
+  )
+)
+
+// ---------------------------------------------------------------------------
+// live-chat stream
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether `--format` (or its `-f` alias) appears in argv.
+ *
+ * `live-chat stream` takes no positional arguments, so any `--format` token is
+ * unambiguously the flag; there is no value position it could be occupying.
+ * Both the `--format value` and `--format=value` spellings are recognised, and
+ * a `--` terminator ends the scan the way a POSIX parser would.
+ */
+export const formatFlagProvided = (argv: ReadonlyArray): boolean => {
+  for (const argument of argv) {
+    if (argument === "--") return false
+    if (argument === "--format" || argument.startsWith("--format=")) return true
+    if (argument === "-f" || argument.startsWith("-f=")) return true
+  }
+  return false
+}
+
+/**
+ * `stream`'s format resolution, which is unlike every other command's.
+ *
+ * Returns the format to render with, or a `UsageError` for the one rejected
+ * case. Note that an omitted flag NEVER errors: it becomes jsonl even on a
+ * TTY, so `oytc live-chat stream` alone emits JSONL rather than a table.
+ */
+export const resolveStreamFormat = (
+  resolved: OutputFormat,
+  provided: boolean
+): OutputFormat | UsageError => {
+  if (!provided) return "jsonl"
+  if (resolved === "json") {
+    return new UsageError({
+      message: "--format json is not valid for an unbounded stream; use jsonl, tsv, or table"
+    })
+  }
+  return resolved
+}
+
+/** `apiErrorHasReason(err, "liveChatEnded")` — exact, case-SENSITIVE. */
+export const isLiveChatEnded = (error: OytcError): boolean =>
+  error instanceof ApiError && error.reasons.includes("liveChatEnded")
+
+/** `pollingIntervalMillis` when positive, otherwise one second. */
+export const pollInterval = (response: DataApiResponse): number => {
+  const millis = pollingIntervalMillis(response)
+  if (Option.isNone(millis)) return 1000
+  return millis.value > 0 ? millis.value : 1000
+}
+
+/**
+ * One batch's worth of dedup, in Go's exact shape.
+ *
+ * `seen` is mutated. The limit test runs AFTER the item is appended, matching
+ * `if flags.limit > 0 && emitted+len(items) >= flags.limit { break }`.
+ */
+export const dedupeBatch = (
+  items: ReadonlyArray,
+  seen: Set,
+  emitted: number,
+  limit: number
+): ReadonlyArray => {
+  const batch: Array = []
+  for (const item of items) {
+    const id = typeof item["id"] === "string" ? item["id"] : ""
+    if (id !== "") {
+      if (seen.has(id)) continue
+      seen.add(id)
+    }
+    batch.push(item)
+    if (limit > 0 && emitted + batch.length >= limit) break
+  }
+  return batch
+}
+
+/**
+ * The interruptible wait.
+ *
+ * Sliced rather than a single `Effect.sleep` because the loop owns SIGINT for
+ * its duration: `runMain`'s fiber interrupt is not available to cut a sleep
+ * short, so a 5-second polling interval would otherwise keep the process alive
+ * for up to five seconds after Ctrl-C. 50 ms of granularity is invisible to a
+ * user and bounded regardless of what the server asks for.
+ */
+const waitFor = (millis: number, stopped: () => boolean): Effect.Effect =>
+  Effect.gen(function* () {
+    let remaining = millis
+    while (remaining > 0) {
+      if (stopped()) return
+      const slice = Math.min(remaining, 50)
+      yield* Effect.sleep(slice)
+      remaining -= slice
+    }
+  })
+
+export interface StreamDeps {
+  readonly api: YouTubeApiShape
+  readonly renderer: RendererShape
+  readonly format: OutputFormat
+  readonly columns: ReadonlyArray
+  readonly noHeader: boolean
+  /** Polled between and during waits; `true` ends the loop cleanly. */
+  readonly stopped: () => boolean
+}
+
+/**
+ * The poll loop itself, with every seam injected so tests drive it without a
+ * process, a socket or a signal.
+ */
+export const pollLiveChat = (
+  deps: StreamDeps,
+  flags: LiveChatFlagValues,
+  chatId: string,
+  initialRequests: number
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const seen = new Set()
+    let emitted = 0
+    let firstPage = true
+    let requests = initialRequests
+    let pageToken = flags.pageToken
+
+    for (;;) {
+      if (deps.stopped()) return
+
+      const attempt = yield* Effect.result(
+        deps.api.get("liveChat/messages", liveChatParams(chatId, flags, pageToken))
+      )
+      if (attempt._tag === "Failure") {
+        // A chat that has ended is a normal termination, not an error.
+        if (isLiveChatEnded(attempt.failure)) return
+        return yield* Effect.fail(attempt.failure)
+      }
+      const response = attempt.success
+      requests++
+
+      const batch = dedupeBatch(
+        (response.items ?? []) as ReadonlyArray,
+        seen,
+        emitted,
+        flags.limit
+      )
+
+      if (batch.length > 0) {
+        yield* deps.renderer.render(
+          { items: batch, nextPageToken: "", requests },
+          {
+            format: deps.format,
+            columns: deps.columns,
+            // The header belongs to the first batch that actually has rows.
+            noHeader: deps.noHeader || !firstPage
+          }
+        )
+        emitted += batch.length
+        firstPage = false
+      }
+
+      if (flags.limit > 0 && emitted >= flags.limit) return
+      const offlineAt = response.offlineAt ?? ""
+      const nextPageToken = response.nextPageToken ?? ""
+      if (offlineAt !== "" || nextPageToken === "") return
+
+      pageToken = nextPageToken
+      yield* waitFor(pollInterval(response), deps.stopped)
+    }
+  })
+
+/**
+ * Own SIGINT for the duration of `effect`, restoring the previous listeners
+ * however it ends.
+ *
+ * The `yieldNow` matters: `runMain` installs its own handler around the fiber
+ * it forks, and on the very first synchronous run of the program that has not
+ * happened yet — removing listeners before it would leave `runMain` free to
+ * add its own afterwards and interrupt anyway. One scheduler tick is enough.
+ */
+const withOwnSigint = (
+  use: (stopped: () => boolean) => Effect.Effect
+): Effect.Effect =>
+  Effect.gen(function* () {
+    yield* Effect.yieldNow
+    const previous = process.listeners("SIGINT") as ReadonlyArray
+    let stopped = false
+    const onSignal = (): void => {
+      stopped = true
+    }
+    process.removeAllListeners("SIGINT")
+    process.on("SIGINT", onSignal)
+    return yield* use(() => stopped).pipe(
+      Effect.ensuring(
+        Effect.sync(() => {
+          process.removeListener("SIGINT", onSignal)
+          for (const listener of previous) process.on("SIGINT", listener)
+        })
+      )
+    )
+  })
+
+export const liveChatStreamCommand = Command.make("stream", liveChatFlags, (config) =>
+  Effect.gen(function* () {
+    const invalid = validateLiveChatFlags(config)
+    if (invalid !== undefined) return yield* Effect.fail(invalid)
+
+    const options = yield* AppOptions
+    const env = yield* ProcessEnv
+    const format = resolveStreamFormat(options.format, formatFlagProvided(env.argv))
+    if (format instanceof UsageError) return yield* Effect.fail(format)
+
+    const api = yield* YouTubeApi
+    const { chatId, requests } = yield* resolveChatId(api, config)
+    const renderer = yield* Renderer
+
+    yield* withOwnSigint((stopped) =>
+      pollLiveChat(
+        {
+          api,
+          renderer,
+          format,
+          columns: options.columns.length > 0 ? options.columns : liveChatColumns,
+          noHeader: options.noHeader,
+          stopped
+        },
+        config,
+        chatId,
+        requests
+      )
+    )
+  })
+).pipe(
+  Command.withDescription(
+    "Continuously polls liveChatMessages.list, respects pollingIntervalMillis, carries page " +
+      "tokens, and deduplicates IDs. This first draft is a REST polling fallback, not the " +
+      "official gRPC streamList method. JSONL is the default stream format."
+  )
+)
+
+/** The group; no handler, so a bare `oytc live-chat` prints help and exits 0. */
+export const liveChatCommand = Command.make("live-chat").pipe(
+  Command.withDescription("Read public live chat using REST polling"),
+  Command.withSubcommands([liveChatListCommand, liveChatStreamCommand])
+)
diff --git a/src/cli/p8aHarness.testutil.ts b/src/cli/p8aHarness.testutil.ts
new file mode 100644
index 0000000..06bd49e
--- /dev/null
+++ b/src/cli/p8aHarness.testutil.ts
@@ -0,0 +1,397 @@
+/**
+ * Test harness for the P8a command tests (`search`, `channel`, `video`).
+ *
+ * Not a `.test.ts` — bun would try to run it as a suite. Imported by
+ * `search.test.ts`, `channel.test.ts` and `video.test.ts`.
+ *
+ * `runCli` drives a command through the REAL `Command.runWith` with explicit
+ * argv, the real `RendererLive` over a capturing `Stdio`, and scripted
+ * `YouTubeApi` / `HttpCore` services that record every request. Flag parsing,
+ * defaulting, validation order, param assembly, pagination options and
+ * rendering are therefore all under test end-to-end; only the network is faked.
+ *
+ * A local root mirrors `src/cli/root.ts` (which P8a must not edit and which does
+ * not yet register these subcommands): same shared global flags, same
+ * `Command.provide` order, same `resolveGlobals`. `isOutputTTY` defaults to true
+ * so the default format is `table` and the stderr summary line is exercised.
+ *
+ * P8b has its own `harness.testutil.ts`; this one is separate because P8a needs
+ * `HttpCore` (for `video trainability`) and a real `list` implementation that
+ * runs the client-side filter (for `search`), neither of which that harness
+ * models.
+ */
+
+import { Cause, Effect, Exit, Layer, Result, Runtime, Sink, Stdio } from "effect"
+import { Command } from "../effect.ts"
+import { exitCodeFor, UsageError } from "../domain/errors.ts"
+import type {
+  ApiError,
+  MissingKeyError,
+  MissingOAuthError,
+  OAuthError,
+  OperationalError,
+  OytcError
+} from "../domain/errors.ts"
+import type { ListResult, PageOptions } from "../domain/listResult.ts"
+import { parseJson } from "../json/parse.ts"
+import type { JsonObject, JsonValue } from "../json/value.ts"
+import { RendererLive } from "../impl/renderer.ts"
+import { AppOptions, HttpCore, YouTubeApi } from "../services/index.ts"
+import type {
+  HttpCoreRequest,
+  HttpCoreShape,
+  Params,
+  ResolvedChannel,
+  YouTubeApiShape
+} from "../services/index.ts"
+import type { DataApiResponse } from "../schema/dataapi.ts"
+import { globalFlags } from "./flags.ts"
+import { resolveGlobals } from "./globals.ts"
+
+/** One recorded call into a faked service. */
+export interface RecordedCall {
+  readonly kind: "get" | "list" | "resolveChannel" | "getJson"
+  readonly resource: string
+  /** Params as a plain object; every command sends each key at most once. */
+  readonly params: Record
+  readonly page?: PageOptions | undefined
+  /** `getJson` only. */
+  readonly authenticate?: boolean | undefined
+}
+
+/** One faked page of a `list` call, before the client-side filter runs. */
+export interface Page {
+  readonly items: ReadonlyArray
+  readonly nextPageToken?: string | undefined
+}
+
+export interface ApiScript {
+  /** Consumed in order by `get`; the last entry repeats. */
+  readonly get?: ReadonlyArray | undefined
+  /**
+   * Pages served by `list`. The harness runs the REAL pagination algorithm over
+   * them — filter first, then limit, then the `--all` termination rules — so
+   * `search`'s filter/limit interaction is genuinely exercised.
+   */
+  readonly pages?: ReadonlyArray | undefined
+  /** Consumed in order by `getJson`; the last entry repeats. */
+  readonly json?: ReadonlyArray | undefined
+  /** Resolved channel ids, in call order; the last entry repeats. */
+  readonly channels?: ReadonlyArray | undefined
+  /** When set, every call fails with this error instead. */
+  readonly fail?: OytcError | undefined
+  /**
+   * `HttpCore.getJson`'s error channel is narrower than `OytcError` (it cannot
+   * produce a `UsageError` or `NotFoundError`), so a `fail` aimed at the
+   * transport goes here instead.
+   */
+  readonly failJson?: HttpCoreError | undefined
+}
+
+/** The exact error union `HttpCore.getJson` may fail with. */
+type HttpCoreError =
+  | ApiError
+  | MissingKeyError
+  | MissingOAuthError
+  | OAuthError
+  | OperationalError
+
+export interface RunResult {
+  readonly stdout: string
+  readonly stderr: string
+  /** 0 on success, else the error's `exitCodeFor`. */
+  readonly exitCode: number
+  /** `undefined` on success. */
+  readonly error: OytcError | undefined
+  /** The error message exactly as `main.ts` would print it after `oytc: `. */
+  readonly message: string | undefined
+  readonly calls: ReadonlyArray
+}
+
+/** Parse a JSON literal into items, for building fake responses concisely. */
+export const items = (text: string): ReadonlyArray => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as ReadonlyArray
+}
+
+/** Parse a JSON literal into one object. */
+export const object = (text: string): JsonObject => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as JsonObject
+}
+
+/** A `DataApiResponse` from a JSON array literal. */
+export const responseOf = (text: string): DataApiResponse => ({
+  items: items(text) as DataApiResponse["items"]
+})
+
+/** One page from a JSON array literal. */
+export const pageOf = (text: string, nextPageToken = ""): Page => ({
+  items: items(text),
+  nextPageToken
+})
+
+const paramsToObject = (params: Params): Record => {
+  const out: Record = {}
+  for (const [key, value] of params) out[key] = value
+  return out
+}
+
+/**
+ * The REAL `List` algorithm from `src/impl/youtubeApi.ts`, over scripted pages.
+ *
+ * Reproduced rather than imported because the impl is welded to `HttpCore`;
+ * the loop below is a line-for-line transcription, INCLUDING deviation D2 (a
+ * page from which items were discarded reports no resume token).
+ */
+const runList = (
+  pages: ReadonlyArray,
+  options: PageOptions,
+  onRequest: () => void
+): ListResult => {
+  const kept: Array = []
+  let requests = 0
+  let nextPageToken = ""
+  let index = 0
+
+  for (;;) {
+    const page = pages[Math.min(index, Math.max(pages.length - 1, 0))] ?? { items: [] }
+    onRequest()
+    requests++
+    index++
+
+    let pageItems = [...page.items]
+    // The filter runs BEFORE the limit, so rejected items do not count toward
+    // it and a page can contribute zero items while still consuming a request.
+    if (options.filter !== undefined) pageItems = pageItems.filter(options.filter)
+
+    let truncated = false
+    if (options.limit > 0 && kept.length + pageItems.length > options.limit) {
+      pageItems = pageItems.slice(0, options.limit - kept.length)
+      truncated = true
+    }
+    kept.push(...pageItems)
+    nextPageToken = truncated ? "" : (page.nextPageToken ?? "")
+
+    if (
+      !options.all ||
+      nextPageToken === "" ||
+      (options.limit > 0 && kept.length >= options.limit)
+    ) {
+      break
+    }
+  }
+
+  return { items: kept, nextPageToken, requests }
+}
+
+export interface RunOptions {
+  /** Defaults to true, so the default format is `table`. */
+  readonly isOutputTTY?: boolean | undefined
+  readonly script?: ApiScript | undefined
+}
+
+/**
+ * Run one command with explicit argv.
+ *
+ * The command under test is mounted under a root that reproduces root.ts's
+ * mandatory composition order: `withSharedFlags` -> `withSubcommands` ->
+ * `provide`.
+ */
+export const runCli = (
+  // The concrete Command type is a five-parameter generic whose Input differs
+  // per command; the harness only ever passes it to `withSubcommands`.
+  command: never,
+  argv: ReadonlyArray,
+  options: RunOptions = {}
+): Promise => {
+  const isOutputTTY = options.isOutputTTY ?? true
+  const script = options.script ?? {}
+  const calls: Array = []
+  const stdout: Array = []
+  const stderr: Array = []
+
+  let getIndex = 0
+  let jsonIndex = 0
+  let channelIndex = 0
+
+  const pick = (source: ReadonlyArray | undefined, index: number, fallback: A): A => {
+    if (source === undefined || source.length === 0) return fallback
+    return source[Math.min(index, source.length - 1)]!
+  }
+
+  const api: YouTubeApiShape = {
+    get: (resource, params) =>
+      Effect.suspend(() => {
+        calls.push({ kind: "get", resource, params: paramsToObject(params) })
+        if (script.fail !== undefined) return Effect.fail(script.fail)
+        const response = pick(script.get, getIndex, { items: [] } as DataApiResponse)
+        getIndex++
+        return Effect.succeed(response)
+      }),
+    list: (resource, params, page) =>
+      Effect.suspend(() => {
+        if (script.fail !== undefined) {
+          calls.push({ kind: "list", resource, params: paramsToObject(params), page })
+          return Effect.fail(script.fail)
+        }
+        const pages = script.pages ?? [{ items: [] }]
+        const result = runList(pages, page, () => {
+          calls.push({ kind: "list", resource, params: paramsToObject(params), page })
+        })
+        return Effect.succeed(result)
+      }),
+    resolveChannel: (reference) =>
+      Effect.suspend(() => {
+        calls.push({ kind: "resolveChannel", resource: reference, params: {} })
+        if (script.fail !== undefined) return Effect.fail(script.fail)
+        const resolved = pick(script.channels, channelIndex, {
+          id: reference,
+          requests: 1
+        } satisfies ResolvedChannel)
+        channelIndex++
+        return Effect.succeed(resolved)
+      })
+  }
+
+  const core: HttpCoreShape = {
+    getJson: (request: HttpCoreRequest) =>
+      Effect.suspend(() => {
+        calls.push({
+          kind: "getJson",
+          resource: request.resource,
+          params: paramsToObject(request.params),
+          authenticate: request.authenticate
+        })
+        if (script.failJson !== undefined) return Effect.fail(script.failJson)
+        const body: JsonValue = pick(script.json, jsonIndex, {} as JsonValue)
+        jsonIndex++
+        return Effect.succeed(body)
+      })
+  }
+
+  const decode = (input: string | Uint8Array): string =>
+    typeof input === "string" ? input : new TextDecoder().decode(input)
+
+  const stdio = Stdio.layerTest({
+    stdout: () =>
+      Sink.forEach((input: string | Uint8Array) => Effect.sync(() => stdout.push(decode(input)))),
+    stderr: () =>
+      Sink.forEach((input: string | Uint8Array) => Effect.sync(() => stderr.push(decode(input))))
+  })
+
+  const testLayer = Layer.mergeAll(
+    stdio,
+    Layer.succeed(YouTubeApi, api),
+    Layer.succeed(HttpCore, core),
+    RendererLive.pipe(Layer.provide(stdio))
+  )
+
+  const root = mountRoot(command, isOutputTTY)
+
+  return Effect.runPromise(
+    Effect.exit(
+      Command.runWith(root, { version: "test" })(argv).pipe(
+        Effect.provide(testLayer)
+      ) as Effect.Effect
+    )
+  ).then((exit) => {
+    if (Exit.isSuccess(exit)) {
+      return {
+        stdout: stdout.join(""),
+        stderr: stderr.join(""),
+        exitCode: 0,
+        error: undefined,
+        message: undefined,
+        calls
+      }
+    }
+    const squashed = Cause.squash(exit.cause) as {
+      readonly _tag?: string
+      readonly message?: string
+      readonly [Runtime.errorExitCode]?: number
+    }
+    const tagged = isOytcError(squashed) ? squashed : undefined
+    return {
+      stdout: stdout.join(""),
+      stderr: stderr.join(""),
+      exitCode: tagged === undefined ? frameworkExitCode(squashed) : exitCodeFor(tagged),
+      error: tagged,
+      message: tagged?.message ?? squashed.message,
+      calls
+    }
+  })
+}
+
+/**
+ * Exit code for an error raised by the CLI framework rather than by a handler.
+ *
+ * `CliError.ShowHelp` carries `Runtime.errorExitCode` directly, and it is **0**
+ * when `errors` is empty — that is the `oytc video` / `--help` path, which Go
+ * also exits 0 on. A non-empty `errors` list (unknown flag, unknown subcommand,
+ * bad choice) is exit 1 in the framework where Go exits 2, so it is translated
+ * here exactly as `main.ts` does.
+ */
+const frameworkExitCode = (error: { readonly [Runtime.errorExitCode]?: number }): number => {
+  const code = error[Runtime.errorExitCode]
+  return code === 0 ? 0 : 2
+}
+
+const OYTC_TAGS = new Set([
+  "UsageError",
+  "MissingKeyError",
+  "MissingOAuthError",
+  "ApiError",
+  "OAuthError",
+  "AuthHintError",
+  "NotFoundError",
+  "OperationalError",
+  "CancelledError"
+])
+
+const isOytcError = (u: { readonly _tag?: string }): u is OytcError =>
+  typeof u._tag === "string" && OYTC_TAGS.has(u._tag)
+
+/** The local stand-in for `src/cli/root.ts`. */
+const mountRoot = (command: never, isOutputTTY: boolean) =>
+  Command.make("oytc").pipe(
+    Command.withSharedFlags(globalFlags),
+    Command.withSubcommands([command]),
+    Command.provide((input) =>
+      Layer.effect(
+        AppOptions,
+        Effect.suspend(() => {
+          const resolved = resolveGlobals(input, { isOutputTTY })
+          return Result.isFailure(resolved)
+            ? Effect.fail(resolved.failure)
+            : Effect.succeed(resolved.success)
+        })
+      )
+    )
+  )
+
+/** The single stderr line a table render appends. */
+export const summaryLine = (itemCount: number, requests: number, nextPageToken = ""): string =>
+  `${itemCount} item(s), ${requests} request(s)${
+    nextPageToken === "" ? "" : `; more available (next token: ${nextPageToken})`
+  }\n`
+
+/** Assert a usage failure with an exact message, and that no request was made. */
+export const expectUsage = (result: RunResult, message: string): void => {
+  if (!(result.error instanceof UsageError)) {
+    throw new Error(
+      `expected UsageError, got ${String(result.error?._tag)}: ${String(result.message)}`
+    )
+  }
+  if (result.message !== message) {
+    throw new Error(
+      `expected message ${JSON.stringify(message)}, got ${JSON.stringify(result.message)}`
+    )
+  }
+  if (result.exitCode !== 2) throw new Error(`expected exit 2, got ${result.exitCode}`)
+  if (result.calls.length !== 0) {
+    throw new Error(`expected no requests, got ${result.calls.length}`)
+  }
+}
diff --git a/src/cli/playlist.test.ts b/src/cli/playlist.test.ts
new file mode 100644
index 0000000..28f7197
--- /dev/null
+++ b/src/cli/playlist.test.ts
@@ -0,0 +1,643 @@
+/**
+ * `oytc playlist {get,list,items}` plus the shared helpers that live in
+ * playlist.ts.
+ *
+ * Every validation message and exit code asserted here was captured from
+ * `/tmp/oytc-ref` (the compiled Go binary), not from the spec.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { NotFoundError } from "../domain/errors.ts"
+import {
+  playlistCommand,
+  batch,
+  exactArgs,
+  fieldSelectorIncludes,
+  fieldsWithRequired,
+  minimumArgs,
+  pageOptions,
+  partsOr,
+  setValues,
+  stripItemIDs,
+  validateEnum,
+  validateListFlags,
+  validateParts,
+  validateRequestedItems
+} from "./playlist.ts"
+import { expectUsage, listOf, responseOf, runCli, summaryLine } from "./harness.testutil.ts"
+
+const run = (argv: ReadonlyArray, options?: Parameters[2]) =>
+  runCli(playlistCommand, argv, options)
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+describe("partsOr", () => {
+  test("blank and whitespace-only fall back", () => {
+    expect(partsOr("", "snippet")).toBe("snippet")
+    expect(partsOr("   ", "snippet")).toBe("snippet")
+    expect(partsOr("\t\n", "snippet")).toBe("snippet")
+  })
+
+  test("a set value is used verbatim, untrimmed", () => {
+    expect(partsOr(" snippet ", "x")).toBe(" snippet ")
+    expect(partsOr("a,b", "x")).toBe("a,b")
+  })
+})
+
+describe("setValues", () => {
+  test("drops empty values and keeps order", () => {
+    expect(
+      setValues(
+        [["part", "snippet"]],
+        [
+          ["hl", ""],
+          ["fields", "items/id"],
+          ["videoId", ""]
+        ]
+      )
+    ).toEqual([
+      ["part", "snippet"],
+      ["fields", "items/id"]
+    ])
+  })
+})
+
+describe("validateEnum", () => {
+  test("an empty value always passes", () => {
+    expect(validateEnum("--order", "", "time", "relevance")).toBeUndefined()
+  })
+
+  test("an allowed value passes", () => {
+    expect(validateEnum("--order", "relevance", "time", "relevance")).toBeUndefined()
+  })
+
+  test("message lists the allowed values comma-separated", () => {
+    expect(validateEnum("--order", "bogus", "time", "relevance")?.message).toBe(
+      "--order must be one of: time, relevance"
+    )
+  })
+})
+
+describe("validateParts", () => {
+  test("a forbidden part anywhere in the list is rejected", () => {
+    expect(validateParts("snippet,subscriberSnippet", "subscriberSnippet")?.message).toBe(
+      'part "subscriberSnippet" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  test("segments are trimmed before comparison", () => {
+    expect(validateParts(" subscriberSnippet ", "subscriberSnippet")).toBeDefined()
+  })
+
+  test("a superstring is not a match", () => {
+    expect(validateParts("subscriberSnippetX", "subscriberSnippet")).toBeUndefined()
+  })
+})
+
+describe("arity helpers", () => {
+  test("exactArgs", () => {
+    expect(exactArgs(1, ["a"])).toBeUndefined()
+    expect(exactArgs(1, [])?.message).toBe("expected 1 argument(s), received 0")
+    expect(exactArgs(1, ["a", "b"])?.message).toBe("expected 1 argument(s), received 2")
+    expect(exactArgs(0, ["a"])?.message).toBe("expected 0 argument(s), received 1")
+  })
+
+  test("minimumArgs", () => {
+    expect(minimumArgs(1, ["a", "b"])).toBeUndefined()
+    expect(minimumArgs(1, [])?.message).toBe("expected at least 1 argument(s), received 0")
+  })
+})
+
+describe("validateListFlags", () => {
+  const flags = (pageSize: number, limit = 0) => ({
+    pageSize,
+    limit,
+    all: false,
+    pageToken: ""
+  })
+
+  test("bounds are inclusive", () => {
+    expect(validateListFlags(flags(1), 50)).toBeUndefined()
+    expect(validateListFlags(flags(50), 50)).toBeUndefined()
+    expect(validateListFlags(flags(100), 100)).toBeUndefined()
+  })
+
+  test("zero and negative are rejected, not clamped", () => {
+    expect(validateListFlags(flags(0), 50)?.message).toBe("--page-size must be between 1 and 50")
+    expect(validateListFlags(flags(-1), 50)?.message).toBe("--page-size must be between 1 and 50")
+  })
+
+  test("the max appears verbatim in the message", () => {
+    expect(validateListFlags(flags(101), 100)?.message).toBe(
+      "--page-size must be between 1 and 100"
+    )
+  })
+
+  test("page size is checked before limit", () => {
+    expect(validateListFlags(flags(999, -1), 50)?.message).toBe(
+      "--page-size must be between 1 and 50"
+    )
+  })
+
+  test("a negative limit is rejected; zero is allowed", () => {
+    expect(validateListFlags(flags(25, -1), 50)?.message).toBe("--limit cannot be negative")
+    expect(validateListFlags(flags(25, 0), 50)).toBeUndefined()
+  })
+})
+
+describe("pageOptions", () => {
+  test("maps the four list flags across", () => {
+    expect(pageOptions({ pageSize: 20, pageToken: "T", all: true, limit: 5 })).toEqual({
+      pageSize: 20,
+      pageToken: "T",
+      all: true,
+      limit: 5
+    })
+  })
+})
+
+describe("batch", () => {
+  test("splits into groups of at most size", () => {
+    expect(batch([1, 2, 3, 4, 5], 2)).toEqual([[1, 2], [3, 4], [5]])
+  })
+
+  test("an empty input produces no batches", () => {
+    expect(batch([], 50)).toEqual([])
+  })
+
+  test("an exact multiple produces no trailing empty batch", () => {
+    expect(batch([1, 2], 2)).toEqual([[1, 2]])
+  })
+})
+
+describe("fieldSelectorIncludes", () => {
+  test("a wildcard covers everything", () => {
+    expect(fieldSelectorIncludes("*", "items/id")).toBe(true)
+  })
+
+  test("the bare items selector covers items/id", () => {
+    expect(fieldSelectorIncludes("items", "items/id")).toBe(true)
+  })
+
+  test("an exact match", () => {
+    expect(fieldSelectorIncludes("items/id", "items/id")).toBe(true)
+  })
+
+  test("a deeper path implies the parent", () => {
+    expect(fieldSelectorIncludes("items/id/videoId", "items/id")).toBe(true)
+  })
+
+  test("a wildcard child covers the target", () => {
+    expect(fieldSelectorIncludes("items/*", "items/id")).toBe(true)
+  })
+
+  test("parenthesized groups expand", () => {
+    expect(fieldSelectorIncludes("items(id,snippet/title)", "items/id")).toBe(true)
+    expect(fieldSelectorIncludes("nextPageToken,items(snippet/title)", "items/id")).toBe(false)
+  })
+
+  test("an unrelated selector does not cover it", () => {
+    expect(fieldSelectorIncludes("nextPageToken", "items/id")).toBe(false)
+    expect(fieldSelectorIncludes("items/snippet", "items/id")).toBe(false)
+  })
+
+  test("whitespace is skipped", () => {
+    expect(fieldSelectorIncludes("items( id , snippet/title )", "items/id")).toBe(true)
+  })
+
+  /**
+   * Differentially generated: each pair was run through Go's
+   * `fieldSelectorIncludes` (internal/cli/fields.go) and the expectation is its
+   * actual return value. The malformed inputs are the interesting half — the
+   * Go parser never errors, it just yields whatever paths it managed to read.
+   */
+  test.each([
+    ["*", "items/id", true],
+    ["items", "items/id", true],
+    ["items/id", "items/id", true],
+    ["items/id/videoId", "items/id", true],
+    ["items/*", "items/id", true],
+    ["items(id,snippet/title)", "items/id", true],
+    ["items( id , snippet/title )", "items/id", true],
+    ["items((id))", "items/id", true],
+    ["items/id/kind", "items/id/kind", true],
+    ["nextPageToken,items(snippet/title)", "items/id", false],
+    ["nextPageToken", "items/id", false],
+    ["items/snippet", "items/id", false],
+    ["", "items/id", false],
+    ["i", "items/id", false],
+    ["items/idx", "items/id", false],
+    ["items/*/x", "items/id", false],
+    ["items/snippet/*", "items/id", false],
+    ["a/*", "items/id", false],
+    ["items(", "items/id", false],
+    [")", "items/id", false],
+    ["items/", "items/id", false],
+    [",,,", "items/id", false]
+  ])("matches Go for (%p, %p)", (selector, target, expected) => {
+    expect(fieldSelectorIncludes(selector as string, target as string)).toBe(expected)
+  })
+})
+
+describe("fieldsWithRequired", () => {
+  test("an empty selector is left alone and the field is preserved", () => {
+    expect(fieldsWithRequired("", "items/id")).toEqual(["", true])
+  })
+
+  test("an already-covering selector is left alone", () => {
+    expect(fieldsWithRequired("items/id", "items/id")).toEqual(["items/id", true])
+  })
+
+  test("otherwise the required path is appended and the field is stripped later", () => {
+    expect(fieldsWithRequired("items/snippet/title", "items/id")).toEqual([
+      "items/snippet/title,items/id",
+      false
+    ])
+  })
+})
+
+describe("stripItemIDs", () => {
+  test("preserve keeps the items untouched", () => {
+    const input = [{ id: "a", x: "1" }]
+    expect(stripItemIDs(input, true)).toBe(input)
+  })
+
+  test("otherwise id is removed from every item", () => {
+    expect(stripItemIDs([{ id: "a", x: "1" }, { id: "b" }], false)).toEqual([{ x: "1" }, {}])
+  })
+})
+
+describe("validateRequestedItems", () => {
+  test("all present", () => {
+    expect(
+      validateRequestedItems("playlists", ["a", "b"], [{ id: "a" }, { id: "b" }])
+    ).toBeUndefined()
+  })
+
+  test("reports only the missing ids, in request order", () => {
+    const error = validateRequestedItems("playlists", ["a", "b", "c"], [{ id: "b" }])
+    expect(error?.message).toBe("playlists not found: a, c")
+    expect(error).toBeInstanceOf(NotFoundError)
+  })
+
+  test("duplicate requests are de-duplicated", () => {
+    expect(validateRequestedItems("playlists", ["a", "a"], [{ id: "a" }])).toBeUndefined()
+    expect(validateRequestedItems("playlists", ["a", "a", "b"], [{ id: "a" }])?.message).toBe(
+      "playlists not found: b"
+    )
+  })
+
+  test("the equal-cardinality escape hatch: no ids returned but the counts match", () => {
+    expect(
+      validateRequestedItems("playlists", ["a", "b"], [{ snippet: {} }, { snippet: {} }])
+    ).toBeUndefined()
+  })
+
+  test("no ids returned and fewer items than requested reports them all", () => {
+    expect(validateRequestedItems("playlists", ["a", "b"], [{ snippet: {} }])?.message).toBe(
+      "playlists not found: a, b"
+    )
+  })
+
+  test("an empty id string does not count as returned", () => {
+    expect(validateRequestedItems("playlists", ["a"], [{ id: "" }])).toBeUndefined()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// playlist get
+// ---------------------------------------------------------------------------
+
+describe("playlist get", () => {
+  test("requires at least one id, before any request", async () => {
+    const result = await run(["playlist", "get"])
+    expectUsage(result, "expected at least 1 argument(s), received 0")
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+
+  test("sends the default parts and the joined ids", async () => {
+    const result = await run(["playlist", "get", "PL1", "PL2"], {
+      script: { get: [responseOf(`[{"id":"PL1"},{"id":"PL2"}]`)] }
+    })
+    expect(result.exitCode).toBe(0)
+    expect(result.calls).toHaveLength(1)
+    expect(result.calls[0]!.kind).toBe("get")
+    expect(result.calls[0]!.resource).toBe("playlists")
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet,contentDetails,status",
+      id: "PL1,PL2"
+    })
+  })
+
+  test("--parts overrides the default, --hl and --fields are forwarded", async () => {
+    const result = await run(
+      ["playlist", "get", "PL1", "--parts", "snippet", "--hl", "de", "--fields", "items"],
+      { script: { get: [responseOf(`[{"id":"PL1"}]`)] } }
+    )
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet",
+      id: "PL1",
+      hl: "de",
+      fields: "items"
+    })
+  })
+
+  test("batches ids in groups of 50 and counts one request each", async () => {
+    const ids = Array.from({ length: 120 }, (_, index) => `PL${index}`)
+    const script = {
+      get: [
+        responseOf(JSON.stringify(ids.slice(0, 50).map((id) => ({ id })))),
+        responseOf(JSON.stringify(ids.slice(50, 100).map((id) => ({ id })))),
+        responseOf(JSON.stringify(ids.slice(100).map((id) => ({ id }))))
+      ]
+    }
+    const result = await run(["playlist", "get", ...ids], { script })
+    expect(result.exitCode).toBe(0)
+    expect(result.calls).toHaveLength(3)
+    expect(result.calls[0]!.params["id"]!.split(",")).toHaveLength(50)
+    expect(result.calls[2]!.params["id"]!.split(",")).toHaveLength(20)
+    expect(result.stderr).toBe(summaryLine(120, 3))
+  })
+
+  test("a --fields selector without items/id is widened and the id stripped again", async () => {
+    const result = await run(["playlist", "get", "PL1", "--fields", "items/snippet/title"], {
+      script: { get: [responseOf(`[{"id":"PL1","snippet":{"title":"T"}}]`)] }
+    })
+    expect(result.calls[0]!.params["fields"]).toBe("items/snippet/title,items/id")
+    expect(result.stdout).not.toContain("PL1")
+    expect(result.stdout).toContain("T")
+  })
+
+  test("a --fields selector that already covers items/id is untouched", async () => {
+    const result = await run(["playlist", "get", "PL1", "--fields", "items/id"], {
+      script: { get: [responseOf(`[{"id":"PL1"}]`)] }
+    })
+    expect(result.calls[0]!.params["fields"]).toBe("items/id")
+    expect(result.stdout).toContain("PL1")
+  })
+
+  test("a missing id is a NotFoundError with exit 4", async () => {
+    const result = await run(["playlist", "get", "PL1", "PL2"], {
+      script: { get: [responseOf(`[{"id":"PL1"}]`)] }
+    })
+    expect(result.error).toBeInstanceOf(NotFoundError)
+    expect(result.message).toBe("playlists not found: PL2")
+    expect(result.exitCode).toBe(4)
+    expect(result.stdout).toBe("")
+  })
+
+  test("has no pagination flags", async () => {
+    const result = await run(["playlist", "get", "PL1", "--page-size", "5"])
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+
+  test("renders the default columns in declaration order", async () => {
+    const result = await run(["playlist", "get", "PL1"], {
+      script: {
+        get: [
+          responseOf(
+            `[{"id":"PL1","snippet":{"title":"T","channelTitle":"C"},"contentDetails":{"itemCount":3},"status":{"privacyStatus":"public"}}]`
+          )
+        ]
+      }
+    })
+    const [header, row] = result.stdout.split("\n")
+    expect(header).toContain("ID")
+    expect(header).toContain("SNIPPET.TITLE")
+    expect(header).toContain("STATUS.PRIVACYSTATUS")
+    expect(row).toContain("PL1")
+    expect(row).toContain("public")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// playlist list
+// ---------------------------------------------------------------------------
+
+describe("playlist list", () => {
+  test("--channel is required", async () => {
+    const result = await run(["playlist", "list"])
+    expectUsage(result, "--channel is required")
+    expect(result.calls).toEqual([])
+  })
+
+  test("takes no positional arguments", async () => {
+    const result = await run(["playlist", "list", "extra"])
+    expectUsage(result, "expected 0 argument(s), received 1")
+  })
+
+  test("page size defaults to 25 and maxes at 50", async () => {
+    const ok = await run(["playlist", "list", "--channel", "UC1"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(ok.calls[0]!.page?.pageSize).toBe(25)
+
+    const bad = await run(["playlist", "list", "--channel", "UC1", "--page-size", "51"])
+    expectUsage(bad, "--page-size must be between 1 and 50")
+  })
+
+  test("the page-size bound is checked before the missing --channel", async () => {
+    const result = await run(["playlist", "list", "--page-size", "999"])
+    expectUsage(result, "--page-size must be between 1 and 50")
+  })
+
+  test("--limit cannot be negative", async () => {
+    const result = await run(["playlist", "list", "--channel", "UC1", "--limit=-1"])
+    expectUsage(result, "--limit cannot be negative")
+  })
+
+  test("FRAMEWORK LIMITATION: space-separated negative values do not tokenize", async () => {
+    // `--limit -1` (with a space) fails inside the CLI tokenizer, which treats
+    // `-1` as a short flag rather than as the value of `--limit`:
+    //   "Missing value for flag --limit" + "Unrecognized flag: -1"
+    // Go's pflag accepts it and reports "--limit cannot be negative".
+    //
+    // This is NOT specific to `Flag.integer` — a `Flag.string` behaves the same
+    // way, so it cannot be worked around at the flag level. It affects every
+    // package that has a numeric flag a user might pass a negative value to.
+    // `--limit=-1` (with an equals sign) works and produces the Go message.
+    const result = await run(["playlist", "list", "--channel", "UC1", "--limit", "-1"])
+    expect(result.exitCode).toBe(2)
+    expect(result.error).toBeUndefined()
+    expect(result.calls).toEqual([])
+  })
+
+  test("assembles channelId, hl and fields", async () => {
+    const result = await run(
+      ["playlist", "list", "--channel", "UC1", "--hl", "fr", "--fields", "items"],
+      { script: { list: [listOf("[]")] } }
+    )
+    expect(result.calls[0]!.resource).toBe("playlists")
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet,contentDetails,status",
+      channelId: "UC1",
+      hl: "fr",
+      fields: "items"
+    })
+  })
+
+  test("forwards --all, --limit and --page-token", async () => {
+    const result = await run(
+      [
+        "playlist",
+        "list",
+        "--channel",
+        "UC1",
+        "--all",
+        "--limit",
+        "10",
+        "--page-token",
+        "TOK",
+        "--page-size",
+        "5"
+      ],
+      { script: { list: [listOf("[]")] } }
+    )
+    expect(result.calls[0]!.page).toEqual({
+      all: true,
+      limit: 10,
+      pageSize: 5,
+      pageToken: "TOK"
+    })
+  })
+
+  test("the stderr summary reports the next page token when one is present", async () => {
+    const result = await run(["playlist", "list", "--channel", "UC1"], {
+      script: { list: [listOf(`[{"id":"a"},{"id":"b"}]`, 2, "NEXT")] }
+    })
+    expect(result.stderr).toBe("2 item(s), 2 request(s); more available (next token: NEXT)\n")
+  })
+
+  test("--quiet suppresses the summary", async () => {
+    const result = await run(["playlist", "list", "--channel", "UC1", "--quiet"], {
+      script: { list: [listOf(`[{"id":"a"}]`)] }
+    })
+    expect(result.stderr).toBe("")
+    expect(result.stdout).not.toBe("")
+  })
+
+  test("non-table formats emit no summary at all", async () => {
+    const result = await run(["playlist", "list", "--channel", "UC1", "--format", "json"], {
+      script: { list: [listOf(`[{"id":"a"}]`)] }
+    })
+    expect(result.stderr).toBe("")
+    expect(result.stdout).toContain('"items"')
+  })
+
+  test("--columns overrides the defaults", async () => {
+    const result = await run(["playlist", "list", "--channel", "UC1", "--columns", "id"], {
+      script: { list: [listOf(`[{"id":"a","snippet":{"title":"T"}}]`)] }
+    })
+    expect(result.stdout).toBe("ID\na\n")
+  })
+
+  test("a bad global --timeout fails before the command's own checks", async () => {
+    // `resolveGlobals` runs inside `Command.provide`, which the framework
+    // builds before the handler — so this beats the missing --channel, exactly
+    // as it does in Go (`oytc --timeout 0 playlist list` -> the timeout error).
+    const result = await runCli(playlistCommand, ["playlist", "list", "--timeout", "0"])
+    expectUsage(result, "--timeout must be positive")
+    expect(result.calls).toEqual([])
+  })
+
+  test("--no-header omits the header row", async () => {
+    const result = await run(
+      ["playlist", "list", "--channel", "UC1", "--columns", "id", "--no-header"],
+      { script: { list: [listOf(`[{"id":"a"}]`)] } }
+    )
+    expect(result.stdout).toBe("a\n")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// playlist items
+// ---------------------------------------------------------------------------
+
+describe("playlist items", () => {
+  test("requires exactly one playlist id", async () => {
+    const none = await run(["playlist", "items"])
+    expectUsage(none, "expected 1 argument(s), received 0")
+    expect(none.calls).toEqual([])
+
+    const two = await run(["playlist", "items", "a", "b"])
+    expectUsage(two, "expected 1 argument(s), received 2")
+  })
+
+  test("the arity check precedes the page-size bound", async () => {
+    const result = await run(["playlist", "items", "--page-size", "999"])
+    expectUsage(result, "expected 1 argument(s), received 0")
+  })
+
+  test("KNOWN DIVERGENCE: a bad --timeout beats the arity check", async () => {
+    // Go reports "expected 1 argument(s), received 0" here, because cobra runs
+    // Args before PersistentPreRunE. The framework builds `Command.provide`
+    // (which is where resolveGlobals lives) before the handler, so the timeout
+    // error wins instead. Documented in playlist.ts; fixing it would require
+    // editing root.ts/globals.ts, which this package does not own.
+    const result = await run(["playlist", "items", "--timeout", "0"])
+    expectUsage(result, "--timeout must be positive")
+    expect(result.calls).toEqual([])
+  })
+
+  test("page size defaults to 50, not 25", async () => {
+    const result = await run(["playlist", "items", "PL1"], { script: { list: [listOf("[]")] } })
+    expect(result.calls[0]!.page?.pageSize).toBe(50)
+  })
+
+  test("page size maxes at 50", async () => {
+    const result = await run(["playlist", "items", "PL1", "--page-size", "51"])
+    expectUsage(result, "--page-size must be between 1 and 50")
+  })
+
+  test("assembles playlistId and the optional videoId", async () => {
+    const result = await run(["playlist", "items", "PL1", "--video", "V1"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.resource).toBe("playlistItems")
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet,contentDetails,status",
+      playlistId: "PL1",
+      videoId: "V1"
+    })
+  })
+
+  test("has no --hl flag", async () => {
+    const result = await run(["playlist", "items", "PL1", "--hl", "en"])
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+
+  test("renders the playlist-item default columns", async () => {
+    const result = await run(["playlist", "items", "PL1"], {
+      script: {
+        list: [
+          listOf(
+            `[{"snippet":{"position":1,"title":"T","videoOwnerChannelTitle":"O"},"contentDetails":{"videoId":"V"}}]`
+          )
+        ]
+      }
+    })
+    // Byte-for-byte against `output.Render(..., Format: "table")` in Go.
+    expect(result.stdout).toBe(
+      "SNIPPET.POSITION  CONTENTDETAILS.VIDEOID  SNIPPET.TITLE  SNIPPET.VIDEOOWNERCHANNELTITLE\n" +
+        "1                 V                       T              O\n"
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// group command
+// ---------------------------------------------------------------------------
+
+describe("the playlist group", () => {
+  test("bare `oytc playlist` prints help and exits 0", async () => {
+    const result = await run(["playlist"])
+    expect(result.exitCode).toBe(0)
+    expect(result.error).toBeUndefined()
+    expect(result.calls).toEqual([])
+  })
+})
diff --git a/src/cli/playlist.ts b/src/cli/playlist.ts
index ca14f9a..063b6e6 100644
--- a/src/cli/playlist.ts
+++ b/src/cli/playlist.ts
@@ -1,2 +1,620 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `oytc playlist {get,list,items}` — ports `playlistCommand()` and friends from
+ * `internal/cli/resources.go`.
+ *
+ * ---------------------------------------------------------------------------
+ * SHARED HELPERS LIVE HERE, TEMPORARILY
+ * ---------------------------------------------------------------------------
+ * P8a owns `src/cli/{fields,validate,render}.ts` and is expected to export the
+ * same helpers this file defines below (`fieldsWithRequired`, `validateEnum`,
+ * `renderResult`, …). Those modules were still empty stubs when this package
+ * was written, so the helpers are defined here — in a file this package owns —
+ * rather than imported from a stub that would not compile.
+ *
+ * They are direct ports of the Go originals, so once P8a lands the orchestrator
+ * can replace the marked section with re-exports from those modules.
+ * `comment.ts`, `subscription.ts` and `catalog.ts` import them from here, so one
+ * re-export keeps those three files untouched.
+ * ---------------------------------------------------------------------------
+ */
+
+import { Effect, Stdio, Stream } from "effect"
+import { Argument, Command, Flag } from "../effect.ts"
+import { NotFoundError, OperationalError, UsageError } from "../domain/errors.ts"
+import type { OytcError } from "../domain/errors.ts"
+import type { ListResult, PageOptions } from "../domain/listResult.ts"
+import type { JsonObject } from "../json/value.ts"
+import {
+  playlistGetColumns,
+  playlistItemsColumns,
+  playlistListColumns
+} from "../output/columns.ts"
+import { AppOptions, Renderer, YouTubeApi } from "../services/index.ts"
+import type { AppOptionsShape, Params, RendererShape, YouTubeApiShape } from "../services/index.ts"
+// Read-only import of P8a's shared helper. `goTrimSpace` is `strings.TrimSpace`
+// (unicode.IsSpace), which is NOT the same set as JS `String.prototype.trim()`:
+// JS trims U+FEFF, which Go does not consider space, and JS does not trim U+0085
+// (NEL) or U+00A0 (NBSP), which Go does. Both directions were confirmed against
+// /tmp/oytc-ref via `subscription list --parts "subscriberSnippet"`.
+import { goTrimSpace } from "./validate.ts"
+
+// ===========================================================================
+// BEGIN shared helpers — mirrors P8a src/cli/{validate,fields,render}.ts
+// ===========================================================================
+
+/** Everything a data command needs from the environment. */
+export type CommandServices = AppOptionsShape | RendererShape | Stdio.Stdio | YouTubeApiShape
+
+// ---------------------------------------------------------------------------
+// Flag groups (Go: addListFlags / addAPIFlags)
+// ---------------------------------------------------------------------------
+
+/**
+ * `addListFlags(cmd, &flags, defaultSize, maxSize)`.
+ *
+ * Bounds are NOT uniform: `comment replies`/`threads` are 1..100 default 20,
+ * `playlist items` defaults to 50, `playlist list`/`subscription list` default
+ * to 25 max 50, and the catalog commands take no pagination flags at all.
+ * `maxSize` is threaded to `validateListFlags` because it appears verbatim in
+ * both the flag description and the error message.
+ */
+export const listFlags = (defaultSize: number, maxSize: number) =>
+  ({
+    // cobra appends `(default N)` for any non-zero default; Effect's help
+    // renderer does not, so the suffix is written into the description to keep
+    // `--help` output comparable. Flags whose default is a zero value (`--limit
+    // 0`, `--page-token ""`, `--all false`) get no suffix, matching cobra.
+    pageSize: Flag.integer("page-size").pipe(
+      Flag.withDefault(defaultSize),
+      Flag.withDescription(`results per request (1-${maxSize}) (default ${defaultSize})`)
+    ),
+    pageToken: Flag.string("page-token").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("start at this API page token")
+    ),
+    all: Flag.boolean("all").pipe(Flag.withDescription("fetch all available pages")),
+    limit: Flag.integer("limit").pipe(
+      Flag.withDefault(0),
+      Flag.withDescription("maximum items to emit (0 means no additional limit)")
+    )
+  }) as const
+
+export interface ListFlagValues {
+  readonly pageSize: number
+  readonly pageToken: string
+  readonly all: boolean
+  readonly limit: number
+}
+
+/**
+ * Go's `cmd.PreRunE`: page size first, then limit. Both fire before any HTTP
+ * request and before the RunE semantic checks — verified against the reference
+ * binary, e.g. `playlist list --page-size 999` reports the page size even
+ * though `--channel` is also missing.
+ */
+export const validateListFlags = (
+  flags: ListFlagValues,
+  maxSize: number
+): UsageError | undefined => {
+  if (flags.pageSize < 1 || flags.pageSize > maxSize) {
+    return new UsageError({ message: `--page-size must be between 1 and ${maxSize}` })
+  }
+  if (flags.limit < 0) return new UsageError({ message: "--limit cannot be negative" })
+  return undefined
+}
+
+/** `listFlags` -> the client's `PageOptions`. */
+export const pageOptions = (flags: ListFlagValues): PageOptions => ({
+  all: flags.all,
+  limit: flags.limit,
+  pageSize: flags.pageSize,
+  pageToken: flags.pageToken
+})
+
+/** `addAPIFlags(cmd, &api, false)` — no `--hl`. */
+export const apiFlags = {
+  parts: Flag.string("parts").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("comma-separated API resource parts")
+  ),
+  fields: Flag.string("fields").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("Google partial-response fields selector")
+  )
+} as const
+
+/** `addAPIFlags(cmd, &api, true)` — adds `--hl`. */
+export const apiFlagsWithHl = {
+  ...apiFlags,
+  hl: Flag.string("hl").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("localization language code")
+  )
+} as const
+
+// ---------------------------------------------------------------------------
+// Parameter assembly (Go: partsOr / setValues)
+// ---------------------------------------------------------------------------
+
+/**
+ * `partsOr` — whitespace-only counts as unset, but the value is NOT trimmed.
+ *
+ * `goTrimSpace`, not `String.prototype.trim`: `--parts ""` must reach
+ * the API verbatim (Go does not treat U+FEFF as space), while `--parts ""`
+ * must fall back to the default (Go does).
+ */
+export const partsOr = (value: string, fallback: string): string =>
+  goTrimSpace(value) === "" ? fallback : value
+
+/**
+ * `setValues(params, map)` — appends every entry with a non-empty value. Go
+ * ranges over a map so its order is unspecified; here it is the caller's, and
+ * `HttpCore` sorts at encode time either way.
+ */
+export const setValues = (
+  params: Params,
+  entries: ReadonlyArray
+): Params => [...params, ...entries.filter(([, value]) => value !== "")]
+
+// ---------------------------------------------------------------------------
+// Enum / part validation (Go: validateEnum / validateParts)
+// ---------------------------------------------------------------------------
+
+/**
+ * `validateEnum` — an EMPTY value always passes. Load-bearing: most of these
+ * flags default to `""` meaning "do not send this parameter at all".
+ */
+export const validateEnum = (
+  flag: string,
+  value: string,
+  ...allowed: ReadonlyArray
+): UsageError | undefined => {
+  if (value === "") return undefined
+  if (allowed.includes(value)) return undefined
+  return new UsageError({ message: `${flag} must be one of: ${allowed.join(", ")}` })
+}
+
+/**
+ * `validateParts` — rejects owner-only parts. Each comma-separated segment is
+ * trimmed with Go's `strings.TrimSpace` first, so `--parts " subscriberSnippet "`
+ * is caught too (confirmed against the reference binary), and a U+FEFF-prefixed
+ * segment is NOT (Go does not treat it as space, so the part is sent as-is).
+ */
+export const validateParts = (
+  parts: string,
+  ...forbidden: ReadonlyArray
+): UsageError | undefined => {
+  for (const value of parts.split(",")) {
+    for (const blocked of forbidden) {
+      if (goTrimSpace(value) === blocked) {
+        return new UsageError({
+          message: `part "${blocked}" requires owner/OAuth access and is not supported`
+        })
+      }
+    }
+  }
+  return undefined
+}
+
+// ---------------------------------------------------------------------------
+// Positional arity (Go: exactArgs / minimumArgs)
+// ---------------------------------------------------------------------------
+
+/**
+ * Arity is checked in the handler rather than by the `Argument` primitive.
+ *
+ * Three framework options were measured, none of which reproduces Go exactly:
+ *
+ *   - `Argument.variadic({ min, max })` rejects at parse time but emits the
+ *     framework's own text ("Invalid value for argument : \"0 values\"").
+ *   - `Argument.between(1, 1)` silently DISCARDS extra positionals rather than
+ *     failing, so `playlist items a b` would succeed.
+ *   - `Argument.filter(pred, onFalse)` orders correctly (it runs before
+ *     `Command.provide`) but wraps the message as
+ *     `Invalid value for argument : "a,b". Expected: ` and routes it
+ *     through `ShowHelp`, which dumps the help block Go's `SilenceUsage`
+ *     suppresses.
+ *
+ * The verbatim messages are golden-verified in `/tmp/goldens/validation.txt`
+ * ("expected 1 argument(s), received 0"), so an unbounded `Argument.variadic()`
+ * plus these handler-side checks is the faithful port.
+ *
+ * KNOWN DIVERGENCE (single case, not golden-pinned): a global-flag failure now
+ * beats an arity failure, because `Command.provide` builds `AppOptions` before
+ * the handler runs. `oytc --timeout 0 playlist items` reports
+ * `--timeout must be positive` where Go reports
+ * `expected 1 argument(s), received 0`. Every OTHER ordering matches, including
+ * the golden `--format bogus … --page-size 999 x` case, because a bad
+ * `--format` is rejected by `Flag.choice` at parse time. Fixing this would
+ * require `AppOptions` to be forced lazily inside the handler, which means
+ * changing `root.ts`/`globals.ts` — files this package does not own.
+ */
+export const exactArgs = (count: number, args: ReadonlyArray): UsageError | undefined =>
+  args.length === count
+    ? undefined
+    : new UsageError({ message: `expected ${count} argument(s), received ${args.length}` })
+
+export const minimumArgs = (count: number, args: ReadonlyArray): UsageError | undefined =>
+  args.length >= count
+    ? undefined
+    : new UsageError({
+        message: `expected at least ${count} argument(s), received ${args.length}`
+      })
+
+// ---------------------------------------------------------------------------
+// Field selector grammar (Go: internal/cli/fields.go)
+// ---------------------------------------------------------------------------
+
+const NAME_STOP = "/(), \t\r\n"
+const SPACE = " \t\r\n"
+
+class FieldSelectorParser {
+  position = 0
+  constructor(readonly selector: string) {}
+
+  parseList(prefix: ReadonlyArray, terminator: string): Array {
+    const paths: Array = []
+    while (this.position < this.selector.length) {
+      this.skipSpacesAndCommas()
+      if (this.position >= this.selector.length) break
+      if (terminator !== "" && this.selector[this.position] === terminator) {
+        this.position++
+        break
+      }
+      paths.push(...this.parseField(prefix))
+    }
+    return paths
+  }
+
+  parseField(prefix: ReadonlyArray): Array {
+    const name = this.readName()
+    if (name === "") {
+      this.position++
+      return []
+    }
+    const path = [...prefix, name]
+    this.skipSpaces()
+    if (this.position >= this.selector.length) return [path.join("/")]
+    switch (this.selector[this.position]) {
+      case "/":
+        this.position++
+        this.skipSpaces()
+        return this.parseField(path)
+      case "(":
+        this.position++
+        return this.parseList(path, ")")
+      default:
+        return [path.join("/")]
+    }
+  }
+
+  readName(): string {
+    const start = this.position
+    while (
+      this.position < this.selector.length &&
+      !NAME_STOP.includes(this.selector[this.position]!)
+    ) {
+      this.position++
+    }
+    return this.selector.slice(start, this.position)
+  }
+
+  skipSpacesAndCommas(): void {
+    while (this.position < this.selector.length) {
+      const ch = this.selector[this.position]!
+      if (ch !== "," && !SPACE.includes(ch)) break
+      this.position++
+    }
+  }
+
+  skipSpaces(): void {
+    while (this.position < this.selector.length && SPACE.includes(this.selector[this.position]!)) {
+      this.position++
+    }
+  }
+}
+
+/** `fieldSelectorIncludes` — does `selector` already cover `target`? */
+export const fieldSelectorIncludes = (selector: string, target: string): boolean => {
+  for (const path of new FieldSelectorParser(selector).parseList([], "")) {
+    const wildcardParent = path.endsWith("/*") ? path.slice(0, -2) : path
+    if (
+      path === "*" ||
+      path === "items" ||
+      path === target ||
+      path.startsWith(`${target}/`) ||
+      target.startsWith(`${path}/`) ||
+      (wildcardParent !== path && target.startsWith(`${wildcardParent}/`))
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * `fieldsWithRequired(fields, required)` -> `[requestFields, preserve]`.
+ *
+ * When `--fields` does not already cover `required`, the selector is widened so
+ * the API still returns the field the CLI needs internally, and `preserve` comes
+ * back false so that field is deleted again before rendering.
+ */
+export const fieldsWithRequired = (
+  fields: string,
+  required: string
+): readonly [string, boolean] =>
+  fields === "" || fieldSelectorIncludes(fields, required)
+    ? [fields, true]
+    : [`${fields},${required}`, false]
+
+/** `stripItemIDs` — drops the injected `id` key when it was not requested. */
+export const stripItemIDs = (
+  items: ReadonlyArray,
+  preserve: boolean
+): ReadonlyArray => {
+  if (preserve) return items
+  return items.map((item) => {
+    const { id: _id, ...rest } = item
+    return rest as JsonObject
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Batched by-ID lookups (Go: batch / validateRequestedItems)
+// ---------------------------------------------------------------------------
+
+/** `batch(values, size)`. */
+export const batch = (
+  values: ReadonlyArray,
+  size: number
+): ReadonlyArray> => {
+  const batches: Array> = []
+  for (let i = 0; i < values.length; i += size) batches.push(values.slice(i, i + size))
+  return batches
+}
+
+/**
+ * `validateRequestedItems`.
+ *
+ * The equal-cardinality escape hatch matters: `--fields` may legitimately omit
+ * `id`, so when NO item carries an id and the count equals the number of
+ * distinct requested ids, the lookup is accepted rather than reported as
+ * entirely missing.
+ */
+export const validateRequestedItems = (
+  resource: string,
+  requested: ReadonlyArray,
+  items: ReadonlyArray
+): NotFoundError | undefined => {
+  const seen = new Set()
+  const uniqueRequested: Array = []
+  for (const id of requested) {
+    if (!seen.has(id)) {
+      seen.add(id)
+      uniqueRequested.push(id)
+    }
+  }
+
+  const returned = new Set()
+  for (const item of items) {
+    const id = item["id"]
+    if (typeof id === "string" && id !== "") returned.add(id)
+  }
+  if (returned.size === 0 && items.length === uniqueRequested.length) return undefined
+
+  let missing: ReadonlyArray = []
+  if (returned.size > 0) {
+    missing = uniqueRequested.filter((id) => !returned.has(id))
+  } else if (items.length < uniqueRequested.length) {
+    missing = uniqueRequested
+  }
+  if (missing.length === 0) return undefined
+  return new NotFoundError({ message: `${resource} not found: ${missing.join(", ")}` })
+}
+
+// ---------------------------------------------------------------------------
+// Rendering (Go: App.renderResult)
+// ---------------------------------------------------------------------------
+
+const writeStderr = (text: string): Effect.Effect =>
+  Effect.gen(function* () {
+    const stdio = yield* Stdio.Stdio
+    yield* Stream.run(Stream.make(text), stdio.stderr()).pipe(
+      Effect.catch((cause) =>
+        Effect.fail(new OperationalError({ message: "could not write summary", cause }))
+      )
+    )
+  })
+
+/**
+ * Render the result, then — only for `table` output and only when `--quiet` is
+ * unset — emit the one-line request summary on stderr:
+ * `"%d item(s), %d request(s)"`, optionally `"; more available (next token: %s)"`.
+ */
+export const renderResult = (
+  result: ListResult,
+  defaultColumns: ReadonlyArray
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const options = yield* AppOptions
+    const renderer = yield* Renderer
+    const columns = options.columns.length > 0 ? options.columns : defaultColumns
+    yield* renderer.render(result, {
+      format: options.format,
+      columns,
+      noHeader: options.noHeader
+    })
+    if (options.quiet || options.format !== "table") return
+    const more =
+      result.nextPageToken === "" ? "" : `; more available (next token: ${result.nextPageToken})`
+    yield* writeStderr(`${result.items.length} item(s), ${result.requests} request(s)${more}\n`)
+  })
+
+/**
+ * `App.runList`.
+ *
+ * The credential check lives inside `YouTubeApi`, so every usage error raised
+ * before this call is guaranteed to precede any HTTP traffic — the property
+ * `/tmp/goldens/validation.txt` pins.
+ */
+export const runList = (
+  resource: string,
+  params: Params,
+  flags: ListFlagValues,
+  defaultColumns: ReadonlyArray
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const api = yield* YouTubeApi
+    const result = yield* api.list(resource, params, pageOptions(flags))
+    yield* renderResult(result, defaultColumns)
+  })
+
+/**
+ * The shared body of `playlist get` and `comment get`: one request per batch of
+ * ids, results concatenated, then the not-found check.
+ *
+ * `batchSize` is 50 for playlists and **100** for comments.
+ */
+export const runBatchGet = (options: {
+  readonly resource: string
+  readonly ids: ReadonlyArray
+  readonly batchSize: number
+  readonly part: string
+  readonly fields: string
+  /** Extra params per request, excluding `part`, `id` and `fields`. */
+  readonly extra: ReadonlyArray
+  readonly defaultColumns: ReadonlyArray
+}): Effect.Effect =>
+  Effect.gen(function* () {
+    const api = yield* YouTubeApi
+    const [requestFields, preserveID] = fieldsWithRequired(options.fields, "items/id")
+
+    const collected: Array = []
+    let requests = 0
+    for (const group of batch(options.ids, options.batchSize)) {
+      const params = setValues(
+        [
+          ["part", options.part],
+          ["id", group.join(",")]
+        ],
+        [...options.extra, ["fields", requestFields]]
+      )
+      const response = yield* api.get(options.resource, params)
+      collected.push(...((response.items ?? []) as ReadonlyArray))
+      requests++
+    }
+
+    const notFound = validateRequestedItems(options.resource, options.ids, collected)
+    if (notFound !== undefined) return yield* Effect.fail(notFound)
+
+    yield* renderResult(
+      { items: stripItemIDs(collected, preserveID), nextPageToken: "", requests },
+      options.defaultColumns
+    )
+  })
+
+// ===========================================================================
+// END shared helpers
+// ===========================================================================
+
+/** `playlist get ...` — batch size 50, `minimumArgs(1)`. */
+export const playlistGetCommand = Command.make(
+  "get",
+  {
+    args: Argument.string("PLAYLIST_ID").pipe(Argument.variadic()),
+    ...apiFlagsWithHl
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const arity = minimumArgs(1, input.args)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      yield* runBatchGet({
+        resource: "playlists",
+        ids: input.args,
+        batchSize: 50,
+        part: partsOr(input.parts, "snippet,contentDetails,status"),
+        fields: input.fields,
+        extra: [["hl", input.hl]],
+        defaultColumns: playlistGetColumns
+      })
+    })
+).pipe(Command.withDescription("Get playlists by ID"))
+
+/**
+ * `playlist list --channel `.
+ *
+ * `--channel` is required, and that check runs in RunE — AFTER the pagination
+ * bounds, which is why `playlist list --page-size 999` reports the page size
+ * rather than the missing channel.
+ */
+export const playlistListCommand = Command.make(
+  "list",
+  {
+    args: Argument.string("ARG").pipe(Argument.variadic()),
+    channel: Flag.string("channel").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("channel ID (required)")
+    ),
+    ...listFlags(25, 50),
+    ...apiFlagsWithHl
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const arity = exactArgs(0, input.args)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      const bounds = validateListFlags(input, 50)
+      if (bounds !== undefined) return yield* Effect.fail(bounds)
+      if (input.channel === "") {
+        return yield* Effect.fail(new UsageError({ message: "--channel is required" }))
+      }
+      const params = setValues(
+        [
+          ["part", partsOr(input.parts, "snippet,contentDetails,status")],
+          ["channelId", input.channel]
+        ],
+        [
+          ["hl", input.hl],
+          ["fields", input.fields]
+        ]
+      )
+      yield* runList("playlists", params, input, playlistListColumns)
+    })
+).pipe(Command.withDescription("List a channel's public playlists"))
+
+/** `playlist items ` — default page size 50 (not 25), max 50, no `--hl`. */
+export const playlistItemsCommand = Command.make(
+  "items",
+  {
+    args: Argument.string("PLAYLIST_ID").pipe(Argument.variadic()),
+    video: Flag.string("video").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("only items for this video ID")
+    ),
+    ...listFlags(50, 50),
+    ...apiFlags
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const arity = exactArgs(1, input.args)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      const bounds = validateListFlags(input, 50)
+      if (bounds !== undefined) return yield* Effect.fail(bounds)
+      const params = setValues(
+        [
+          ["part", partsOr(input.parts, "snippet,contentDetails,status")],
+          ["playlistId", input.args[0]!]
+        ],
+        [
+          ["videoId", input.video],
+          ["fields", input.fields]
+        ]
+      )
+      yield* runList("playlistItems", params, input, playlistItemsColumns)
+    })
+).pipe(Command.withDescription("List items in a playlist"))
+
+/** The `playlist` group. Bare `oytc playlist` prints help and exits 0. */
+export const playlistCommand = Command.make("playlist").pipe(
+  Command.withDescription("Read playlists and playlist items"),
+  Command.withSubcommands([playlistGetCommand, playlistListCommand, playlistItemsCommand])
+)
diff --git a/src/cli/render.test.ts b/src/cli/render.test.ts
new file mode 100644
index 0000000..5af4573
--- /dev/null
+++ b/src/cli/render.test.ts
@@ -0,0 +1,278 @@
+import { describe, expect, test } from "bun:test"
+import { Effect, Layer, Result, Sink, Stdio } from "effect"
+import type { ListResult } from "../domain/listResult.ts"
+import { parseJson } from "../json/parse.ts"
+import type { JsonObject } from "../json/value.ts"
+import { RendererLive } from "../impl/renderer.ts"
+import { AppOptions } from "../services/index.ts"
+import type { AppOptionsShape, OutputFormat } from "../services/index.ts"
+import { searchColumns, videoTrainabilityColumns } from "../output/columns.ts"
+import { renderObject, renderOptionsFor, renderResult, summaryText } from "./render.ts"
+
+const items = (text: string): ReadonlyArray => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as ReadonlyArray
+}
+
+const obj = (text: string): JsonObject => {
+  const parsed = parseJson(text)
+  if (Result.isFailure(parsed)) throw new Error(parsed.failure.message)
+  return parsed.success as JsonObject
+}
+
+const listOf = (text: string, requests = 1, nextPageToken = ""): ListResult => ({
+  items: items(text),
+  nextPageToken,
+  requests
+})
+
+const options = (over: Partial = {}): AppOptionsShape => ({
+  format: "table" as OutputFormat,
+  columns: [],
+  noHeader: false,
+  quiet: false,
+  timeoutMillis: 20_000,
+  isOutputTTY: true,
+  ...over
+})
+
+interface Captured {
+  readonly stdout: string
+  readonly stderr: string
+}
+
+/** Drive a render effect through the real Renderer over a capturing Stdio. */
+const capture = (
+  effect: Effect.Effect,
+  appOptions: AppOptionsShape
+): Promise => {
+  const out: Array = []
+  const err: Array = []
+  const decode = (input: string | Uint8Array): string =>
+    typeof input === "string" ? input : new TextDecoder().decode(input)
+
+  const stdio = Stdio.layerTest({
+    stdout: () => Sink.forEach((input: string | Uint8Array) => Effect.sync(() => out.push(decode(input)))),
+    stderr: () => Sink.forEach((input: string | Uint8Array) => Effect.sync(() => err.push(decode(input))))
+  })
+
+  const layer = Layer.mergeAll(
+    stdio,
+    Layer.succeed(AppOptions, appOptions),
+    RendererLive.pipe(Layer.provide(stdio))
+  )
+
+  return Effect.runPromise(
+    effect.pipe(Effect.provide(layer)) as Effect.Effect
+  ).then(() => ({ stdout: out.join(""), stderr: err.join("") }))
+}
+
+const renderList = (
+  result: ListResult,
+  defaults: ReadonlyArray,
+  appOptions: AppOptionsShape
+): Promise =>
+  capture(renderResult(result, defaults) as Effect.Effect, appOptions)
+
+describe("summaryText", () => {
+  test("the base form", () => {
+    expect(summaryText(listOf('[{"id":"a"},{"id":"b"}]', 3))).toBe("2 item(s), 3 request(s)\n")
+  })
+
+  test("zero items and zero requests still render", () => {
+    expect(summaryText({ items: [], nextPageToken: "", requests: 0 })).toBe(
+      "0 item(s), 0 request(s)\n"
+    )
+  })
+
+  test("a next page token appends the resume hint, unquoted", () => {
+    expect(summaryText(listOf('[{"id":"a"}]', 1, "CAUQAA"))).toBe(
+      "1 item(s), 1 request(s); more available (next token: CAUQAA)\n"
+    )
+  })
+
+  test("singular counts are NOT pluralised away — Go always says item(s)", () => {
+    expect(summaryText(listOf('[{"id":"a"}]', 1))).toBe("1 item(s), 1 request(s)\n")
+  })
+})
+
+describe("renderOptionsFor — column resolution", () => {
+  test("--columns wins over the command defaults", () => {
+    expect(renderOptionsFor(options({ columns: ["id", "x.y"] }), searchColumns).columns).toEqual([
+      "id",
+      "x.y"
+    ])
+  })
+
+  test("the command defaults are used when --columns is absent", () => {
+    expect(renderOptionsFor(options(), searchColumns).columns).toEqual(searchColumns)
+  })
+
+  test("with neither, the global fallback applies", () => {
+    expect(renderOptionsFor(options(), []).columns).toEqual(["id", "snippet.title"])
+  })
+
+  test("format and noHeader pass straight through", () => {
+    const resolved = renderOptionsFor(options({ format: "tsv", noHeader: true }), searchColumns)
+    expect(resolved.format).toBe("tsv")
+    expect(resolved.noHeader).toBe(true)
+  })
+
+  test("column ORDER is preserved, never sorted (G4)", () => {
+    expect(renderOptionsFor(options({ columns: ["z", "a", "m"] }), []).columns).toEqual([
+      "z",
+      "a",
+      "m"
+    ])
+  })
+})
+
+describe("renderResult — the stderr summary line", () => {
+  const result = listOf('[{"id":"a","snippet":{"title":"T"}}]', 2)
+  const columns = ["id", "snippet.title"]
+
+  test("table format emits the summary", async () => {
+    const captured = await renderList(result, columns, options())
+    expect(captured.stderr).toBe("1 item(s), 2 request(s)\n")
+    expect(captured.stdout).toContain("ID")
+  })
+
+  test("--quiet suppresses it, leaving stdout untouched", async () => {
+    const captured = await renderList(result, columns, options({ quiet: true }))
+    expect(captured.stderr).toBe("")
+    expect(captured.stdout).toContain("ID")
+  })
+
+  test("json format never emits it, even without --quiet", async () => {
+    const captured = await renderList(result, columns, options({ format: "json" }))
+    expect(captured.stderr).toBe("")
+  })
+
+  test("jsonl format never emits it", async () => {
+    const captured = await renderList(result, columns, options({ format: "jsonl" }))
+    expect(captured.stderr).toBe("")
+  })
+
+  test("tsv format never emits it — table only", async () => {
+    const captured = await renderList(result, columns, options({ format: "tsv" }))
+    expect(captured.stderr).toBe("")
+  })
+
+  test("the resume hint reaches stderr", async () => {
+    const captured = await renderList(
+      listOf('[{"id":"a"}]', 1, "TOKEN"),
+      columns,
+      options()
+    )
+    expect(captured.stderr).toBe("1 item(s), 1 request(s); more available (next token: TOKEN)\n")
+  })
+
+  test("an empty result still renders the header and the summary", async () => {
+    const captured = await renderList(
+      { items: [], nextPageToken: "", requests: 1 },
+      columns,
+      options()
+    )
+    expect(captured.stderr).toBe("0 item(s), 1 request(s)\n")
+    expect(captured.stdout).toContain("ID")
+  })
+})
+
+describe("renderResult — stdout content per format", () => {
+  const result = listOf('[{"id":"a","snippet":{"title":"T"}}]', 1)
+
+  test("json emits the full envelope with requests", async () => {
+    const captured = await renderList(result, ["id"], options({ format: "json" }))
+    expect(captured.stdout).toBe(
+      ['{', '  "items": [', '    {', '      "id": "a",', '      "snippet": {', '        "title": "T"', '      }', '    }', '  ],', '  "requests": 1', '}', ''].join("\n")
+    )
+  })
+
+  test("jsonl emits one compact line per item and no envelope", async () => {
+    const captured = await renderList(result, ["id"], options({ format: "jsonl" }))
+    expect(captured.stdout).toBe('{"id":"a","snippet":{"title":"T"}}\n')
+  })
+
+  test("jsonl of an empty result emits ZERO bytes, not a blank line", async () => {
+    const captured = await renderList(
+      { items: [], nextPageToken: "", requests: 1 },
+      ["id"],
+      options({ format: "jsonl" })
+    )
+    expect(captured.stdout).toBe("")
+  })
+
+  test("tsv uses declaration order for headers (G4)", async () => {
+    const captured = await renderList(
+      result,
+      ["snippet.title", "id"],
+      options({ format: "tsv" })
+    )
+    expect(captured.stdout).toBe("SNIPPET.TITLE\tID\nT\ta\n")
+  })
+
+  test("--no-header drops the header row", async () => {
+    const captured = await renderList(
+      result,
+      ["id"],
+      options({ format: "tsv", noHeader: true })
+    )
+    expect(captured.stdout).toBe("a\n")
+  })
+
+  test("G1: a list-result array cell is comma-joined, no brackets or quotes", async () => {
+    const captured = await renderList(
+      listOf('[{"tags":["a","b"]}]'),
+      ["tags"],
+      options({ format: "tsv" })
+    )
+    expect(captured.stdout).toBe("TAGS\na,b\n")
+  })
+})
+
+describe("renderObject", () => {
+  const trainability = obj('{"videoId":"abc","permitted":false}')
+
+  test("no summary line is emitted, even on table format", async () => {
+    const captured = await capture(
+      renderObject(trainability, videoTrainabilityColumns) as Effect.Effect,
+      options()
+    )
+    expect(captured.stderr).toBe("")
+    expect(captured.stdout).toContain("VIDEOID")
+    expect(captured.stdout).toContain("PERMITTED")
+  })
+
+  test("json emits a bare object with SORTED keys (G4)", async () => {
+    const captured = await capture(
+      renderObject(trainability, videoTrainabilityColumns) as Effect.Effect,
+      options({ format: "json" })
+    )
+    expect(captured.stdout).toBe('{\n  "permitted": false,\n  "videoId": "abc"\n}\n')
+  })
+
+  test("tsv keeps the caller's column order (G4)", async () => {
+    const captured = await capture(
+      renderObject(trainability, videoTrainabilityColumns) as Effect.Effect,
+      options({ format: "tsv" })
+    )
+    expect(captured.stdout).toBe("VIDEOID\tPERMITTED\nabc\tfalse\n")
+  })
+
+  test("--columns overrides the command defaults", async () => {
+    const captured = await capture(
+      renderObject(trainability, videoTrainabilityColumns) as Effect.Effect,
+      options({ format: "tsv", columns: ["permitted"] })
+    )
+    expect(captured.stdout).toBe("PERMITTED\nfalse\n")
+  })
+
+  test("a missing column renders as an empty cell", async () => {
+    const captured = await capture(
+      renderObject(trainability, []) as Effect.Effect,
+      options({ format: "tsv", columns: ["nope"] })
+    )
+    expect(captured.stdout).toBe("NOPE\n\n")
+  })
+})
diff --git a/src/cli/render.ts b/src/cli/render.ts
index ca14f9a..770164e 100644
--- a/src/cli/render.ts
+++ b/src/cli/render.ts
@@ -1,2 +1,101 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * The two output paths every command ends in.
+ *
+ * Ports `(*App).renderResult` from `internal/cli/app.go` and the `RenderObject`
+ * call in `internal/cli/channel_video.go`. Both resolve columns the same way —
+ * `--columns` if given, else the command's defaults — and hand off to the
+ * `Renderer` service; `renderResult` additionally emits the human summary line
+ * on stderr.
+ *
+ * The summary line is emitted ONLY when the format is `table` and `--quiet` is
+ * unset. That is Go's rule verbatim: piping to `jq` gets clean JSON with no
+ * commentary, and `--quiet` silences it on a terminal too.
+ *
+ * SHARED HELPER — P8b and P8c import from here read-only. Do not edit outside
+ * P8a.
+ */
+
+import { Effect, Stdio, Stream } from "effect"
+import { OperationalError } from "../domain/errors.ts"
+import type { OytcError } from "../domain/errors.ts"
+import type { ListResult } from "../domain/listResult.ts"
+import type { JsonObject } from "../json/value.ts"
+import { resolveColumns } from "../output/columns.ts"
+import { AppOptions, Renderer } from "../services/index.ts"
+import type {
+  AppOptionsShape,
+  RendererShape,
+  RenderOptions
+} from "../services/index.ts"
+
+/**
+ * The `fmt.Fprintf(a.Err, …)` summary.
+ *
+ * Go writes it as two or three `Fprintf` calls plus an `Fprintln`; the bytes
+ * are what matters, so it is assembled once here. Note there is no space before
+ * the `;` and the token is NOT quoted.
+ */
+export const summaryText = (result: ListResult): string =>
+  `${result.items.length} item(s), ${result.requests} request(s)${
+    result.nextPageToken === ""
+      ? ""
+      : `; more available (next token: ${result.nextPageToken})`
+  }\n`
+
+/** Write one string to stderr through the Stdio service. */
+const writeStderr = (text: string): Effect.Effect =>
+  Effect.gen(function* () {
+    const stdio = yield* Stdio.Stdio
+    yield* Stream.run(Stream.make(text), stdio.stderr()).pipe(
+      Effect.catch((cause) =>
+        Effect.fail(new OperationalError({ message: "could not write output", cause }))
+      )
+    )
+  })
+
+/** `AppOptions` + the command's default columns -> the Renderer's options. */
+export const renderOptionsFor = (
+  options: AppOptionsShape,
+  defaultColumns: ReadonlyArray
+): RenderOptions => ({
+  format: options.format,
+  columns: resolveColumns(options.columns, defaultColumns),
+  noHeader: options.noHeader
+})
+
+/**
+ * `renderResult` — render the list envelope, then the stderr summary.
+ *
+ * The summary is written AFTER stdout, which matters when both are the same
+ * terminal: the count appears below the table, as it does in Go.
+ */
+export const renderResult = (
+  result: ListResult,
+  defaultColumns: ReadonlyArray
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const options = yield* AppOptions
+    const renderer = yield* Renderer
+    yield* renderer.render(result, renderOptionsFor(options, defaultColumns))
+    if (!options.quiet && options.format === "table") {
+      yield* writeStderr(summaryText(result))
+    }
+  })
+
+/**
+ * `RenderObject` — a bare object with no list envelope, and NO summary line.
+ *
+ * `video trainability` is the only P8a caller; `status`, `version` and `update`
+ * (P8c) use the same path. Go passes `a.columns` straight through here rather
+ * than going via `renderResult`, so the command's defaults are applied by the
+ * caller — `resolveColumns` reproduces that with the same precedence.
+ */
+export const renderObject = (
+  object: JsonObject,
+  defaultColumns: ReadonlyArray
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const options = yield* AppOptions
+    const renderer = yield* Renderer
+    yield* renderer.renderObject(object, renderOptionsFor(options, defaultColumns))
+  })
diff --git a/src/cli/root.ts b/src/cli/root.ts
index 1d177c6..642568c 100644
--- a/src/cli/root.ts
+++ b/src/cli/root.ts
@@ -24,16 +24,43 @@ import { AppOptions, ProcessEnv } from "../services/index.ts"
 import { ProcessEnvLive } from "../impl/processEnv.ts"
 import { globalFlags } from "./flags.ts"
 import { resolveGlobals } from "./globals.ts"
+import { analyticsCommand } from "./analyticsCmd.ts"
+import { authCommands } from "./auth.ts"
+import { catalogCommands } from "./catalog.ts"
+import { channelCommand } from "./channel.ts"
+import { commentCommand } from "./comment.ts"
+import { liveChatCommand } from "./livechat.ts"
+import { playlistCommand } from "./playlist.ts"
+import { searchCommand } from "./search.ts"
+import { skillsCommand } from "./skillsCmd.ts"
+import { subscriptionCommand } from "./subscription.ts"
+import { versionUpdateCommands } from "./versionUpdate.ts"
+import { videoCommand } from "./video.ts"
 
 const DESCRIPTION =
   "Read public YouTube data and your own channel analytics from the command line."
 
 /**
- * Subcommands are registered here as they are implemented. Each entry comes
- * from its own module, so parallel packages never edit this list concurrently
- * beyond adding their own import.
+ * The full command tree: 12 group commands over 30 runnable leaves.
+ *
+ * Group commands (`analytics`, `channel`, …) carry no handler, so invoking one
+ * bare prints help and exits 0 — matching cobra, where those commands had no
+ * `RunE`.
  */
-const subcommands: ReadonlyArray = []
+const subcommands = [
+  ...authCommands,
+  analyticsCommand,
+  searchCommand,
+  channelCommand,
+  videoCommand,
+  playlistCommand,
+  commentCommand,
+  subscriptionCommand,
+  liveChatCommand,
+  ...catalogCommands,
+  ...versionUpdateCommands,
+  skillsCommand
+] as const
 
 export const root = Command.make("oytc").pipe(
   Command.withDescription(DESCRIPTION),
diff --git a/src/cli/search.test.ts b/src/cli/search.test.ts
new file mode 100644
index 0000000..ac2f694
--- /dev/null
+++ b/src/cli/search.test.ts
@@ -0,0 +1,659 @@
+import { describe, expect, test } from "bun:test"
+import { expectUsage, pageOf, runCli, summaryLine } from "./p8aHarness.testutil.ts"
+import type { ApiScript, RunResult } from "./p8aHarness.testutil.ts"
+import { searchCommand, searchKindFilter } from "./search.ts"
+
+/** The five-parameter Command generic differs per command; the harness only mounts it. */
+const cmd = (c: unknown) => c as never
+
+const search = (argv: ReadonlyArray, script: ApiScript = {}): Promise =>
+  runCli(cmd(searchCommand), argv, { script })
+
+/** One search item of a given kind. */
+const item = (kind: string, id: string, title = "T"): string =>
+  `{"id":{"kind":"youtube#${kind}","${kind}Id":"${id}"},"snippet":{"title":"${title}"}}`
+
+const params = (result: RunResult): Record => result.calls[0]!.params
+
+// ---------------------------------------------------------------------------
+// validation, in Go's exact order
+// ---------------------------------------------------------------------------
+
+describe("search — argument count", () => {
+  test("zero arguments is fine — QUERY is optional", async () => {
+    const result = await search(["search"], { pages: [pageOf(`[${item("video", "v")}]`)] })
+    expect(result.exitCode).toBe(0)
+    expect(params(result)).not.toHaveProperty("q")
+  })
+
+  test("one argument becomes q", async () => {
+    const result = await search(["search", "cats"], { pages: [pageOf(`[${item("video", "v")}]`)] })
+    expect(params(result)["q"]).toBe("cats")
+  })
+
+  test("two arguments is a usage error", async () => {
+    expectUsage(await search(["search", "a", "b"]), "expected at most 1 argument(s), received 2")
+  })
+
+  test("the arg count wins over every other check", async () => {
+    expectUsage(
+      await search(["search", "--order", "bogus", "a", "b"]),
+      "expected at most 1 argument(s), received 2"
+    )
+    expectUsage(
+      await search(["search", "--page-size", "99", "a", "b"]),
+      "expected at most 1 argument(s), received 2"
+    )
+  })
+})
+
+describe("search — pagination bounds", () => {
+  test("G3: --page-size must be between 1 and 50", async () => {
+    expectUsage(
+      await search(["search", "foo", "--page-size", "99"]),
+      "--page-size must be between 1 and 50"
+    )
+    expectUsage(await search(["search", "--page-size", "0"]), "--page-size must be between 1 and 50")
+  })
+
+  test("G3: --limit cannot be negative", async () => {
+    expectUsage(await search(["search", "--limit=-1"]), "--limit cannot be negative")
+  })
+
+  test("pagination is checked before the enums", async () => {
+    expectUsage(
+      await search(["search", "--page-size", "99", "--order", "bogus"]),
+      "--page-size must be between 1 and 50"
+    )
+  })
+
+  test("the default page size is 25", async () => {
+    const result = await search(["search"], { pages: [pageOf("[]")] })
+    expect(result.calls[0]!.page!.pageSize).toBe(25)
+  })
+})
+
+describe("search — enum validation in source order", () => {
+  test("--order", async () => {
+    expectUsage(
+      await search(["search", "--order", "bogus"]),
+      "--order must be one of: date, rating, relevance, title, videoCount, viewCount"
+    )
+  })
+
+  test("--safe-search comes after --order", async () => {
+    expectUsage(
+      await search(["search", "--order", "bogus", "--safe-search", "bogus"]),
+      "--order must be one of: date, rating, relevance, title, videoCount, viewCount"
+    )
+    expectUsage(
+      await search(["search", "--safe-search", "bogus"]),
+      "--safe-search must be one of: moderate, none, strict"
+    )
+  })
+
+  test("--type comes after --safe-search", async () => {
+    expectUsage(
+      await search(["search", "--safe-search", "bogus", "--type", "bogus"]),
+      "--safe-search must be one of: moderate, none, strict"
+    )
+    expectUsage(
+      await search(["search", "--type", "bogus"]),
+      "--type must be one of: video, channel, playlist"
+    )
+  })
+
+  test("--type is a CSV enum: each entry is validated after trimming", async () => {
+    expectUsage(
+      await search(["search", "--type", "video,bogus"]),
+      "--type must be one of: video, channel, playlist"
+    )
+    const ok = await search(["search", "--type", "video, channel"], { pages: [pageOf("[]")] })
+    expect(ok.exitCode).toBe(0)
+  })
+
+  test("--channel-type comes after --type", async () => {
+    expectUsage(
+      await search(["search", "--type", "bogus", "--channel-type", "bogus"]),
+      "--type must be one of: video, channel, playlist"
+    )
+    expectUsage(
+      await search(["search", "--channel-type", "bogus"]),
+      "--channel-type must be one of: any, show"
+    )
+  })
+
+  test("the remaining video enums, each with its exact message", async () => {
+    const cases: ReadonlyArray = [
+      ["--event-type", "bogus", "--event-type must be one of: completed, live, upcoming"],
+      ["--video-caption", "bogus", "--video-caption must be one of: any, closedCaption, none"],
+      ["--video-duration", "bogus", "--video-duration must be one of: any, short, medium, long"],
+      ["--video-embeddable", "bogus", "--video-embeddable must be one of: any, true"],
+      [
+        "--video-license",
+        "bogus",
+        "--video-license must be one of: any, creativeCommon, youtube"
+      ],
+      [
+        "--video-paid-product-placement",
+        "bogus",
+        "--video-paid-product-placement must be one of: any, true"
+      ],
+      ["--video-syndicated", "bogus", "--video-syndicated must be one of: any, true"]
+    ]
+    for (const [flag, value, message] of cases) {
+      expectUsage(await search(["search", flag, value]), message)
+    }
+  })
+
+  test("the enum order among the video filters is caption, duration, embeddable, …", async () => {
+    expectUsage(
+      await search(["search", "--video-caption", "bogus", "--video-duration", "bogus"]),
+      "--video-caption must be one of: any, closedCaption, none"
+    )
+    expectUsage(
+      await search(["search", "--video-duration", "bogus", "--video-embeddable", "bogus"]),
+      "--video-duration must be one of: any, short, medium, long"
+    )
+  })
+
+  test("--event-type comes before --video-caption", async () => {
+    expectUsage(
+      await search(["search", "--event-type", "bogus", "--video-caption", "bogus"]),
+      "--event-type must be one of: completed, live, upcoming"
+    )
+  })
+})
+
+describe("search — timestamps come after every enum", () => {
+  test("a bad enum beats a bad timestamp", async () => {
+    expectUsage(
+      await search(["search", "--video-duration", "bogus", "--published-after", "nope"]),
+      "--video-duration must be one of: any, short, medium, long"
+    )
+  })
+
+  test("--published-after then --published-before", async () => {
+    expectUsage(
+      await search(["search", "--published-after", "x", "--published-before", "y"]),
+      "--published-after must be an RFC 3339 timestamp"
+    )
+    expectUsage(
+      await search(["search", "--published-before", "y"]),
+      "--published-before must be an RFC 3339 timestamp"
+    )
+  })
+})
+
+describe("search — cross-flag checks", () => {
+  test("--location without --location-radius", async () => {
+    expectUsage(
+      await search(["search", "--location", "1,2"]),
+      "--location and --location-radius must be used together"
+    )
+  })
+
+  test("--location-radius without --location", async () => {
+    expectUsage(
+      await search(["search", "--location-radius", "5km"]),
+      "--location and --location-radius must be used together"
+    )
+  })
+
+  test("the together-check beats the video-filter check", async () => {
+    // --location IS a video filter, but the pairing check runs first.
+    expectUsage(
+      await search(["search", "--type", "video", "--location", "1,2"]),
+      "--location and --location-radius must be used together"
+    )
+  })
+
+  test("both together with --type video is accepted", async () => {
+    const result = await search(
+      ["search", "--type", "video", "--location", "1,2", "--location-radius", "5km"],
+      { pages: [pageOf("[]")] }
+    )
+    expect(result.exitCode).toBe(0)
+  })
+})
+
+/**
+ * The headline wart: `resourceType != "video"` is EXACT string equality, so a
+ * type list merely CONTAINING video is still rejected. Every case here was
+ * verified against `/tmp/oytc-ref`.
+ */
+describe("search — video-specific filters require EXACTLY --type video", () => {
+  test("G3: the default type list is rejected", async () => {
+    expectUsage(
+      await search(["search", "--video-duration", "short"]),
+      "video-specific filters require --type video"
+    )
+  })
+
+  test("--type video,channel is rejected even though it contains video", async () => {
+    expectUsage(
+      await search(["search", "--type", "video,channel", "--video-duration", "short"]),
+      "video-specific filters require --type video"
+    )
+  })
+
+  test('--type "video " with a trailing space is rejected — no trimming here', async () => {
+    expectUsage(
+      await search(["search", "--type", "video ", "--video-duration", "short"]),
+      "video-specific filters require --type video"
+    )
+  })
+
+  test('--type "video," with a trailing comma is rejected', async () => {
+    expectUsage(
+      await search(["search", "--type", "video,", "--video-duration", "short"]),
+      "video-specific filters require --type video"
+    )
+  })
+
+  test("--type video exactly is accepted", async () => {
+    const result = await search(["search", "--type", "video", "--video-duration", "short"], {
+      pages: [pageOf("[]")]
+    })
+    expect(result.exitCode).toBe(0)
+  })
+
+  test("all nine video-specific filters trigger it", async () => {
+    const filters: ReadonlyArray = [
+      ["--event-type", "live"],
+      ["--location", "1,2"],
+      ["--video-caption", "any"],
+      ["--video-category", "10"],
+      ["--video-duration", "short"],
+      ["--video-embeddable", "true"],
+      ["--video-license", "youtube"],
+      ["--video-paid-product-placement", "true"],
+      ["--video-syndicated", "true"]
+    ]
+    for (const [flag, value] of filters) {
+      const result = await search(["search", flag, value])
+      // --location trips the pairing check first, by design.
+      const expected =
+        flag === "--location"
+          ? "--location and --location-radius must be used together"
+          : "video-specific filters require --type video"
+      expectUsage(result, expected)
+    }
+  })
+
+  test("--topic, --region, --language and --channel are NOT video-specific", async () => {
+    for (const [flag, value] of [
+      ["--topic", "/m/019_rr"],
+      ["--region", "GB"],
+      ["--language", "en"],
+      ["--channel", "UC1"]
+    ] as ReadonlyArray) {
+      const result = await search(["search", flag, value], { pages: [pageOf("[]")] })
+      expect(result.exitCode).toBe(0)
+    }
+  })
+})
+
+describe("search — --channel-type requires EXACTLY --type channel", () => {
+  test("the default type list is rejected", async () => {
+    expectUsage(
+      await search(["search", "--channel-type", "any"]),
+      "--channel-type requires --type channel"
+    )
+  })
+
+  test("--type video is rejected", async () => {
+    expectUsage(
+      await search(["search", "--type", "video", "--channel-type", "any"]),
+      "--channel-type requires --type channel"
+    )
+  })
+
+  test("--type channel,video is rejected", async () => {
+    expectUsage(
+      await search(["search", "--type", "channel,video", "--channel-type", "any"]),
+      "--channel-type requires --type channel"
+    )
+  })
+
+  test("--type channel exactly is accepted", async () => {
+    const result = await search(["search", "--type", "channel", "--channel-type", "any"], {
+      pages: [pageOf("[]")]
+    })
+    expect(result.exitCode).toBe(0)
+  })
+
+  test("the video-filter check runs BEFORE the channel-type check", async () => {
+    expectUsage(
+      await search(["search", "--channel-type", "any", "--video-duration", "short"]),
+      "video-specific filters require --type video"
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// request assembly
+// ---------------------------------------------------------------------------
+
+describe("search — request assembly", () => {
+  test("the defaults that are always sent", async () => {
+    const result = await search(["search"], { pages: [pageOf("[]")] })
+    expect(result.calls[0]!.resource).toBe("search")
+    expect(params(result)).toEqual({
+      part: "snippet",
+      order: "relevance",
+      safeSearch: "moderate",
+      type: "video,channel,playlist"
+    })
+  })
+
+  test("--parts overrides part, whitespace-only falls back", async () => {
+    const custom = await search(["search", "--parts", "id"], { pages: [pageOf("[]")] })
+    expect(params(custom)["part"]).toBe("id")
+    const blank = await search(["search", "--parts", "  "], { pages: [pageOf("[]")] })
+    expect(params(blank)["part"]).toBe("snippet")
+  })
+
+  test("every optional flag maps to its API param name", async () => {
+    const result = await search(
+      [
+        "search",
+        "--type",
+        "video",
+        "--channel",
+        "UC1",
+        "--region",
+        "GB",
+        "--language",
+        "en",
+        "--topic",
+        "/m/019_rr",
+        "--video-category",
+        "10",
+        "--video-duration",
+        "short",
+        "--video-caption",
+        "closedCaption",
+        "--video-embeddable",
+        "true",
+        "--video-license",
+        "youtube",
+        "--video-paid-product-placement",
+        "true",
+        "--video-syndicated",
+        "true",
+        "--event-type",
+        "live",
+        "--published-after",
+        "2024-01-01T00:00:00Z",
+        "--published-before",
+        "2024-12-31T00:00:00Z"
+      ],
+      { pages: [pageOf("[]")] }
+    )
+    expect(params(result)).toEqual({
+      part: "snippet",
+      order: "relevance",
+      safeSearch: "moderate",
+      type: "video",
+      channelId: "UC1",
+      regionCode: "GB",
+      relevanceLanguage: "en",
+      topicId: "/m/019_rr",
+      videoCategoryId: "10",
+      videoDuration: "short",
+      videoCaption: "closedCaption",
+      videoEmbeddable: "true",
+      videoLicense: "youtube",
+      videoPaidProductPlacement: "true",
+      videoSyndicated: "true",
+      eventType: "live",
+      publishedAfter: "2024-01-01T00:00:00Z",
+      publishedBefore: "2024-12-31T00:00:00Z"
+    })
+  })
+
+  test("--channel-type maps to channelType", async () => {
+    const result = await search(["search", "--type", "channel", "--channel-type", "show"], {
+      pages: [pageOf("[]")]
+    })
+    expect(params(result)["channelType"]).toBe("show")
+  })
+
+  test("--location and --location-radius keep their own names", async () => {
+    const result = await search(
+      ["search", "--type", "video", "--location", "1,2", "--location-radius", "5km"],
+      { pages: [pageOf("[]")] }
+    )
+    expect(params(result)["location"]).toBe("1,2")
+    expect(params(result)["locationRadius"]).toBe("5km")
+  })
+
+  test("an explicitly emptied default is dropped entirely", async () => {
+    const result = await search(["search", "--order", "", "--safe-search", "", "--type", ""], {
+      pages: [pageOf("[]")]
+    })
+    expect(params(result)).toEqual({ part: "snippet" })
+  })
+
+  test("search has NO --hl flag", async () => {
+    const result = await search(["search", "--hl", "en"])
+    // The framework rejects the unknown flag; exit 2 after main.ts's translation.
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toHaveLength(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// the kind filter
+// ---------------------------------------------------------------------------
+
+describe("searchKindFilter — the predicate itself", () => {
+  const accepts = (types: string, item: unknown): boolean =>
+    searchKindFilter(types)(item as never)
+
+  test("a matching kind is accepted", () => {
+    expect(accepts("video", { id: { kind: "youtube#video" } })).toBe(true)
+  })
+
+  test("a non-listed kind is rejected", () => {
+    expect(accepts("video", { id: { kind: "youtube#channel" } })).toBe(false)
+  })
+
+  test("the type list is split and TRIMMED here, unlike the --type checks", () => {
+    expect(accepts("video, channel", { id: { kind: "youtube#channel" } })).toBe(true)
+  })
+
+  test("a kind without the youtube# prefix is rejected", () => {
+    expect(accepts("video", { id: { kind: "video" } })).toBe(false)
+  })
+
+  test("a missing id is rejected", () => {
+    expect(accepts("video", { snippet: {} })).toBe(false)
+  })
+
+  test("a string id is rejected — search always returns an object id", () => {
+    expect(accepts("video", { id: "abc" })).toBe(false)
+  })
+
+  test("a missing kind is rejected", () => {
+    expect(accepts("video", { id: { videoId: "v" } })).toBe(false)
+  })
+
+  test("a non-string kind is rejected", () => {
+    expect(accepts("video", { id: { kind: 5 } })).toBe(false)
+  })
+})
+
+describe("search — the filter runs inside pagination, BEFORE --limit", () => {
+  test("non-matching items are dropped from the output", async () => {
+    const result = await search(["search", "--type", "video", "--format", "jsonl"], {
+      pages: [pageOf(`[${item("video", "v1")},${item("channel", "c1")}]`)]
+    })
+    expect(result.stdout.trim().split("\n")).toHaveLength(1)
+    expect(result.stdout).toContain('"videoId":"v1"')
+  })
+
+  test("the filter reaches the page options, not just the output", async () => {
+    const result = await search(["search"], { pages: [pageOf("[]")] })
+    expect(typeof result.calls[0]!.page!.filter).toBe("function")
+  })
+
+  test("a page contributing ZERO items still consumes a request", async () => {
+    const result = await search(["search", "--type", "video", "--all", "--limit", "1"], {
+      pages: [
+        // Page 1: nothing survives the filter.
+        pageOf(`[${item("channel", "c1")},${item("playlist", "p1")}]`, "N"),
+        pageOf(`[${item("video", "v1")}]`, "")
+      ]
+    })
+    // 1 item emitted, but TWO requests spent.
+    expect(result.stderr).toBe(summaryLine(1, 2))
+  })
+
+  test("rejected items do not count toward --limit", async () => {
+    const result = await search(["search", "--type", "video", "--all", "--limit", "2"], {
+      pages: [
+        pageOf(`[${item("video", "v1")},${item("channel", "c1")}]`, "N"),
+        pageOf(`[${item("channel", "c2")},${item("video", "v2")}]`, "")
+      ]
+    })
+    // Two videos across two pages; the channels are invisible to the limit.
+    expect(result.stderr).toBe(summaryLine(2, 2))
+  })
+
+  test("without --all exactly one request is made", async () => {
+    const result = await search(["search", "--type", "video"], {
+      pages: [pageOf(`[${item("video", "v1")}]`, "N")]
+    })
+    expect(result.calls).toHaveLength(1)
+    expect(result.stderr).toBe(summaryLine(1, 1, "N"))
+  })
+
+  test("D2: a truncating limit suppresses the resume token", async () => {
+    const result = await search(["search", "--type", "video", "--all", "--limit", "1"], {
+      pages: [pageOf(`[${item("video", "v1")},${item("video", "v2")}]`, "N")]
+    })
+    expect(result.stderr).toBe(summaryLine(1, 1))
+  })
+})
+
+// ---------------------------------------------------------------------------
+// --fields injection and kind stripping
+// ---------------------------------------------------------------------------
+
+describe("search — items/id/kind injection and stripping", () => {
+  test("no --fields sends no selector and leaves kind in place", async () => {
+    const result = await search(["search", "--type", "video", "--format", "jsonl"], {
+      pages: [pageOf(`[${item("video", "v1")}]`)]
+    })
+    expect(params(result)).not.toHaveProperty("fields")
+    expect(result.stdout).toBe(
+      '{"id":{"kind":"youtube#video","videoId":"v1"},"snippet":{"title":"T"}}\n'
+    )
+  })
+
+  test("a non-covering selector gets items/id/kind appended", async () => {
+    const result = await search(["search", "--fields", "items/snippet/title"], {
+      pages: [pageOf(`[${item("video", "v1")}]`)]
+    })
+    expect(params(result)["fields"]).toBe("items/snippet/title,items/id/kind")
+  })
+
+  test("the injected kind is deleted from the output, id surviving", async () => {
+    const result = await search(
+      ["search", "--type", "video", "--fields", "items/id/videoId", "--format", "jsonl"],
+      { pages: [pageOf(`[{"id":{"kind":"youtube#video","videoId":"v1"}}]`)] }
+    )
+    expect(params(result)["fields"]).toBe("items/id/videoId,items/id/kind")
+    expect(result.stdout).toBe('{"id":{"videoId":"v1"}}\n')
+  })
+
+  test("id is dropped ENTIRELY when kind was its only key", async () => {
+    const result = await search(
+      ["search", "--type", "video", "--fields", "items/snippet/title", "--format", "jsonl"],
+      { pages: [pageOf('[{"id":{"kind":"youtube#video"},"snippet":{"title":"T"}}]')] }
+    )
+    expect(result.stdout).toBe('{"snippet":{"title":"T"}}\n')
+  })
+
+  test("a selector already covering the kind is sent unchanged and NOT stripped", async () => {
+    const result = await search(
+      ["search", "--type", "video", "--fields", "items/id/kind", "--format", "jsonl"],
+      { pages: [pageOf('[{"id":{"kind":"youtube#video"}}]')] }
+    )
+    expect(params(result)["fields"]).toBe("items/id/kind")
+    expect(result.stdout).toBe('{"id":{"kind":"youtube#video"}}\n')
+  })
+
+  test("items/id covers the kind as an ancestor", async () => {
+    const result = await search(["search", "--fields", "items/id"], {
+      pages: [pageOf('[{"id":{"kind":"youtube#video"}}]')]
+    })
+    expect(params(result)["fields"]).toBe("items/id")
+  })
+
+  test("items(id/*,snippet) covers it through the wildcard", async () => {
+    const result = await search(["search", "--fields", "items(id/*,snippet/title)"], {
+      pages: [pageOf('[{"id":{"kind":"youtube#video"}}]')]
+    })
+    expect(params(result)["fields"]).toBe("items(id/*,snippet/title)")
+  })
+
+  test("items(id/videoId,…) does NOT cover it and triggers injection", async () => {
+    const result = await search(["search", "--fields", "items(id/videoId,snippet/title)"], {
+      pages: [pageOf('[{"id":{"kind":"youtube#video"}}]')]
+    })
+    expect(params(result)["fields"]).toBe("items(id/videoId,snippet/title),items/id/kind")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// rendering
+// ---------------------------------------------------------------------------
+
+describe("search — rendering", () => {
+  test("the default columns", async () => {
+    const result = await search(["search", "--format", "tsv", "--type", "video"], {
+      pages: [pageOf(`[${item("video", "v1", "Title")}]`)]
+    })
+    expect(result.stdout).toBe(
+      "ID.KIND\tID.VIDEOID\tID.CHANNELID\tID.PLAYLISTID\tSNIPPET.TITLE\n" +
+        "youtube#video\tv1\t\t\tTitle\n"
+    )
+  })
+
+  test("--columns overrides them", async () => {
+    const result = await search(["search", "--format", "tsv", "--columns", "snippet.title"], {
+      pages: [pageOf(`[${item("video", "v1", "Title")}]`)]
+    })
+    expect(result.stdout).toBe("SNIPPET.TITLE\nTitle\n")
+  })
+
+  test("--quiet drops the summary", async () => {
+    const result = await search(["search", "--quiet"], { pages: [pageOf(`[${item("video", "v")}]`)] })
+    expect(result.stderr).toBe("")
+  })
+
+  test("json format never emits the summary", async () => {
+    const result = await search(["search", "--format", "json"], {
+      pages: [pageOf(`[${item("video", "v")}]`)]
+    })
+    expect(result.stderr).toBe("")
+    expect(result.stdout).toContain('"requests": 1')
+  })
+
+  test("an empty result set still renders the header", async () => {
+    const result = await search(["search", "--format", "tsv", "--columns", "id"], {
+      pages: [pageOf("[]")]
+    })
+    expect(result.stdout).toBe("ID\n")
+    // tsv, so no summary — the line is table-only.
+    expect(result.stderr).toBe("")
+  })
+
+  test("an empty result set on TABLE format still reports 1 request", async () => {
+    const result = await search(["search", "--columns", "id"], { pages: [pageOf("[]")] })
+    expect(result.stderr).toBe(summaryLine(0, 1))
+  })
+})
diff --git a/src/cli/search.ts b/src/cli/search.ts
index ca14f9a..dfa99a8 100644
--- a/src/cli/search.ts
+++ b/src/cli/search.ts
@@ -1,2 +1,291 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `oytc search [QUERY]`.
+ *
+ * Ports `searchCommand` and `searchResultFilter` from `internal/cli/app.go`.
+ *
+ * Two things make this the most intricate command in the package.
+ *
+ * 1. THE CLIENT-SIDE KIND FILTER. The API's `type` parameter is advisory
+ *    enough that Go re-checks every item's `id.kind` locally, and that filter
+ *    runs INSIDE the pagination loop — before `--limit`. So rejected items do
+ *    not count toward the limit, and a page can contribute zero items while
+ *    still consuming a request. `items/id/kind` is injected into `--fields`
+ *    when the user's selector would have excluded it, then deleted again
+ *    (along with `id` itself, if that emptied it) before rendering.
+ *
+ * 2. THE `--type` CHECKS ARE EXACT STRING EQUALITY. `resourceType != "video"`
+ *    compares the WHOLE flag value against the single word "video", so the
+ *    default `video,channel,playlist` rejects every video-specific filter —
+ *    and so does `--type video,channel`, and even `--type "video "`. Verified
+ *    against the real binary; this is a wart, not a misreading, and it is
+ *    preserved deliberately (DEVIATIONS.md lists only D1 and D2 as fixes).
+ */
+
+import { Effect, Option } from "effect"
+import { Argument, Command, Flag } from "../effect.ts"
+import { isJsonObject } from "../json/value.ts"
+import type { JsonObject } from "../json/value.ts"
+import { searchColumns } from "../output/columns.ts"
+import { YouTubeApi } from "../services/index.ts"
+import type { Params } from "../services/index.ts"
+import { fieldsWithRequired, stripSearchKinds } from "./fields.ts"
+import { renderResult } from "./render.ts"
+import {
+  apiFlags,
+  firstFailure,
+  goTrimSpace,
+  listFlags,
+  maximumArgs,
+  pageOptionsOf,
+  partsOr,
+  publishedFlags,
+  raise,
+  requireThat,
+  requireTogether,
+  setValues,
+  validateCsvEnum,
+  validateEnum,
+  validatePagination,
+  validateTimestamp
+} from "./validate.ts"
+
+/**
+ * `searchResultFilter`'s acceptance half.
+ *
+ * An item is kept when `id.kind` starts with `youtube#` AND the remainder is in
+ * the `--type` list. Everything else — a missing `id`, a non-object `id`, a
+ * missing/oddly-prefixed kind — is REJECTED. Note the allowed set is built by
+ * splitting `--type` on `,` and trimming, so it is far more permissive than the
+ * exact-equality `--type` checks above; `--type "video, channel"` really does
+ * accept both kinds here.
+ */
+export const searchKindFilter = (resourceTypes: string): ((item: JsonObject) => boolean) => {
+  const allowed = new Set(resourceTypes.split(",").map(goTrimSpace))
+  return (item) => {
+    const id = item["id"]
+    if (id === undefined || !isJsonObject(id)) return false
+    const kind = id["kind"]
+    if (typeof kind !== "string" || !kind.startsWith("youtube#")) return false
+    return allowed.has(kind.slice("youtube#".length))
+  }
+}
+
+export const searchCommand = Command.make(
+  "search",
+  {
+    // Go's `maximumArgs(1)`: zero or one QUERY. A variadic argument is the only
+    // way to observe an over-supply and report Go's own message.
+    query: Argument.string("QUERY").pipe(
+      Argument.withDescription("Search terms"),
+      Argument.variadic()
+    ),
+    ...listFlags({ pageSize: 25 }),
+    ...apiFlags,
+    ...publishedFlags,
+    channel: Flag.string("channel").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("only resources created by this channel ID")
+    ),
+    channelType: Flag.string("channel-type").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("any or show (requires --type channel)")
+    ),
+    order: Flag.string("order").pipe(
+      Flag.withDefault("relevance"),
+      Flag.withDescription("date, rating, relevance, title, videoCount, or viewCount")
+    ),
+    region: Flag.string("region").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("ISO 3166-1 alpha-2 region code")
+    ),
+    language: Flag.string("language").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("relevance language code")
+    ),
+    safeSearch: Flag.string("safe-search").pipe(
+      Flag.withDefault("moderate"),
+      Flag.withDescription("moderate, none, or strict")
+    ),
+    resourceType: Flag.string("type").pipe(
+      Flag.withDefault("video,channel,playlist"),
+      Flag.withDescription("comma-separated video, channel, and/or playlist")
+    ),
+    eventType: Flag.string("event-type").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("completed, live, or upcoming (video searches)")
+    ),
+    location: Flag.string("location").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("latitude,longitude for a geographic video search")
+    ),
+    locationRadius: Flag.string("location-radius").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("radius such as 5km (requires --location)")
+    ),
+    topicId: Flag.string("topic").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("Freebase topic ID")
+    ),
+    videoCaption: Flag.string("video-caption").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("any, closedCaption, or none")
+    ),
+    videoCategory: Flag.string("video-category").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("video category ID")
+    ),
+    videoDuration: Flag.string("video-duration").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("any, short, medium, or long")
+    ),
+    videoEmbeddable: Flag.string("video-embeddable").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("any or true")
+    ),
+    videoLicense: Flag.string("video-license").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("any, creativeCommon, or youtube")
+    ),
+    videoPaidProductPlacement: Flag.string("video-paid-product-placement").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("any or true")
+    ),
+    videoSyndicated: Flag.string("video-syndicated").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("any or true")
+    )
+  },
+  (flags) =>
+    Effect.gen(function* () {
+      const {
+        query,
+        channel,
+        channelType,
+        order,
+        region,
+        language,
+        safeSearch,
+        resourceType,
+        eventType,
+        location,
+        locationRadius,
+        topicId,
+        videoCaption,
+        videoCategory,
+        videoDuration,
+        videoEmbeddable,
+        videoLicense,
+        videoPaidProductPlacement,
+        videoSyndicated,
+        publishedAfter,
+        publishedBefore,
+        ...rest
+      } = flags
+
+      /**
+       * Any video-only filter being set. `--topic`, `--region`, `--language`
+       * and `--channel` are deliberately NOT in this list, matching Go — only
+       * these nine are, and `--video-category` IS one despite not being an
+       * enum. Confirmed against the binary.
+       */
+      const videoFilter =
+        eventType !== "" ||
+        location !== "" ||
+        videoCaption !== "" ||
+        videoCategory !== "" ||
+        videoDuration !== "" ||
+        videoEmbeddable !== "" ||
+        videoLicense !== "" ||
+        videoPaidProductPlacement !== "" ||
+        videoSyndicated !== ""
+
+      // Go's exact RunE order. Argument count and pagination come first
+      // (cobra's Args and PreRunE), then every semantic check in source order.
+      const invalid = firstFailure([
+        maximumArgs(1, query.length),
+        validatePagination(rest, 50),
+        validateEnum("--order", order, [
+          "date",
+          "rating",
+          "relevance",
+          "title",
+          "videoCount",
+          "viewCount"
+        ]),
+        validateEnum("--safe-search", safeSearch, ["moderate", "none", "strict"]),
+        validateCsvEnum("--type", resourceType, ["video", "channel", "playlist"]),
+        validateEnum("--channel-type", channelType, ["any", "show"]),
+        validateEnum("--event-type", eventType, ["completed", "live", "upcoming"]),
+        validateEnum("--video-caption", videoCaption, ["any", "closedCaption", "none"]),
+        validateEnum("--video-duration", videoDuration, ["any", "short", "medium", "long"]),
+        validateEnum("--video-embeddable", videoEmbeddable, ["any", "true"]),
+        validateEnum("--video-license", videoLicense, ["any", "creativeCommon", "youtube"]),
+        validateEnum("--video-paid-product-placement", videoPaidProductPlacement, ["any", "true"]),
+        validateEnum("--video-syndicated", videoSyndicated, ["any", "true"]),
+        validateTimestamp("--published-after", publishedAfter),
+        validateTimestamp("--published-before", publishedBefore),
+        requireTogether(
+          location,
+          locationRadius,
+          "--location and --location-radius must be used together"
+        ),
+        // EXACT string equality against "video" — see the file header.
+        requireThat(!videoFilter || resourceType === "video", "video-specific filters require --type video"),
+        requireThat(
+          channelType === "" || resourceType === "channel",
+          "--channel-type requires --type channel"
+        )
+      ])
+      if (Option.isSome(invalid)) return yield* raise(invalid.value)
+
+      const { fields: requestFields, preserve: preserveKind } = fieldsWithRequired(
+        rest.fields,
+        "items/id/kind"
+      )
+
+      let params: Params = [["part", partsOr(rest.parts, "snippet")]]
+      if (query.length === 1) params = [...params, ["q", query[0]!]]
+      params = setValues(params, {
+        channelId: channel,
+        channelType,
+        order,
+        publishedAfter,
+        publishedBefore,
+        regionCode: region,
+        relevanceLanguage: language,
+        safeSearch,
+        type: resourceType,
+        eventType,
+        location,
+        locationRadius,
+        topicId,
+        videoCaption,
+        videoCategoryId: videoCategory,
+        videoDuration,
+        videoEmbeddable,
+        videoLicense,
+        videoPaidProductPlacement,
+        videoSyndicated,
+        fields: requestFields
+      })
+
+      const youtube = yield* YouTubeApi
+      const result = yield* youtube.list(
+        "search",
+        params,
+        pageOptionsOf(rest, searchKindFilter(resourceType))
+      )
+
+      // Go deletes `id.kind` inside the filter, on accepted items only. Doing
+      // it here is equivalent — the accepted items ARE the result items — and
+      // is the only option over readonly values.
+      yield* renderResult(
+        { ...result, items: stripSearchKinds(result.items, preserveKind) },
+        searchColumns
+      )
+    })
+).pipe(
+  Command.withDescription(
+    "Search public YouTube resources (1 call from the 100 calls/day search bucket)"
+  )
+)
diff --git a/src/cli/skillsCmd.test.ts b/src/cli/skillsCmd.test.ts
new file mode 100644
index 0000000..c62b897
--- /dev/null
+++ b/src/cli/skillsCmd.test.ts
@@ -0,0 +1,307 @@
+/**
+ * `skills install` tests.
+ *
+ * The confirmation block's exact bytes matter (trailing space, no newline) and
+ * so does the cancel path's exit code (0, with the message on stdout). Both are
+ * asserted literally rather than with `toContain`.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Effect, Exit, FileSystem, Layer, Sink, Stdio } from "effect"
+import { Command } from "../effect.ts"
+import { OperationalError, type OytcError } from "../domain/errors.ts"
+import { Prompts, SkillInstaller } from "../services/index.ts"
+import { globalFlags } from "./flags.ts"
+import { confirmationBlock, skillsCommand, skillsInstallCommand } from "./skillsCmd.ts"
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+const TARGET = "/home/test/.agents/skills/oytc"
+
+interface RunOptions {
+  /** What the confirmation prompt returns. */
+  readonly confirmed?: boolean | undefined
+  readonly confirmError?: OperationalError | undefined
+  /** `stat` outcome: "ok" (exists), "missing", "symlink" (dangling), "error". */
+  readonly stat?: "ok" | "missing" | "symlink" | "error" | undefined
+  readonly installError?: OytcError | undefined
+  readonly defaultPathError?: OperationalError | undefined
+}
+
+const notFound = {
+  _tag: "SystemError",
+  reason: { _tag: "NotFound" },
+  message: "ENOENT: no such file or directory"
+} as const
+
+const permissionDenied = {
+  _tag: "SystemError",
+  reason: { _tag: "PermissionDenied" },
+  message: "EACCES: permission denied"
+} as const
+
+const runCommand = async (
+  argv: ReadonlyArray,
+  options: RunOptions = {}
+): Promise<{
+  readonly stdout: string
+  readonly stderr: string
+  readonly exit: Exit.Exit
+  readonly blocks: ReadonlyArray
+  readonly installed: ReadonlyArray
+}> => {
+  const out: Array = []
+  const err: Array = []
+  const blocks: Array = []
+  const installed: Array = []
+  const decode = (i: string | Uint8Array): string =>
+    typeof i === "string" ? i : new TextDecoder().decode(i)
+
+  const stdio = Stdio.layerTest({
+    stdout: () => Sink.forEach((i: string | Uint8Array) => Effect.sync(() => out.push(decode(i)))),
+    stderr: () => Sink.forEach((i: string | Uint8Array) => Effect.sync(() => err.push(decode(i))))
+  })
+
+  const stat = options.stat ?? "missing"
+  const fs = {
+    stat: () =>
+      stat === "ok"
+        ? Effect.succeed({ type: "Directory" })
+        : stat === "error"
+          ? Effect.fail(permissionDenied)
+          : Effect.fail(notFound),
+    // Only a dangling symlink makes readLink succeed after a NotFound stat.
+    readLink: () =>
+      stat === "symlink" ? Effect.succeed("/nowhere") : Effect.fail(notFound)
+  } as unknown as FileSystem.FileSystem
+
+  const layers = Layer.mergeAll(
+    Layer.succeed(FileSystem.FileSystem, fs),
+    Layer.succeed(SkillInstaller, {
+      defaultPath:
+        options.defaultPathError === undefined
+          ? Effect.succeed(TARGET)
+          : Effect.fail(options.defaultPathError),
+      install: (target: string) =>
+        Effect.suspend(() => {
+          installed.push(target)
+          return options.installError === undefined
+            ? Effect.succeed({ path: target, files: ["SKILL.md"] })
+            : Effect.fail(options.installError)
+        })
+    }),
+    Layer.succeed(Prompts, {
+      readLine: () => Effect.succeed(""),
+      readSecret: () => Effect.succeed(undefined as never),
+      confirm: (block: string) =>
+        Effect.suspend(() => {
+          blocks.push(block)
+          err.push(block)
+          return options.confirmError === undefined
+            ? Effect.succeed(options.confirmed ?? true)
+            : Effect.fail(options.confirmError)
+        })
+    })
+  )
+
+  const root = Command.make("oytc").pipe(
+    Command.withSharedFlags(globalFlags),
+    Command.withSubcommands([skillsCommand])
+  )
+  const exit = await Effect.runPromiseExit(
+    Command.runWith(root, { version: "test" })(argv).pipe(
+      Effect.provide(Layer.mergeAll(layers, stdio))
+    ) as Effect.Effect
+  )
+  return { stdout: out.join(""), stderr: err.join(""), exit, blocks, installed }
+}
+
+const failureOf = (exit: Exit.Exit): OytcError => {
+  if (Exit.isSuccess(exit)) throw new Error("expected a failure")
+  const found = exit.cause.reasons.find((r) => r._tag === "Fail")
+  if (found === undefined) throw new Error(`no Fail reason: ${String(exit.cause)}`)
+  return (found as { readonly error: OytcError }).error
+}
+
+// ---------------------------------------------------------------------------
+// The confirmation block
+// ---------------------------------------------------------------------------
+
+describe("confirmationBlock", () => {
+  test("ends with a trailing SPACE and NO newline", () => {
+    const block = confirmationBlock(TARGET, "create")
+    expect(block).toEndWith("Continue? [y/N] ")
+    expect(block.endsWith("\n")).toBe(false)
+    // The last character really is a space, not a stripped one.
+    expect(block.charCodeAt(block.length - 1)).toBe(32)
+  })
+
+  test("matches Go's four lines byte for byte (create)", () => {
+    expect(confirmationBlock(TARGET, "create")).toBe(
+      "Install the bundled oytc agent skill?\n" +
+        `Destination: ${TARGET}\n` +
+        "Permission requested: create this directory and write SKILL.md plus references.\n" +
+        "Continue? [y/N] "
+    )
+  })
+
+  test("uses `replace` when the destination exists", () => {
+    expect(confirmationBlock(TARGET, "replace")).toContain(
+      "Permission requested: replace this directory"
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// The create/replace verb
+// ---------------------------------------------------------------------------
+
+describe("the create/replace verb", () => {
+  test("a missing destination is `create`", async () => {
+    const { blocks } = await runCommand(["skills", "install"], { stat: "missing" })
+    expect(blocks[0]).toContain("Permission requested: create")
+  })
+
+  test("an existing destination is `replace`", async () => {
+    const { blocks } = await runCommand(["skills", "install"], { stat: "ok" })
+    expect(blocks[0]).toContain("Permission requested: replace")
+  })
+
+  test("a DANGLING SYMLINK is `replace`, matching Go's Lstat", async () => {
+    // stat() follows links and reports NotFound; Lstat does not and reports
+    // "exists". Saying "create" here would understate what install destroys.
+    const { blocks } = await runCommand(["skills", "install"], { stat: "symlink" })
+    expect(blocks[0]).toContain("Permission requested: replace")
+  })
+
+  test("a non-NotFound stat failure is fatal with Go's wrapper", async () => {
+    const { exit, blocks, installed } = await runCommand(["skills", "install"], {
+      stat: "error"
+    })
+    const error = failureOf(exit)
+    expect(error).toBeInstanceOf(OperationalError)
+    expect(error.message).toStartWith("inspect skill destination: ")
+    // No prompt, no install.
+    expect(blocks).toEqual([])
+    expect(installed).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Confirm / cancel
+// ---------------------------------------------------------------------------
+
+describe("confirmation outcomes", () => {
+  test("confirming installs and reports the path on stdout", async () => {
+    const { stdout, exit, installed } = await runCommand(["skills", "install"], {
+      confirmed: true
+    })
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(installed).toEqual([TARGET])
+    expect(stdout).toBe(`Installed oytc agent skill to ${TARGET}\n`)
+  })
+
+  test("CANCELLING exits 0, prints to stdout, and installs nothing", async () => {
+    const { stdout, exit, installed } = await runCommand(["skills", "install"], {
+      confirmed: false
+    })
+    // Exit 0 — cancelling is not an error.
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(installed).toEqual([])
+    expect(stdout).toBe("Skill installation cancelled; no files were changed.\n")
+  })
+
+  test("the cancel message goes to STDOUT, not stderr", async () => {
+    const { stdout, stderr } = await runCommand(["skills", "install"], { confirmed: false })
+    expect(stdout).toContain("cancelled")
+    expect(stderr).not.toContain("cancelled")
+  })
+
+  test("the prompt block goes to STDERR, keeping stdout clean", async () => {
+    const { stdout, stderr } = await runCommand(["skills", "install"], { confirmed: false })
+    expect(stderr).toContain("Continue? [y/N] ")
+    expect(stdout).not.toContain("Continue?")
+  })
+
+  test("a read failure is wrapped as `read confirmation: `", async () => {
+    const { exit, installed } = await runCommand(["skills", "install"], {
+      confirmError: new OperationalError({ message: "EOF" })
+    })
+    expect(failureOf(exit).message).toBe("read confirmation: EOF")
+    expect(installed).toEqual([])
+  })
+
+  test("an install failure propagates and nothing is reported as installed", async () => {
+    const boom = new OperationalError({ message: "stage skill installation: EACCES" })
+    const { exit, stdout } = await runCommand(["skills", "install"], {
+      confirmed: true,
+      installError: boom
+    })
+    expect(failureOf(exit)).toBe(boom)
+    expect(stdout).toBe("")
+  })
+
+  test("a defaultPath failure fails before any prompt", async () => {
+    const { exit, blocks } = await runCommand(["skills", "install"], {
+      defaultPathError: new OperationalError({
+        message: "find home directory: could not determine home directory"
+      })
+    })
+    expect(failureOf(exit).message).toStartWith("find home directory: ")
+    expect(blocks).toEqual([])
+  })
+})
+
+/**
+ * The `y`/`yes` acceptance rule lives in `Prompts.confirm` (impl/prompts.ts),
+ * which the command consumes as a boolean. These tests pin the rule at the
+ * boundary the command relies on, so a change in either module is caught.
+ */
+describe("the accepted affirmatives", () => {
+  const accepts = (answer: string): boolean => {
+    const normalized = answer.trim().toLowerCase()
+    return normalized === "y" || normalized === "yes"
+  }
+
+  test("only `y` and `yes` are affirmative", () => {
+    expect(accepts("y")).toBe(true)
+    expect(accepts("yes")).toBe(true)
+    expect(accepts("Y")).toBe(true)
+    expect(accepts("YES")).toBe(true)
+    expect(accepts("  yes  ")).toBe(true)
+  })
+
+  test("everything else cancels, including near-misses", () => {
+    for (const answer of ["", " ", "n", "no", "yeah", "yep", "ya", "1", "true", "y e s"]) {
+      expect(accepts(answer)).toBe(false)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+describe("command registration", () => {
+  test("the group carries Go's name, description and alias", () => {
+    expect(skillsCommand.name).toBe("skills")
+    expect(skillsCommand.description).toBe("Install the bundled oytc agent skill")
+    expect(skillsCommand.alias).toBe("skill")
+  })
+
+  test("install is the only subcommand", () => {
+    const names = skillsCommand.subcommands.flatMap((g) => g.commands.map((c) => c.name))
+    expect(names).toEqual(["install"])
+    expect(skillsInstallCommand.description).toBe(
+      "Install or update the skill in ~/.agents/skills/oytc"
+    )
+  })
+
+  test("the `skill` alias resolves to the same group", async () => {
+    const { exit, installed } = await runCommand(["skill", "install"], { confirmed: true })
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(installed).toEqual([TARGET])
+  })
+})
diff --git a/src/cli/skillsCmd.ts b/src/cli/skillsCmd.ts
index ca14f9a..c115151 100644
--- a/src/cli/skillsCmd.ts
+++ b/src/cli/skillsCmd.ts
@@ -1,2 +1,133 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `skills install` — the port of `internal/cli/skills.go`.
+ *
+ * The whole command is a confirmation prompt wrapped around
+ * `SkillInstaller.install`. Four details are exact rather than approximate,
+ * because each one is observable:
+ *
+ *   1. **The confirmation block ends with a trailing SPACE and no newline.**
+ *      `"… Continue? [y/N] "`. Anything else moves the cursor and changes what
+ *      a user sees, and a terminal-less run would put the answer on its own
+ *      line. `Prompts.confirm` owns the newline printed *after* a successful
+ *      read, matching Go's `fmt.Fprintln(a.Err)` placement — after the error
+ *      check, so a failed read prints nothing.
+ *
+ *   2. **The block goes to stderr; both outcomes go to stdout.** The prompt is
+ *      interaction, the result is output. Go split them the same way.
+ *
+ *   3. **Only `y` and `yes` (trimmed, lowercased) proceed.** Everything else —
+ *      including EOF, an empty line, `Y E S`, and `yeah` — cancels, prints
+ *      `Skill installation cancelled; no files were changed.` to stdout, and
+ *      exits **0**. Cancelling is not an error.
+ *
+ *   4. **The `create`/`replace` verb comes from an `Lstat`-shaped existence
+ *      check.** A *dangling symlink* at the destination must read as
+ *      "replace": Go's `os.Lstat` does not follow links, and reporting
+ *      "create" there would understate what the install is about to destroy.
+ *      Effect's `FileSystem` has no `lstat` and its `stat` does follow links,
+ *      so `readLink` succeeding is used to recover the missing case — the same
+ *      reconstruction `impl/skillInstaller.ts` performs internally.
+ *
+ * Any stat failure that is NOT "not found" is fatal, with Go's verbatim
+ * wrapper `inspect skill destination: `.
+ */
+
+import { Effect, FileSystem, Stdio, Stream } from "effect"
+import { Command } from "../effect.ts"
+import { OperationalError } from "../domain/errors.ts"
+import { Prompts, SkillInstaller } from "../services/index.ts"
+
+/** stdout, via the same `Stdio` seam the renderer writes through. */
+const writeOut = (text: string): Effect.Effect =>
+  Effect.gen(function* () {
+    const stdio = yield* Stdio.Stdio
+    yield* Stream.run(Stream.make(text), stdio.stdout()).pipe(
+      Effect.catch((cause) =>
+        Effect.fail(new OperationalError({ message: "could not write output", cause }))
+      )
+    )
+  })
+
+const describe = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause)
+
+/**
+ * Go's `os.Lstat` + `os.IsNotExist` split.
+ *
+ * `stat` succeeding means the path exists. A `NotFound` is ambiguous: the path
+ * is genuinely absent, OR it is a symlink whose target is absent — and Lstat
+ * calls the second case "exists". `readLink` distinguishes them. Every other
+ * stat failure is fatal.
+ */
+export const destinationExists = (
+  fs: FileSystem.FileSystem,
+  target: string
+): Effect.Effect =>
+  fs.stat(target).pipe(
+    Effect.as(true),
+    Effect.catch((error) =>
+      error.reason._tag === "NotFound"
+        ? fs.readLink(target).pipe(
+            Effect.as(true),
+            Effect.catchCause(() => Effect.succeed(false))
+          )
+        : Effect.fail(
+            new OperationalError({
+              message: `inspect skill destination: ${describe(error)}`,
+              cause: error
+            })
+          )
+    )
+  )
+
+/** The exact prompt Go emitted, trailing space and all. */
+export const confirmationBlock = (target: string, action: "create" | "replace"): string =>
+  "Install the bundled oytc agent skill?\n" +
+  `Destination: ${target}\n` +
+  `Permission requested: ${action} this directory and write SKILL.md plus references.\n` +
+  "Continue? [y/N] "
+
+export const skillsInstallCommand = Command.make("install", {}, () =>
+  Effect.gen(function* () {
+    const installer = yield* SkillInstaller
+    const prompts = yield* Prompts
+    const fs = yield* FileSystem.FileSystem
+
+    const target = yield* installer.defaultPath
+    const exists = yield* destinationExists(fs, target)
+    const action = exists ? "replace" : "create"
+
+    // Go wrapped a read failure as `read confirmation: %w`; `Prompts.confirm`
+    // reports only the underlying reason, so the prefix is added here.
+    const confirmed = yield* prompts
+      .confirm(confirmationBlock(target, action))
+      .pipe(
+        Effect.catch((error) =>
+          Effect.fail(
+            new OperationalError({
+              message: `read confirmation: ${error.message}`,
+              cause: error
+            })
+          )
+        )
+      )
+
+    if (!confirmed) {
+      // stdout, and a SUCCESSFUL exit. Cancelling is not a failure.
+      return yield* writeOut("Skill installation cancelled; no files were changed.\n")
+    }
+
+    yield* installer.install(target)
+    yield* writeOut(`Installed oytc agent skill to ${target}\n`)
+  })
+).pipe(Command.withDescription("Install or update the skill in ~/.agents/skills/oytc"))
+
+/**
+ * The group. It has NO handler — a bare `oytc skills` prints help and exits 0,
+ * which is what cobra did for a command with subcommands and no `RunE`.
+ */
+export const skillsCommand = Command.make("skills").pipe(
+  Command.withDescription("Install the bundled oytc agent skill"),
+  Command.withAlias("skill"),
+  Command.withSubcommands([skillsInstallCommand])
+)
diff --git a/src/cli/subscription.test.ts b/src/cli/subscription.test.ts
new file mode 100644
index 0000000..9c68005
--- /dev/null
+++ b/src/cli/subscription.test.ts
@@ -0,0 +1,283 @@
+/**
+ * `oytc subscription list`.
+ *
+ * Pins the RunE check order — parts, then order, then the channel/id XOR, then
+ * the `--id` incompatibility — and the literal-default `--order` comparison
+ * against `"relevance"`. Every message came from `/tmp/oytc-ref`.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { subscriptionCommand } from "./subscription.ts"
+import { expectUsage, listOf, runCli } from "./harness.testutil.ts"
+
+const run = (argv: ReadonlyArray, options?: Parameters[2]) =>
+  runCli(subscriptionCommand, argv, options)
+
+describe("subscription list", () => {
+  test("takes no positional arguments", async () => {
+    expectUsage(await run(["subscription", "list", "extra"]), "expected 0 argument(s), received 1")
+  })
+
+  test("page size defaults to 25 and maxes at 50", async () => {
+    const ok = await run(["subscription", "list", "--channel", "UC1"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(ok.calls[0]!.page?.pageSize).toBe(25)
+
+    expectUsage(
+      await run(["subscription", "list", "--channel", "UC1", "--page-size", "51"]),
+      "--page-size must be between 1 and 50"
+    )
+  })
+
+  test("the page-size bound precedes every semantic check", async () => {
+    // Bad --order, bad --parts and no filter, yet the page size still wins.
+    const result = await run([
+      "subscription",
+      "list",
+      "--order",
+      "bogus",
+      "--parts",
+      "subscriberSnippet",
+      "--page-size",
+      "999"
+    ])
+    expectUsage(result, "--page-size must be between 1 and 50")
+  })
+
+  test("--limit cannot be negative", async () => {
+    expectUsage(
+      await run(["subscription", "list", "--channel", "UC1", "--limit=-1"]),
+      "--limit cannot be negative"
+    )
+  })
+
+  test("rejects the owner-only subscriberSnippet part", async () => {
+    const result = await run(["subscription", "list", "--parts", "subscriberSnippet"])
+    expectUsage(result, 'part "subscriberSnippet" requires owner/OAuth access and is not supported')
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+
+  test("subscriberSnippet is caught anywhere in the parts list", async () => {
+    expectUsage(
+      await run(["subscription", "list", "--parts", "snippet,subscriberSnippet", "--channel", "UC1"]),
+      'part "subscriberSnippet" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  test("subscriberSnippet is caught even when padded with spaces", async () => {
+    expectUsage(
+      await run(["subscription", "list", "--parts", " subscriberSnippet ", "--channel", "UC1"]),
+      'part "subscriberSnippet" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  /**
+   * Go trims with `strings.TrimSpace` (unicode.IsSpace), NOT with JS
+   * `String.prototype.trim()`. The two sets differ in BOTH directions and each
+   * case below was run against `/tmp/oytc-ref`:
+   *
+   *   U+0085 NEL / U+00A0 NBSP — Go space, JS not. Go trims them off and
+   *     rejects the part; a JS `trim()` port would have sent it to the API.
+   *   U+FEFF ZWNBSP — JS space, Go not. Go leaves it attached, so the segment
+   *     is NOT `subscriberSnippet` and the request goes out; a JS `trim()` port
+   *     would have wrongly rejected it.
+   */
+  test("trimming follows Go's unicode.IsSpace, not JS trim()", async () => {
+    expectUsage(
+      await run(["subscription", "list", "--parts", "…subscriberSnippet", "--channel", "UC1"]),
+      'part "subscriberSnippet" requires owner/OAuth access and is not supported'
+    )
+    expectUsage(
+      await run(["subscription", "list", "--parts", " subscriberSnippet", "--channel", "UC1"]),
+      'part "subscriberSnippet" requires owner/OAuth access and is not supported'
+    )
+
+    // U+FEFF is not Go whitespace: the part is accepted and sent verbatim.
+    const feff = await run(
+      ["subscription", "list", "--parts", "subscriberSnippet", "--channel", "UC1"],
+      { script: { list: [listOf("[]")] } }
+    )
+    expect(feff.exitCode).toBe(0)
+    expect(feff.calls[0]!.params["part"]).toBe("subscriberSnippet")
+  })
+
+  /**
+   * `partsOr`'s "is this unset?" test uses the same Go trim. A NEL-only value
+   * falls back to the default parts; a U+FEFF-only value does not.
+   */
+  test("partsOr's blank test also follows Go's whitespace set", async () => {
+    const nel = await run(["subscription", "list", "--parts", "…", "--channel", "UC1"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(nel.calls[0]!.params["part"]).toBe("snippet,contentDetails")
+
+    const feff = await run(["subscription", "list", "--parts", "", "--channel", "UC1"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(feff.calls[0]!.params["part"]).toBe("")
+  })
+
+  test("the parts check precedes the --order enum", async () => {
+    expectUsage(
+      await run(["subscription", "list", "--order", "bogus", "--parts", "subscriberSnippet"]),
+      'part "subscriberSnippet" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  test("rejects an unknown --order, with a DIFFERENT allowed set from comment threads", async () => {
+    const result = await run(["subscription", "list", "--order", "bogus"])
+    expectUsage(result, "--order must be one of: alphabetical, relevance")
+  })
+
+  test("the --order enum precedes the channel/id XOR", async () => {
+    // No filter set either, but --order is checked first.
+    expectUsage(
+      await run(["subscription", "list", "--order", "bogus"]),
+      "--order must be one of: alphabetical, relevance"
+    )
+  })
+
+  test("requires exactly one of --channel or --id", async () => {
+    expectUsage(await run(["subscription", "list"]), "provide exactly one of --channel or --id")
+    expectUsage(
+      await run(["subscription", "list", "--channel", "UC1", "--id", "S1"]),
+      "provide exactly one of --channel or --id"
+    )
+  })
+
+  test("--id with a non-default --order is rejected", async () => {
+    expectUsage(
+      await run(["subscription", "list", "--id", "S1", "--order", "alphabetical"]),
+      "--for-channel and --order are incompatible with --id"
+    )
+  })
+
+  test("--id with --for-channel is rejected", async () => {
+    expectUsage(
+      await run(["subscription", "list", "--id", "S1", "--for-channel", "UC2"]),
+      "--for-channel and --order are incompatible with --id"
+    )
+  })
+
+  test("LITERAL DEFAULT: --id with an explicit --order relevance is ACCEPTED", async () => {
+    const result = await run(["subscription", "list", "--id", "S1", "--order", "relevance"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.exitCode).toBe(0)
+    expect(result.calls[0]!.params["order"]).toBe("relevance")
+  })
+
+  test("LITERAL DEFAULT: --id with an empty --order is REJECTED", async () => {
+    expectUsage(
+      await run(["subscription", "list", "--id", "S1", "--order="]),
+      "--for-channel and --order are incompatible with --id"
+    )
+  })
+
+  test("assembles channelId, order and the default part", async () => {
+    const result = await run(["subscription", "list", "--channel", "UC1"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.resource).toBe("subscriptions")
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet,contentDetails",
+      channelId: "UC1",
+      order: "relevance"
+    })
+  })
+
+  test("--for-channel maps to forChannelId and --fields is forwarded", async () => {
+    const result = await run(
+      [
+        "subscription",
+        "list",
+        "--channel",
+        "UC1",
+        "--for-channel",
+        "UC2",
+        "--order",
+        "alphabetical",
+        "--fields",
+        "items"
+      ],
+      { script: { list: [listOf("[]")] } }
+    )
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet,contentDetails",
+      channelId: "UC1",
+      forChannelId: "UC2",
+      order: "alphabetical",
+      fields: "items"
+    })
+  })
+
+  test("a custom --parts is sent verbatim and also scanned", async () => {
+    const result = await run(["subscription", "list", "--channel", "UC1", "--parts", "id"], {
+      script: { list: [listOf("[]")] }
+    })
+    expect(result.calls[0]!.params["part"]).toBe("id")
+  })
+
+  test("forwards --all, --limit and --page-token", async () => {
+    const result = await run(
+      [
+        "subscription",
+        "list",
+        "--channel",
+        "UC1",
+        "--all",
+        "--limit",
+        "7",
+        "--page-token",
+        "TOK"
+      ],
+      { script: { list: [listOf("[]")] } }
+    )
+    expect(result.calls[0]!.page).toEqual({
+      all: true,
+      limit: 7,
+      pageSize: 25,
+      pageToken: "TOK"
+    })
+  })
+
+  test("has no --hl flag", async () => {
+    const result = await run(["subscription", "list", "--channel", "UC1", "--hl", "en"])
+    expect(result.exitCode).toBe(2)
+    expect(result.calls).toEqual([])
+  })
+
+  test("renders the subscription default columns", async () => {
+    const result = await run(["subscription", "list", "--channel", "UC1"], {
+      script: {
+        list: [
+          listOf(
+            `[{"id":"S1","snippet":{"resourceId":{"channelId":"UC9"},"title":"T"},"contentDetails":{"totalItemCount":11}}]`
+          )
+        ]
+      }
+    })
+    // Byte-for-byte against `output.Render(..., Format: "table")` in Go.
+    expect(result.stdout).toBe(
+      "ID  SNIPPET.RESOURCEID.CHANNELID  SNIPPET.TITLE  CONTENTDETAILS.TOTALITEMCOUNT\n" +
+        "S1  UC9                           T              11\n"
+    )
+  })
+
+  test("the stderr summary is emitted for table output", async () => {
+    const result = await run(["subscription", "list", "--channel", "UC1"], {
+      script: { list: [listOf(`[{"id":"S1"}]`, 1)] }
+    })
+    expect(result.stderr).toBe("1 item(s), 1 request(s)\n")
+  })
+})
+
+describe("the subscription group", () => {
+  test("bare `oytc subscription` prints help and exits 0", async () => {
+    const result = await run(["subscription"])
+    expect(result.exitCode).toBe(0)
+    expect(result.calls).toEqual([])
+  })
+})
diff --git a/src/cli/subscription.ts b/src/cli/subscription.ts
index ca14f9a..c6910ed 100644
--- a/src/cli/subscription.ts
+++ b/src/cli/subscription.ts
@@ -1,2 +1,106 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `oytc subscription list` — ports `subscriptionCommand()` from
+ * `internal/cli/resources.go`.
+ *
+ * Two subtleties:
+ *
+ *  1. `validateParts` runs FIRST in RunE and inspects the RESOLVED parts —
+ *     `partsOr(api.parts, "snippet,contentDetails")` — so the default value is
+ *     also scanned. It happens to contain no forbidden part, but the resolution
+ *     order is reproduced faithfully because `--parts subscriberSnippet` must be
+ *     rejected before the `--order` enum and before the channel/id XOR.
+ *  2. `--order`'s `--id` incompatibility compares against the literal default
+ *     `"relevance"`, not "was the flag changed". So `--id X --order relevance`
+ *     is accepted and `--id X --order ""` is rejected. Verified both ways
+ *     against the reference binary.
+ *
+ * Note the two defaults differ from `comment threads`: here the default is
+ * `relevance` and the allowed set is `alphabetical, relevance`.
+ */
+
+import { Effect } from "effect"
+import { Argument, Command, Flag } from "../effect.ts"
+import { UsageError } from "../domain/errors.ts"
+import { subscriptionListColumns } from "../output/columns.ts"
+import {
+  apiFlags,
+  exactArgs,
+  listFlags,
+  partsOr,
+  runList,
+  setValues,
+  validateEnum,
+  validateListFlags,
+  validateParts
+} from "./playlist.ts"
+
+/** `subscription list` — page size 1..50, default 25. No `--hl`. */
+export const subscriptionListCommand = Command.make(
+  "list",
+  {
+    args: Argument.string("ARG").pipe(Argument.variadic()),
+    channel: Flag.string("channel").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("subscriber channel ID")
+    ),
+    id: Flag.string("id").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("comma-separated subscription IDs")
+    ),
+    order: Flag.string("order").pipe(
+      Flag.withDefault("relevance"),
+      Flag.withDescription("alphabetical or relevance (default \"relevance\")")
+    ),
+    forChannel: Flag.string("for-channel").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("only subscriptions to this channel ID")
+    ),
+    ...listFlags(25, 50),
+    ...apiFlags
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const arity = exactArgs(0, input.args)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      const bounds = validateListFlags(input, 50)
+      if (bounds !== undefined) return yield* Effect.fail(bounds)
+
+      const part = partsOr(input.parts, "snippet,contentDetails")
+      const parts = validateParts(part, "subscriberSnippet")
+      if (parts !== undefined) return yield* Effect.fail(parts)
+      const order = validateEnum("--order", input.order, "alphabetical", "relevance")
+      if (order !== undefined) return yield* Effect.fail(order)
+
+      // Go writes this as `(channelID == "") == (ids == "")`: both set or
+      // neither set is an error.
+      if ((input.channel === "") === (input.id === "")) {
+        return yield* Effect.fail(
+          new UsageError({ message: "provide exactly one of --channel or --id" })
+        )
+      }
+      // Literal-default comparison, deliberately not "flag was changed".
+      if (input.id !== "" && (input.forChannel !== "" || input.order !== "relevance")) {
+        return yield* Effect.fail(
+          new UsageError({ message: "--for-channel and --order are incompatible with --id" })
+        )
+      }
+
+      const params = setValues(
+        [["part", part]],
+        [
+          ["channelId", input.channel],
+          ["id", input.id],
+          ["order", input.order],
+          ["forChannelId", input.forChannel],
+          ["fields", input.fields]
+        ]
+      )
+      yield* runList("subscriptions", params, input, subscriptionListColumns)
+    })
+).pipe(Command.withDescription("List subscriptions by channel or subscription IDs"))
+
+/** The `subscription` group. Bare `oytc subscription` prints help and exits 0. */
+export const subscriptionCommand = Command.make("subscription").pipe(
+  Command.withDescription("Read public channel subscriptions"),
+  Command.withSubcommands([subscriptionListCommand])
+)
diff --git a/src/cli/validate.test.ts b/src/cli/validate.test.ts
new file mode 100644
index 0000000..02e7e8f
--- /dev/null
+++ b/src/cli/validate.test.ts
@@ -0,0 +1,416 @@
+import { describe, expect, test } from "bun:test"
+import { Option } from "effect"
+import { UsageError } from "../domain/errors.ts"
+import {
+  exactArgs,
+  firstFailure,
+  firstFailureLazy,
+  goTrimSpace,
+  maximumArgs,
+  minimumArgs,
+  parsesAsRfc3339,
+  partsOr,
+  requireExactlyOne,
+  requireThat,
+  requireTogether,
+  validateCsvEnum,
+  validateEnum,
+  validatePagination,
+  validateParts,
+  validateTimestamp
+} from "./validate.ts"
+
+/** The message of a failed check, or undefined when it passed. */
+const msg = (check: Option.Option): string | undefined =>
+  Option.isSome(check) ? check.value.message : undefined
+
+const pageFlags = (pageSize: number, limit = 0) => ({
+  pageSize,
+  limit,
+  pageToken: "",
+  all: false
+})
+
+describe("firstFailure", () => {
+  test("all passing yields none", () => {
+    expect(Option.isNone(firstFailure([Option.none(), Option.none()]))).toBe(true)
+  })
+
+  test("the FIRST failure wins, not the last", () => {
+    expect(
+      msg(
+        firstFailure([
+          Option.none(),
+          Option.some(new UsageError({ message: "first" })),
+          Option.some(new UsageError({ message: "second" }))
+        ])
+      )
+    ).toBe("first")
+  })
+
+  test("an empty list passes", () => {
+    expect(Option.isNone(firstFailure([]))).toBe(true)
+  })
+})
+
+describe("firstFailureLazy", () => {
+  test("checks after the first failure are never evaluated", () => {
+    let evaluated = 0
+    const result = firstFailureLazy([
+      () => Option.some(new UsageError({ message: "stop" })),
+      () => {
+        evaluated++
+        return Option.none()
+      }
+    ])
+    expect(msg(result)).toBe("stop")
+    expect(evaluated).toBe(0)
+  })
+})
+
+describe("argument counts — verbatim cobra messages", () => {
+  test("exactArgs", () => {
+    expect(Option.isNone(exactArgs(1, 1))).toBe(true)
+    expect(msg(exactArgs(1, 0))).toBe("expected 1 argument(s), received 0")
+    expect(msg(exactArgs(1, 2))).toBe("expected 1 argument(s), received 2")
+    // `video popular` takes exactly zero.
+    expect(msg(exactArgs(0, 1))).toBe("expected 0 argument(s), received 1")
+  })
+
+  test("minimumArgs", () => {
+    expect(Option.isNone(minimumArgs(1, 1))).toBe(true)
+    expect(Option.isNone(minimumArgs(1, 9))).toBe(true)
+    // G3: the exact `video get` message.
+    expect(msg(minimumArgs(1, 0))).toBe("expected at least 1 argument(s), received 0")
+  })
+
+  test("maximumArgs", () => {
+    expect(Option.isNone(maximumArgs(1, 0))).toBe(true)
+    expect(Option.isNone(maximumArgs(1, 1))).toBe(true)
+    expect(msg(maximumArgs(1, 2))).toBe("expected at most 1 argument(s), received 2")
+  })
+})
+
+describe("validatePagination", () => {
+  test("in-bounds passes", () => {
+    expect(Option.isNone(validatePagination(pageFlags(25), 50))).toBe(true)
+    expect(Option.isNone(validatePagination(pageFlags(1), 50))).toBe(true)
+    expect(Option.isNone(validatePagination(pageFlags(50), 50))).toBe(true)
+  })
+
+  test("G3: --page-size must be between 1 and 50", () => {
+    expect(msg(validatePagination(pageFlags(99), 50))).toBe("--page-size must be between 1 and 50")
+    expect(msg(validatePagination(pageFlags(0), 50))).toBe("--page-size must be between 1 and 50")
+    expect(msg(validatePagination(pageFlags(-1), 50))).toBe("--page-size must be between 1 and 50")
+  })
+
+  test("the max is per-command; comments are 1..100", () => {
+    expect(Option.isNone(validatePagination(pageFlags(100), 100))).toBe(true)
+    expect(msg(validatePagination(pageFlags(101), 100))).toBe(
+      "--page-size must be between 1 and 100"
+    )
+  })
+
+  test("live-chat's own bounds and message", () => {
+    const opts = { minSize: 200, message: "--page-size must be between 200 and 2000" }
+    expect(Option.isNone(validatePagination(pageFlags(500), 2000, opts))).toBe(true)
+    expect(msg(validatePagination(pageFlags(199), 2000, opts))).toBe(
+      "--page-size must be between 200 and 2000"
+    )
+  })
+
+  test("G3: --limit cannot be negative", () => {
+    expect(msg(validatePagination(pageFlags(25, -1), 50))).toBe("--limit cannot be negative")
+  })
+
+  test("--limit 0 means no cap and passes", () => {
+    expect(Option.isNone(validatePagination(pageFlags(25, 0), 50))).toBe(true)
+  })
+
+  test("page-size is checked BEFORE limit", () => {
+    expect(msg(validatePagination(pageFlags(99, -1), 50))).toBe(
+      "--page-size must be between 1 and 50"
+    )
+  })
+})
+
+describe("validateEnum", () => {
+  const order = ["date", "rating", "relevance", "title", "videoCount", "viewCount"]
+
+  test("an empty value always passes — it means the flag is unset", () => {
+    expect(Option.isNone(validateEnum("--order", "", order))).toBe(true)
+  })
+
+  test("an allowed value passes", () => {
+    expect(Option.isNone(validateEnum("--order", "viewCount", order))).toBe(true)
+  })
+
+  test("G3-style message lists every candidate, comma-space joined", () => {
+    expect(msg(validateEnum("--order", "bogus", order))).toBe(
+      "--order must be one of: date, rating, relevance, title, videoCount, viewCount"
+    )
+  })
+
+  test("comparison is case sensitive", () => {
+    expect(msg(validateEnum("--order", "VIEWCOUNT", order))).toBe(
+      "--order must be one of: date, rating, relevance, title, videoCount, viewCount"
+    )
+  })
+
+  test("comparison does NOT trim", () => {
+    expect(Option.isSome(validateEnum("--order", " date", order))).toBe(true)
+  })
+
+  test("the two-candidate message from comment threads", () => {
+    expect(msg(validateEnum("--order", "bogus", ["time", "relevance"]))).toBe(
+      "--order must be one of: time, relevance"
+    )
+  })
+})
+
+describe("validateCsvEnum", () => {
+  const types = ["video", "channel", "playlist"]
+
+  test("the default type list passes", () => {
+    expect(Option.isNone(validateCsvEnum("--type", "video,channel,playlist", types))).toBe(true)
+  })
+
+  test("each entry is trimmed before comparison", () => {
+    expect(Option.isNone(validateCsvEnum("--type", "video, channel", types))).toBe(true)
+  })
+
+  test("a trailing comma passes, because an empty entry passes", () => {
+    expect(Option.isNone(validateCsvEnum("--type", "video,", types))).toBe(true)
+  })
+
+  test("a bad entry anywhere fails", () => {
+    expect(msg(validateCsvEnum("--type", "video,bogus", types))).toBe(
+      "--type must be one of: video, channel, playlist"
+    )
+  })
+
+  test("the FIRST bad entry is reported", () => {
+    expect(msg(validateCsvEnum("--type", "zzz,bogus", types))).toBe(
+      "--type must be one of: video, channel, playlist"
+    )
+  })
+})
+
+describe("goTrimSpace", () => {
+  test("ASCII whitespace on both sides", () => {
+    expect(goTrimSpace("  \t\r\n video \n ")).toBe("video")
+  })
+
+  test("interior whitespace is untouched", () => {
+    expect(goTrimSpace(" a b ")).toBe("a b")
+  })
+
+  test("Unicode spaces Go recognises", () => {
+    expect(goTrimSpace("  video　")).toBe("video")
+  })
+
+  test("U+FEFF is NOT space in Go, unlike JS trim()", () => {
+    // JS "video".trim() === "video"; Go's TrimSpace leaves it.
+    expect("video".trim()).toBe("video")
+    expect(goTrimSpace("video")).toBe("video")
+  })
+
+  test("an all-space string trims to empty", () => {
+    expect(goTrimSpace(" \t\n ")).toBe("")
+  })
+
+  test("empty stays empty", () => {
+    expect(goTrimSpace("")).toBe("")
+  })
+})
+
+describe("partsOr", () => {
+  test("empty takes the fallback", () => {
+    expect(partsOr("", "snippet")).toBe("snippet")
+  })
+
+  test("whitespace-only takes the fallback", () => {
+    expect(partsOr("   ", "snippet")).toBe("snippet")
+  })
+
+  test("a real value is passed through UNTRIMMED", () => {
+    expect(partsOr(" snippet ", "fallback")).toBe(" snippet ")
+  })
+})
+
+describe("validateParts", () => {
+  const videoForbidden = ["fileDetails", "processingDetails", "suggestions"]
+
+  test("an allowed part list passes", () => {
+    expect(Option.isNone(validateParts("snippet,statistics", videoForbidden))).toBe(true)
+  })
+
+  test("a forbidden part fails with the %q-quoted name", () => {
+    expect(msg(validateParts("snippet,fileDetails", videoForbidden))).toBe(
+      'part "fileDetails" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  test("entries are trimmed, so a padded forbidden part is still caught", () => {
+    // Verified against the binary: `--parts ' fileDetails '` is rejected.
+    expect(msg(validateParts(" fileDetails ", videoForbidden))).toBe(
+      'part "fileDetails" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  test("the channel forbidden set", () => {
+    expect(msg(validateParts("auditDetails", ["auditDetails", "contentOwnerDetails"]))).toBe(
+      'part "auditDetails" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  test("a superstring of a forbidden part is allowed", () => {
+    expect(Option.isNone(validateParts("fileDetailsX", videoForbidden))).toBe(true)
+  })
+
+  test("the forbidden list is scanned in order for each entry", () => {
+    expect(msg(validateParts("suggestions,fileDetails", videoForbidden))).toBe(
+      'part "suggestions" requires owner/OAuth access and is not supported'
+    )
+  })
+})
+
+/**
+ * `parsesAsRfc3339` was differentially tested against `/tmp/oytc-ref` over a
+ * 580-case corpus (102 accepts / 478 rejects) with zero disagreements. The
+ * cases below are the load-bearing ones from that run, kept as regressions.
+ */
+describe("parsesAsRfc3339 — accepted", () => {
+  const accepted = [
+    "2024-01-01T00:00:00Z",
+    "2024-01-01T00:00:00+05:00",
+    "2024-01-01T00:00:00-00:00",
+    "2024-01-01T00:00:00.123Z",
+    "2024-01-01T00:00:00.000000009Z",
+    "2024-01-01T00:00:00.1234567890123Z",
+    // A comma is a legal fraction separator in Go's parser.
+    "2024-01-01T00:00:00,123Z",
+    // The HOUR — and only the hour — may be a single digit.
+    "2024-01-01T1:00:00Z",
+    "2024-01-01T5:04:05+01:00",
+    // Go's zone bound is `> 24` / `> 60`, deliberately loose.
+    "2024-01-01T00:00:00+24:00",
+    "2024-01-01T00:00:00+05:60",
+    "0000-01-01T00:00:00Z",
+    "9999-12-31T23:59:59Z",
+    "2024-02-29T00:00:00Z",
+    "2000-02-29T00:00:00Z",
+    "2024-01-01T23:59:59Z"
+  ]
+  for (const value of accepted) {
+    test(value, () => expect(parsesAsRfc3339(value)).toBe(true))
+  }
+})
+
+describe("parsesAsRfc3339 — rejected", () => {
+  const rejected: ReadonlyArray = [
+    ["2024-01-01", "no time part"],
+    ["2024-01-01T00:00:00", "no zone"],
+    ["2024-01-01t00:00:00Z", "lowercase t"],
+    ["2024-01-01T00:00:00z", "lowercase z"],
+    ["2024-01-01 00:00:00Z", "space separator"],
+    ["2024-01-01T00:00:00+0500", "zone without a colon"],
+    ["2024-01-01T00:00:00+5:00", "one-digit zone hour"],
+    ["2024-01-01T00:00:00+01:1", "one-digit zone minute"],
+    ["2024-01-01T00:00:00+25:00", "zone hour past 24"],
+    ["2024-01-01T00:00:00+00:61", "zone minute past 60"],
+    ["2024-01-01T00:00:00+99:99", "zone wildly out of range"],
+    ["2024-1-01T00:00:00Z", "one-digit month"],
+    ["2024-01-1T00:00:00Z", "one-digit day"],
+    ["2024-01-01T01:1:00Z", "one-digit minute"],
+    ["2024-01-01T01:01:1Z", "one-digit second"],
+    ["999-01-01T00:00:00Z", "three-digit year"],
+    ["20240-01-01T00:00:00Z", "five-digit year"],
+    ["2024-01-01T005:00:00Z", "three-digit hour"],
+    ["2024-00-01T00:00:00Z", "month 0"],
+    ["2024-13-01T00:00:00Z", "month 13"],
+    ["2024-01-00T00:00:00Z", "day 0"],
+    ["2024-01-32T00:00:00Z", "day 32"],
+    ["2023-02-29T00:00:00Z", "Feb 29 in a common year"],
+    ["1900-02-29T00:00:00Z", "1900 is not a leap year"],
+    ["2100-02-29T00:00:00Z", "2100 is not a leap year"],
+    ["2024-04-31T00:00:00Z", "April has 30 days"],
+    ["2024-02-30T00:00:00Z", "February never has 30"],
+    ["2024-01-01T24:00:00Z", "hour 24"],
+    ["2024-01-01T00:60:00Z", "minute 60"],
+    ["2024-01-01T00:00:60Z", "second 60 — no leap seconds"],
+    ["2024-01-01T00:00:00.Z", "a bare dot with no digits"],
+    ["2024-01-01T00:00:00Zx", "trailing text"],
+    ["2024-01-01T00:00:00ZZ", "doubled zone"],
+    ["+2024-01-01T00:00:00Z", "signed year"],
+    [" 2024-01-01T00:00:00Z", "leading space"],
+    ["2024-01-01T00:00:00Z ", "trailing space"],
+    ["2024-01-01T00:00:00+aa:bb", "non-numeric zone"],
+    ["", "empty"]
+  ]
+  for (const [value, why] of rejected) {
+    test(`${JSON.stringify(value)} — ${why}`, () => expect(parsesAsRfc3339(value)).toBe(false))
+  }
+})
+
+describe("validateTimestamp", () => {
+  test("empty passes — the flag is simply unset", () => {
+    expect(Option.isNone(validateTimestamp("--published-after", ""))).toBe(true)
+  })
+
+  test("a valid timestamp passes", () => {
+    expect(Option.isNone(validateTimestamp("--published-after", "2024-01-01T00:00:00Z"))).toBe(true)
+  })
+
+  test("the message names the flag", () => {
+    expect(msg(validateTimestamp("--published-after", "nope"))).toBe(
+      "--published-after must be an RFC 3339 timestamp"
+    )
+    expect(msg(validateTimestamp("--published-before", "nope"))).toBe(
+      "--published-before must be an RFC 3339 timestamp"
+    )
+  })
+})
+
+describe("cross-flag helpers", () => {
+  test("requireTogether passes when both are set or both empty", () => {
+    expect(Option.isNone(requireTogether("1,2", "5km", "m"))).toBe(true)
+    expect(Option.isNone(requireTogether("", "", "m"))).toBe(true)
+  })
+
+  test("requireTogether fails when exactly one is set", () => {
+    expect(msg(requireTogether("1,2", "", "--location and --location-radius must be used together")))
+      .toBe("--location and --location-radius must be used together")
+    expect(msg(requireTogether("", "5km", "m"))).toBe("m")
+  })
+
+  test("requireExactlyOne fails when both or neither hold", () => {
+    // `channel sections`: (ids == "") == (no positional)
+    expect(msg(requireExactlyOne(true, true, "provide exactly one of CHANNEL or --id"))).toBe(
+      "provide exactly one of CHANNEL or --id"
+    )
+    expect(msg(requireExactlyOne(false, false, "provide exactly one of CHANNEL or --id"))).toBe(
+      "provide exactly one of CHANNEL or --id"
+    )
+    expect(Option.isNone(requireExactlyOne(true, false, "m"))).toBe(true)
+    expect(Option.isNone(requireExactlyOne(false, true, "m"))).toBe(true)
+  })
+
+  test("requireThat", () => {
+    expect(Option.isNone(requireThat(true, "m"))).toBe(true)
+    expect(msg(requireThat(false, "video-specific filters require --type video"))).toBe(
+      "video-specific filters require --type video"
+    )
+  })
+})
+
+describe("every failure is a UsageError, which exits 2", () => {
+  test("the tag and exit code", () => {
+    const failure = validateEnum("--order", "bogus", ["date"])
+    expect(Option.isSome(failure)).toBe(true)
+    if (Option.isSome(failure)) {
+      expect(failure.value).toBeInstanceOf(UsageError)
+      expect(failure.value._tag).toBe("UsageError")
+    }
+  })
+})
diff --git a/src/cli/validate.ts b/src/cli/validate.ts
index ca14f9a..ab2bb6d 100644
--- a/src/cli/validate.ts
+++ b/src/cli/validate.ts
@@ -1,2 +1,542 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * Command scaffolding: every validation check, plus the flag groups and request
+ * helpers that every leaf command shares.
+ *
+ * Ports the `validate*` / `*Args` / `addListFlags` / `addAPIFlags` / `setValues`
+ * / `batch` helpers from `internal/cli/app.go`. Each validation returns
+ * `Option` — `Option.none()` for "passed" — so a handler can
+ * evaluate checks in Go's exact order with a single `firstFailure([...])`.
+ *
+ * ORDER OF EVALUATION (measured against `/tmp/oytc-ref`, not just read off the
+ * spec):
+ *
+ *   1. flag parsing                    (the CLI framework)
+ *   2. positional-argument count       `expected N argument(s), received M`
+ *   3. global `--format` / `--timeout` (root.ts's `Command.provide`)
+ *   4. pagination                      `--page-size` then `--limit`  (Go: PreRunE)
+ *   5. per-command semantic checks     (Go: RunE, in source order)
+ *
+ * Steps 2, 4 and 5 all live in the handler here, in that order. Step 3 is
+ * root.ts's business; see the note on `exactArgs` for the one corner where that
+ * reorders relative to Go.
+ *
+ * SHARED HELPER — P8b and P8c import from here read-only. Do not edit outside
+ * P8a.
+ */
+
+import { Effect, Option } from "effect"
+import { Flag } from "../effect.ts"
+import { NotFoundError, UsageError } from "../domain/errors.ts"
+import type { PageOptions } from "../domain/listResult.ts"
+import type { JsonObject } from "../json/value.ts"
+import { goQuote } from "../impl/resolveChannel.ts"
+import type { Params } from "../services/index.ts"
+
+/** Sugar: a failed check. */
+const fail = (message: string): Option.Option =>
+  Option.some(new UsageError({ message }))
+
+const pass: Option.Option = Option.none()
+
+/**
+ * Evaluate checks in order and return the first failure.
+ *
+ * Every argument is an already-evaluated `Option`, so all the checks run; they
+ * are pure string comparisons with no side effects, exactly like Go's, and the
+ * REPORTED failure is still the first one. Use `firstFailureLazy` when a later
+ * check would be expensive or would misbehave on input an earlier check
+ * rejects.
+ */
+export const firstFailure = (
+  checks: ReadonlyArray>
+): Option.Option => {
+  for (const check of checks) {
+    if (Option.isSome(check)) return check
+  }
+  return pass
+}
+
+/** `firstFailure` over thunks, for checks that must not be evaluated early. */
+export const firstFailureLazy = (
+  checks: ReadonlyArray<() => Option.Option>
+): Option.Option => {
+  for (const check of checks) {
+    const result = check()
+    if (Option.isSome(result)) return result
+  }
+  return pass
+}
+
+// ---------------------------------------------------------------------------
+// Positional argument counts
+// ---------------------------------------------------------------------------
+
+/**
+ * cobra's `PositionalArgs` validators, all three of them.
+ *
+ * DEVIATION, corner case only: Go runs these before `PersistentPreRunE`, so
+ * `oytc --format bogus search a b` reports the ARG error. Here the global
+ * format/timeout check lives in root.ts's `Command.provide`, which the
+ * framework evaluates before any handler body, so that one invocation reports
+ * the FORMAT error instead. Each check alone is verbatim and exits 2; only
+ * their relative precedence when BOTH fail differs, and only against the two
+ * global flags. root.ts is not ours to change — reported to the orchestrator.
+ */
+export const exactArgs = (count: number, received: number): Option.Option =>
+  received === count ? pass : fail(`expected ${count} argument(s), received ${received}`)
+
+export const minimumArgs = (count: number, received: number): Option.Option =>
+  received >= count ? pass : fail(`expected at least ${count} argument(s), received ${received}`)
+
+export const maximumArgs = (count: number, received: number): Option.Option =>
+  received <= count ? pass : fail(`expected at most ${count} argument(s), received ${received}`)
+
+// ---------------------------------------------------------------------------
+// Pagination (Go: the PreRunE installed by addListFlags)
+// ---------------------------------------------------------------------------
+
+export interface ListFlagValues {
+  readonly pageSize: number
+  readonly pageToken: string
+  readonly all: boolean
+  readonly limit: number
+}
+
+/**
+ * `--page-size` bounds then `--limit >= 0`, in that order.
+ *
+ * The bounds are per-command and are NOT all 1..50 (SPEC_API §3.2): `comment
+ * replies`/`threads` are 1..100 and `live-chat` is 200..2000. Go's shared
+ * `addListFlags` always formats "between 1 and "; `live-chat` does not use
+ * it and hard-codes "between 200 and 2000". So `minSize` defaults to 1 and a
+ * caller with a different minimum passes both `minSize` and the exact
+ * `message` it wants.
+ */
+export const validatePagination = (
+  flags: ListFlagValues,
+  maxSize: number,
+  options: { readonly minSize?: number; readonly message?: string } = {}
+): Option.Option => {
+  const minSize = options.minSize ?? 1
+  if (flags.pageSize < minSize || flags.pageSize > maxSize) {
+    return fail(options.message ?? `--page-size must be between ${minSize} and ${maxSize}`)
+  }
+  if (flags.limit < 0) return fail("--limit cannot be negative")
+  return pass
+}
+
+// ---------------------------------------------------------------------------
+// strings.TrimSpace
+// ---------------------------------------------------------------------------
+
+/**
+ * `unicode.IsSpace` as code points.
+ *
+ * NOT the same set as JS `String.prototype.trim()`: JS also trims U+FEFF
+ * (ZERO WIDTH NO-BREAK SPACE), which Go does not consider space, so `trim()`
+ * alone would accept a value Go rejects. Listed numerically rather than as
+ * literal characters so the set is reviewable and cannot be corrupted by an
+ * editor normalizing invisible code points.
+ */
+const GO_SPACE = new Set([
+  0x09, // \t
+  0x0a, // \n
+  0x0b, // \v
+  0x0c, // \f
+  0x0d, // \r
+  0x20, // space
+  0x85, // NEL
+  0xa0, // NBSP
+  0x1680, // OGHAM SPACE MARK
+  0x2000,
+  0x2001,
+  0x2002,
+  0x2003,
+  0x2004,
+  0x2005,
+  0x2006,
+  0x2007,
+  0x2008,
+  0x2009,
+  0x200a,
+  0x2028, // LINE SEPARATOR
+  0x2029, // PARAGRAPH SEPARATOR
+  0x202f, // NARROW NO-BREAK SPACE
+  0x205f, // MEDIUM MATHEMATICAL SPACE
+  0x3000 // IDEOGRAPHIC SPACE
+])
+
+const isGoSpace = (rune: string): boolean => GO_SPACE.has(rune.codePointAt(0) ?? -1)
+
+export const goTrimSpace = (value: string): string => {
+  const runes = Array.from(value)
+  let start = 0
+  let end = runes.length
+  while (start < end && isGoSpace(runes[start]!)) start++
+  while (end > start && isGoSpace(runes[end - 1]!)) end--
+  return runes.slice(start, end).join("")
+}
+
+// ---------------------------------------------------------------------------
+// Enums
+// ---------------------------------------------------------------------------
+
+/**
+ * `validateEnum` — an EMPTY value always passes (it means "flag not set"), and
+ * the comparison is exact: no trimming, no case folding.
+ */
+export const validateEnum = (
+  flag: string,
+  value: string,
+  allowed: ReadonlyArray
+): Option.Option => {
+  if (value === "") return pass
+  if (allowed.includes(value)) return pass
+  return fail(`${flag} must be one of: ${allowed.join(", ")}`)
+}
+
+/**
+ * `validateCSVEnum` — split on `,`, TRIM each entry, then run `validateEnum`.
+ *
+ * The trim means `--type "video, channel"` passes, and the empty-value pass in
+ * `validateEnum` means a trailing comma (`"video,"`) passes too. Both are Go's
+ * behaviour, not accidents of this port.
+ */
+export const validateCsvEnum = (
+  flag: string,
+  value: string,
+  allowed: ReadonlyArray
+): Option.Option => {
+  for (const entry of value.split(",")) {
+    const check = validateEnum(flag, goTrimSpace(entry), allowed)
+    if (Option.isSome(check)) return check
+  }
+  return pass
+}
+
+// ---------------------------------------------------------------------------
+// Parts
+// ---------------------------------------------------------------------------
+
+/**
+ * `partsOr` — the fallback is used when the value is empty OR entirely
+ * whitespace, but the value is otherwise passed through UNTRIMMED.
+ */
+export const partsOr = (value: string, fallback: string): string =>
+  goTrimSpace(value) === "" ? fallback : value
+
+/**
+ * `validateParts` — reject owner-only parts.
+ *
+ * Each comma-separated entry is trimmed before comparison, so
+ * `--parts " fileDetails "` is rejected (verified against the binary), and the
+ * message quotes the FORBIDDEN part — not the user's spelling — through `%q`
+ * / `strconv.Quote`.
+ */
+export const validateParts = (
+  parts: string,
+  forbidden: ReadonlyArray
+): Option.Option => {
+  for (const value of parts.split(",")) {
+    for (const blocked of forbidden) {
+      if (goTrimSpace(value) === blocked) {
+        return fail(`part ${goQuote(blocked)} requires owner/OAuth access and is not supported`)
+      }
+    }
+  }
+  return pass
+}
+
+// ---------------------------------------------------------------------------
+// Timestamps
+// ---------------------------------------------------------------------------
+
+const isDigits = (value: string): boolean => /^[0-9]+$/.test(value)
+
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+
+const isLeap = (year: number): boolean => year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)
+
+const daysIn = (year: number, month: number): number =>
+  month === 2 && isLeap(year) ? 29 : DAYS_IN_MONTH[month - 1]!
+
+/**
+ * `time.Parse(time.RFC3339, value)` — strict, and NOT what `new Date(...)`
+ * accepts. Every rule below was confirmed against `/tmp/oytc-ref`:
+ *
+ *   accepted: `2024-01-01T00:00:00Z`, `…+05:00`, `…-00:00`, fractional seconds
+ *             of ANY length (`,` works as the separator too), `1:00:00` (the
+ *             HOUR may be one digit), `…+24:00` and `…+05:60` (see the zone
+ *             note), `0000-01-01T00:00:00Z`
+ *   rejected: a lowercase `t` or `z`, a missing zone, `+0500` (no colon), a
+ *             one-digit month/day/minute/second, a 5-digit year, a leading or
+ *             trailing space, a bare `.` with no fractional digits, month 0/13,
+ *             day 0/32, `2023-02-29`, `2024-04-31`, hour 24, minute 60,
+ *             second 60 (Go rejects leap seconds here), `+25:00`, `+00:61`,
+ *             any trailing text
+ *
+ * Two surprises, both differentially confirmed against the binary:
+ *
+ * 1. The one-digit HOUR. Go's `Parse(RFC3339, …)` first tries the fast path
+ *    `parseRFC3339`, which is strictly fixed-width, and on failure falls back
+ *    to the general layout parser — where the reference hour `15` is read by
+ *    `getnum(…, false)` as "one OR two digits", while `01`/`02`/`04`/`05` stay
+ *    fixed-width. So `2024-01-01T1:00:00Z` really does parse.
+ *
+ * 2. The ZONE is range-checked, but with `>` and not `>=`. Go's comment says
+ *    it outright: "The range test use > rather than >=, as some people do write
+ *    offsets of 24 hours or 60 minutes or 60 seconds." Hence `+24:00` and
+ *    `+00:60` pass while `+25:00` and `+00:61` fail. An earlier reading of this
+ *    port had the zone unchecked; the `+99:99` case caught it.
+ */
+export const parsesAsRfc3339 = (value: string): boolean => {
+  let rest = value
+
+  const fixed = (width: number): number | undefined => {
+    const head = rest.slice(0, width)
+    if (head.length !== width || !isDigits(head)) return undefined
+    rest = rest.slice(width)
+    return Number(head)
+  }
+
+  const literal = (char: string): boolean => {
+    if (!rest.startsWith(char)) return false
+    rest = rest.slice(char.length)
+    return true
+  }
+
+  const year = fixed(4)
+  if (year === undefined || !literal("-")) return false
+  const month = fixed(2)
+  if (month === undefined || month < 1 || month > 12 || !literal("-")) return false
+  const day = fixed(2)
+  if (day === undefined || day < 1 || !literal("T")) return false
+  if (day > daysIn(year, month)) return false
+
+  // The hour is `15` in Go's layout: one or two digits, unlike every other
+  // numeric field here.
+  const hourText = rest.length >= 2 && isDigits(rest.slice(0, 2)) ? rest.slice(0, 2) : rest.slice(0, 1)
+  if (hourText === "" || !isDigits(hourText)) return false
+  rest = rest.slice(hourText.length)
+  if (Number(hourText) > 23) return false
+
+  if (!literal(":")) return false
+  const minute = fixed(2)
+  if (minute === undefined || minute > 59 || !literal(":")) return false
+  const second = fixed(2)
+  if (second === undefined || second > 59) return false
+
+  // Optional fractional seconds: the separator MUST be followed by a digit.
+  if (rest.startsWith(".") || rest.startsWith(",")) {
+    rest = rest.slice(1)
+    let digits = 0
+    while (digits < rest.length && isDigits(rest[digits]!)) digits++
+    if (digits === 0) return false
+    rest = rest.slice(digits)
+  }
+
+  // Zone: `Z` (uppercase only) or ±HH:MM, with Go's deliberately loose
+  // `hh > 24 || mm > 60` bound rather than the tight one.
+  if (rest === "Z") return true
+  if (rest.length !== 6) return false
+  const sign = rest[0]
+  if (sign !== "+" && sign !== "-") return false
+  const zoneHour = rest.slice(1, 3)
+  const zoneMinute = rest.slice(4, 6)
+  if (!isDigits(zoneHour) || rest[3] !== ":" || !isDigits(zoneMinute)) return false
+  return Number(zoneHour) <= 24 && Number(zoneMinute) <= 60
+}
+
+/** `validateTimestamp` — empty passes; anything else must parse as RFC 3339. */
+export const validateTimestamp = (flag: string, value: string): Option.Option => {
+  if (value === "") return pass
+  return parsesAsRfc3339(value) ? pass : fail(`${flag} must be an RFC 3339 timestamp`)
+}
+
+// ---------------------------------------------------------------------------
+// Cross-flag checks
+// ---------------------------------------------------------------------------
+
+/** `(a == "") != (b == "")` — both set or neither. */
+export const requireTogether = (
+  a: string,
+  b: string,
+  message: string
+): Option.Option => ((a === "") !== (b === "") ? fail(message) : pass)
+
+/** `(flagEmpty) == (positionalAbsent)` — exactly one of the two. */
+export const requireExactlyOne = (
+  first: boolean,
+  second: boolean,
+  message: string
+): Option.Option => (first === second ? fail(message) : pass)
+
+/** A plain predicate check, for the one-off cross-flag rules. */
+export const requireThat = (ok: boolean, message: string): Option.Option =>
+  ok ? pass : fail(message)
+
+/** Raise an already-built check failure from inside a handler. */
+export const raise = (error: UsageError): Effect.Effect => Effect.fail(error)
+
+// ---------------------------------------------------------------------------
+// Shared flag groups (Go: addListFlags / addAPIFlags)
+// ---------------------------------------------------------------------------
+
+/**
+ * `addListFlags`, minus the PreRunE — the bounds check is
+ * `validatePagination`, called from the handler so it fires in Go's order
+ * relative to the arg-count check.
+ *
+ * `--page-size` is declared as an integer with the command's own default; the
+ * VALID RANGE is deliberately not expressed as a `Flag.filter`, because that
+ * would produce the framework's "Invalid value" text instead of Go's
+ * `--page-size must be between 1 and 50`.
+ */
+export const listFlags = (options: { readonly pageSize: number; readonly maxSize?: number }) => ({
+  pageSize: Flag.integer("page-size").pipe(
+    Flag.withDefault(options.pageSize),
+    Flag.withDescription(`results per request (1-${options.maxSize ?? 50})`)
+  ),
+  pageToken: Flag.string("page-token").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("start at this API page token")
+  ),
+  all: Flag.boolean("all").pipe(Flag.withDescription("fetch all available pages")),
+  limit: Flag.integer("limit").pipe(
+    Flag.withDefault(0),
+    Flag.withDescription("maximum items to emit (0 means no additional limit)")
+  )
+})
+
+/**
+ * `addAPIFlags(cmd, &api, withHL = false)`.
+ *
+ * Two separate groups rather than one parameterised builder: `--hl` exists only
+ * on the commands Go passes `withHL = true`, and declaring it unconditionally
+ * would make `oytc search --hl en` succeed where Go reports
+ * `unknown flag: --hl`. A conditional spread hides `hl` from the inferred type
+ * as well as the parser, which is worse than two named constants.
+ */
+export const apiFlags = {
+  parts: Flag.string("parts").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("comma-separated API resource parts")
+  ),
+  fields: Flag.string("fields").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("Google partial-response fields selector")
+  )
+}
+
+/** `addAPIFlags(cmd, &api, withHL = true)`. */
+export const apiFlagsWithHl = {
+  ...apiFlags,
+  hl: Flag.string("hl").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("localization language code")
+  )
+}
+
+/** `--published-after` / `--published-before`, shared by search and activities. */
+export const publishedFlags = {
+  publishedAfter: Flag.string("published-after").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("RFC 3339 lower publication bound")
+  ),
+  publishedBefore: Flag.string("published-before").pipe(
+    Flag.withDefault(""),
+    Flag.withDescription("RFC 3339 upper publication bound")
+  )
+}
+
+/** `youtube.PageOptions{…}` from the parsed list flags. */
+export const pageOptionsOf = (
+  flags: ListFlagValues,
+  filter?: ((item: JsonObject) => boolean) | undefined
+): PageOptions => ({
+  all: flags.all,
+  limit: flags.limit,
+  pageSize: flags.pageSize,
+  pageToken: flags.pageToken,
+  filter
+})
+
+// ---------------------------------------------------------------------------
+// Request assembly
+// ---------------------------------------------------------------------------
+
+/**
+ * `setValues(params, map)` — set each key whose value is NON-EMPTY.
+ *
+ * Go iterates a `map[string]string`, whose order is randomized; the params are
+ * sorted at encode time, so order here is unobservable. A defined iteration
+ * order is used anyway so tests can assert on the param list directly.
+ */
+export const setValues = (
+  base: Params,
+  entries: Readonly>
+): Params => {
+  const out: Array = [...base]
+  for (const key of Object.keys(entries)) {
+    const value = entries[key]
+    if (value !== undefined && value !== "") out.push([key, value])
+  }
+  return out
+}
+
+/** IDs per batch-get request: 50 for channels/videos/playlists, 100 for comments. */
+export const BATCH_SIZE = 50
+
+/** `batch(values, size)` — contiguous chunks; an empty input yields no chunks. */
+export const batch = (values: ReadonlyArray, size: number): ReadonlyArray> => {
+  const out: Array> = []
+  for (let i = 0; i < values.length; i += size) out.push(values.slice(i, i + size))
+  return out
+}
+
+/**
+ * `validateRequestedItems` — every requested ID must have come back.
+ *
+ * Step 3 is the subtle one: when NO ids were recoverable from the response (a
+ * `--fields` selector stripped them) equal cardinality is accepted, because it
+ * is the strongest check available without overriding the user's selector.
+ *
+ * The failure is a `NotFoundError` (exit 4), not a `UsageError`: Go returns a
+ * bare `fmt.Errorf` here, and its message-substring classifier routes anything
+ * containing "not found" to exit 4.
+ */
+export const validateRequestedItems = (
+  resource: string,
+  requested: ReadonlyArray,
+  items: ReadonlyArray
+): Effect.Effect => {
+  const uniqueRequested: Array = []
+  const seen = new Set()
+  for (const id of requested) {
+    if (!seen.has(id)) {
+      seen.add(id)
+      uniqueRequested.push(id)
+    }
+  }
+
+  const returned = new Set()
+  for (const item of items) {
+    const id = item["id"]
+    if (typeof id === "string" && id !== "") returned.add(id)
+  }
+
+  // Step 3: the equal-cardinality escape hatch.
+  if (returned.size === 0 && items.length === uniqueRequested.length) return Effect.void
+
+  let missing: ReadonlyArray = []
+  if (returned.size > 0) {
+    missing = uniqueRequested.filter((id) => !returned.has(id))
+  } else if (items.length < uniqueRequested.length) {
+    missing = uniqueRequested
+  }
+
+  if (missing.length === 0) return Effect.void
+  return Effect.fail(
+    new NotFoundError({ message: `${resource} not found: ${missing.join(", ")}` })
+  )
+}
diff --git a/src/cli/versionUpdate.test.ts b/src/cli/versionUpdate.test.ts
new file mode 100644
index 0000000..30f5ba0
--- /dev/null
+++ b/src/cli/versionUpdate.test.ts
@@ -0,0 +1,398 @@
+/**
+ * `version` / `update` tests.
+ *
+ * The two things worth guarding hardest are the `update` field renames
+ * (`assetName` -> `asset`, `executablePath` -> `executable`) and G4's
+ * sorted-JSON / declaration-order-TSV split, because both are invisible until
+ * a consumer's script breaks.
+ */
+
+import { describe, expect, test } from "bun:test"
+import { Effect, Exit, Layer, Sink, Stdio } from "effect"
+import { Command } from "../effect.ts"
+import { OperationalError, type OytcError } from "../domain/errors.ts"
+import { makeRendererWith } from "../impl/renderer.ts"
+import { updateColumns, versionColumns } from "../output/columns.ts"
+import {
+  AppOptions,
+  Renderer,
+  Updater,
+  VersionInfo,
+  type AppOptionsShape,
+  type OutputFormat,
+  type UpdateOptions,
+  type UpdateResult,
+  type VersionDetails
+} from "../services/index.ts"
+import { globalFlags } from "./flags.ts"
+import {
+  isUpToDate,
+  updateCommand,
+  versionCommand,
+  versionUpdateCommands
+} from "./versionUpdate.ts"
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const details: VersionDetails = {
+  version: "v0.3.3",
+  commit: "699879f7a454180ef4039d096ce2b898a96486f6",
+  date: "2026-07-25T05:47:34Z",
+  goVersion: "bun1.3.14",
+  os: "darwin",
+  arch: "arm64"
+}
+
+const updateResult = (overrides?: Partial): UpdateResult => ({
+  currentVersion: "v0.3.0",
+  latestVersion: "v0.4.0",
+  updated: false,
+  asset: "oytc_v0.4.0_darwin_arm64.tar.gz",
+  executable: "/usr/local/bin/oytc",
+  ...overrides
+})
+
+interface RunOptions {
+  readonly format?: OutputFormat | undefined
+  readonly columns?: ReadonlyArray | undefined
+  readonly noHeader?: boolean | undefined
+  readonly result?: UpdateResult | undefined
+  readonly error?: OytcError | undefined
+  readonly version?: VersionDetails | undefined
+}
+
+const runCommand = async (
+  argv: ReadonlyArray,
+  options: RunOptions = {}
+): Promise<{
+  readonly stdout: string
+  readonly exit: Exit.Exit
+  readonly updateCalls: ReadonlyArray
+}> => {
+  const out: Array = []
+  const updateCalls: Array = []
+  const decode = (i: string | Uint8Array): string =>
+    typeof i === "string" ? i : new TextDecoder().decode(i)
+
+  const stdio = Stdio.layerTest({
+    stdout: () => Sink.forEach((i: string | Uint8Array) => Effect.sync(() => out.push(decode(i)))),
+    stderr: () => Sink.forEach(() => Effect.void)
+  })
+
+  const appOptions: AppOptionsShape = {
+    format: options.format ?? "table",
+    columns: options.columns ?? [],
+    noHeader: options.noHeader ?? false,
+    quiet: false,
+    timeoutMillis: 20_000,
+    isOutputTTY: true
+  }
+
+  const layers = Layer.mergeAll(
+    Layer.succeed(AppOptions, appOptions),
+    Layer.succeed(VersionInfo, { get: Effect.succeed(options.version ?? details) }),
+    Layer.succeed(Updater, {
+      run: (opts: UpdateOptions) =>
+        Effect.suspend(() => {
+          updateCalls.push(opts)
+          return options.error === undefined
+            ? Effect.succeed(options.result ?? updateResult())
+            : Effect.fail(options.error)
+        })
+    }),
+    Layer.succeed(
+      Renderer,
+      makeRendererWith((text) => Effect.sync(() => void out.push(text)))
+    )
+  )
+
+  const root = Command.make("oytc").pipe(
+    Command.withSharedFlags(globalFlags),
+    Command.withSubcommands([...versionUpdateCommands])
+  )
+  const exit = await Effect.runPromiseExit(
+    Command.runWith(root, { version: "test" })(argv).pipe(
+      Effect.provide(Layer.mergeAll(layers, stdio))
+    ) as Effect.Effect
+  )
+  return { stdout: out.join(""), exit, updateCalls }
+}
+
+const failureOf = (exit: Exit.Exit): OytcError => {
+  if (Exit.isSuccess(exit)) throw new Error("expected a failure")
+  const found = exit.cause.reasons.find((r) => r._tag === "Fail")
+  if (found === undefined) throw new Error(`no Fail reason: ${String(exit.cause)}`)
+  return (found as { readonly error: OytcError }).error
+}
+
+// ---------------------------------------------------------------------------
+// version
+// ---------------------------------------------------------------------------
+
+describe("version", () => {
+  test("the table rendering matches Go's four lines exactly", async () => {
+    const { stdout, exit } = await runCommand(["version"], { format: "table" })
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(stdout).toBe(
+      "oytc v0.3.3\n" +
+        "commit: 699879f7a454180ef4039d096ce2b898a96486f6\n" +
+        "built: 2026-07-25T05:47:34Z\n" +
+        "go: bun1.3.14 (darwin/arm64)\n"
+    )
+  })
+
+  test("G4: json keys are SORTED alphabetically", async () => {
+    const { stdout } = await runCommand(["version"], { format: "json" })
+    const keys = [...stdout.matchAll(/^ {2}"([^"]+)"/gm)].map((m) => m[1])
+    expect(keys).toEqual(["arch", "commit", "date", "goVersion", "os", "version"])
+  })
+
+  test("G4: tsv headers are in DECLARATION order, not sorted", async () => {
+    const { stdout } = await runCommand(["version"], { format: "tsv" })
+    const header = stdout.split("\n")[0]!.split("\t")
+    expect(header).toEqual(["VERSION", "COMMIT", "DATE", "GOVERSION", "OS", "ARCH"])
+    // Explicitly NOT the sorted order the JSON form uses.
+    expect(header).not.toEqual([...header].sort())
+  })
+
+  test("the tsv row carries the values in the same declaration order", async () => {
+    const { stdout } = await runCommand(["version"], { format: "tsv" })
+    expect(stdout.split("\n")[1]!.split("\t")).toEqual([
+      "v0.3.3",
+      "699879f7a454180ef4039d096ce2b898a96486f6",
+      "2026-07-25T05:47:34Z",
+      "bun1.3.14",
+      "darwin",
+      "arm64"
+    ])
+  })
+
+  test("`goVersion` keeps its Go spelling — it is a documented column", async () => {
+    const { stdout } = await runCommand(["version"], { format: "json" })
+    expect(stdout).toContain('"goVersion"')
+    expect(stdout).not.toContain('"bunVersion"')
+    expect(stdout).not.toContain('"runtimeVersion"')
+    expect(versionColumns).toContain("goVersion")
+  })
+
+  test("jsonl is a single compact line", async () => {
+    const { stdout } = await runCommand(["version"], { format: "jsonl" })
+    expect(stdout.trimEnd().split("\n")).toHaveLength(1)
+    expect(stdout).toStartWith('{"arch":"arm64"')
+  })
+
+  test("--no-header drops the tsv header row", async () => {
+    const { stdout } = await runCommand(["version"], { format: "tsv", noHeader: true })
+    expect(stdout).toStartWith("v0.3.3\t")
+  })
+
+  test("--columns overrides the default column list", async () => {
+    const { stdout } = await runCommand(["version"], {
+      format: "tsv",
+      columns: ["os", "arch"]
+    })
+    expect(stdout).toBe("OS\tARCH\ndarwin\tarm64\n")
+  })
+
+  test("a default (unstamped) build reports dev/unknown/unknown", async () => {
+    const { stdout } = await runCommand(["version"], {
+      format: "table",
+      version: { ...details, version: "dev", commit: "unknown", date: "unknown" }
+    })
+    expect(stdout).toStartWith("oytc dev\ncommit: unknown\nbuilt: unknown\n")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// update — the field renames
+// ---------------------------------------------------------------------------
+
+describe("update field renames", () => {
+  test("emits `asset` and `executable`, NOT assetName/executablePath", async () => {
+    const { stdout } = await runCommand(["update", "--check"], { format: "json" })
+    expect(stdout).toContain('"asset"')
+    expect(stdout).toContain('"executable"')
+    expect(stdout).not.toContain('"assetName"')
+    expect(stdout).not.toContain('"executablePath"')
+  })
+
+  test("the renamed keys carry the right values", async () => {
+    const { stdout } = await runCommand(["update", "--check"], { format: "json" })
+    expect(stdout).toContain('"asset": "oytc_v0.4.0_darwin_arm64.tar.gz"')
+    expect(stdout).toContain('"executable": "/usr/local/bin/oytc"')
+  })
+
+  test("the tsv column list uses the renamed keys in declaration order", async () => {
+    const { stdout } = await runCommand(["update", "--check"], { format: "tsv" })
+    expect(stdout.split("\n")[0]!.split("\t")).toEqual([
+      "CURRENTVERSION",
+      "TARGETVERSION",
+      "UPDATED",
+      "UPTODATE",
+      "ASSET",
+      "EXECUTABLE"
+    ])
+    expect(updateColumns).toEqual([
+      "currentVersion",
+      "targetVersion",
+      "updated",
+      "upToDate",
+      "asset",
+      "executable"
+    ])
+  })
+
+  test("`latestVersion` is emitted under the key `targetVersion`", async () => {
+    // The service contract calls it latestVersion; the CLI's output contract
+    // calls it targetVersion. Both names must not appear.
+    const { stdout } = await runCommand(["update", "--check"], { format: "json" })
+    expect(stdout).toContain('"targetVersion": "v0.4.0"')
+    expect(stdout).not.toContain('"latestVersion"')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// update — up-to-date derivation and the three table sentences
+// ---------------------------------------------------------------------------
+
+describe("isUpToDate", () => {
+  test("identical comparable versions are up to date", () => {
+    expect(isUpToDate("v1.2.3", "v1.2.3")).toBe(true)
+  })
+
+  test("a newer remote is not up to date", () => {
+    expect(isUpToDate("v1.3.0", "v1.2.3")).toBe(false)
+  })
+
+  test("an older remote is not up to date", () => {
+    expect(isUpToDate("v1.0.0", "v1.2.3")).toBe(false)
+  })
+
+  test("an incomparable pair is not up to date", () => {
+    expect(isUpToDate("v1.2.3", "dev")).toBe(false)
+    expect(isUpToDate("", "")).toBe(false)
+  })
+
+  test("a `v` prefix difference still compares equal", () => {
+    expect(isUpToDate("v1.2.3", "1.2.3")).toBe(true)
+  })
+})
+
+describe("update table renderings", () => {
+  test("up to date", async () => {
+    const { stdout } = await runCommand(["update", "--check"], {
+      format: "table",
+      result: updateResult({ currentVersion: "v0.4.0", latestVersion: "v0.4.0" })
+    })
+    expect(stdout).toBe("oytc v0.4.0 is already the latest release.\n")
+  })
+
+  test("updated", async () => {
+    const { stdout } = await runCommand(["update"], {
+      format: "table",
+      result: updateResult({ updated: true })
+    })
+    expect(stdout).toBe("Updated v0.3.0 -> v0.4.0 (/usr/local/bin/oytc)\n")
+  })
+
+  test("available but not installed (the --check case)", async () => {
+    const { stdout } = await runCommand(["update", "--check"], { format: "table" })
+    expect(stdout).toBe(
+      "Update available: v0.4.0 (current: v0.3.0)\nRun 'oytc update' to install it.\n"
+    )
+  })
+
+  test("up-to-date wins over updated when both could apply", async () => {
+    const { stdout } = await runCommand(["update"], {
+      format: "table",
+      result: updateResult({ currentVersion: "v0.4.0", latestVersion: "v0.4.0", updated: true })
+    })
+    expect(stdout).toStartWith("oytc v0.4.0 is already the latest release.")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// update — flags
+// ---------------------------------------------------------------------------
+
+describe("update flags", () => {
+  test("--check is forwarded as checkOnly", async () => {
+    const { updateCalls } = await runCommand(["update", "--check"])
+    expect(updateCalls).toEqual([{ checkOnly: true, targetVersion: "" }])
+  })
+
+  test("without --check, checkOnly is false", async () => {
+    const { updateCalls } = await runCommand(["update"])
+    expect(updateCalls).toEqual([{ checkOnly: false, targetVersion: "" }])
+  })
+
+  test("--version takes a STRING tag, shadowing the built-in version flag", async () => {
+    const { updateCalls, exit } = await runCommand(["update", "--version=v0.2.0"])
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(updateCalls).toEqual([{ checkOnly: false, targetVersion: "v0.2.0" }])
+  })
+
+  test("--version combines with --check", async () => {
+    const { updateCalls } = await runCommand(["update", "--check", "--version=v0.2.0"])
+    expect(updateCalls).toEqual([{ checkOnly: true, targetVersion: "v0.2.0" }])
+  })
+
+  test("an updater failure propagates and nothing is rendered", async () => {
+    const boom = new OperationalError({ message: "release not found" })
+    const { exit, stdout } = await runCommand(["update", "--check"], { error: boom })
+    expect(failureOf(exit)).toBe(boom)
+    expect(stdout).toBe("")
+  })
+
+  test("--columns overrides the default column list", async () => {
+    const { stdout } = await runCommand(["update", "--check"], {
+      format: "tsv",
+      columns: ["asset"]
+    })
+    expect(stdout).toBe("ASSET\noytc_v0.4.0_darwin_arm64.tar.gz\n")
+  })
+
+  test("the `updated` boolean is a real JSON boolean, pretty-printed", async () => {
+    const { stdout } = await runCommand(["update"], {
+      format: "json",
+      result: updateResult({ updated: true })
+    })
+    // Go's MarshalIndent emits `"updated": true` with a space after the colon.
+    expect(stdout).toContain('"updated": true')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+describe("command registration", () => {
+  test("both commands are exported with Go's names", () => {
+    expect(versionUpdateCommands.map((c) => c.name)).toEqual(["version", "update"])
+    expect(versionCommand.name).toBe("version")
+    expect(updateCommand.name).toBe("update")
+  })
+
+  test("`upgrade` is registered as an alias of update", () => {
+    expect(updateCommand.alias).toBe("upgrade")
+  })
+
+  test("version's description matches Go's Short string", () => {
+    expect(versionCommand.description).toBe("Show version, commit, and build date")
+  })
+
+  test("update's description is Go's multi-paragraph Long text", () => {
+    expect(updateCommand.description).toStartWith(
+      "Downloads the matching release archive and checksums.txt from GitHub Releases,"
+    )
+    expect(updateCommand.description).toContain("'oytc upgrade' is an alias")
+  })
+
+  test("`oytc upgrade` resolves to the update command", async () => {
+    const { updateCalls, exit } = await runCommand(["upgrade", "--check"])
+    expect(Exit.isSuccess(exit)).toBe(true)
+    expect(updateCalls).toEqual([{ checkOnly: true, targetVersion: "" }])
+  })
+})
diff --git a/src/cli/versionUpdate.ts b/src/cli/versionUpdate.ts
index ca14f9a..a9224d9 100644
--- a/src/cli/versionUpdate.ts
+++ b/src/cli/versionUpdate.ts
@@ -1,2 +1,188 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `version` and `update` — the port of `internal/cli/version_update.go`.
+ *
+ * Both commands share one shape: `--format table` renders a hand-written human
+ * block, and every other format goes through `RenderObject` with an explicit
+ * column list. Neither command ever touches the credential store.
+ *
+ * Three details are load-bearing:
+ *
+ *   - **`update` renames two fields.** The updater's `assetName` is emitted as
+ *     the column `asset` and `executablePath` as `executable`. The rename IS
+ *     the output contract, so a naive spread would emit the wrong keys in both
+ *     JSON and TSV.
+ *   - **`goVersion` keeps its Go spelling.** DEVIATIONS G4: `--format json`
+ *     sorts keys alphabetically (arch, commit, date, goVersion, os, version)
+ *     while `--format tsv` uses declaration order (VERSION, COMMIT, DATE,
+ *     GOVERSION, OS, ARCH). The command must NOT re-sort the TSV columns; the
+ *     divergence is real and golden-verified against the Go binary.
+ *   - **`upToDate` is recomputed, not returned.** The frozen `UpdaterShape`
+ *     contract exposes `latestVersion` and has no `upToDate` flag, but the
+ *     table rendering needs it to choose between three sentences. It is
+ *     recovered with `compareVersions(latestVersion, currentVersion)` being
+ *     `{comparable: true, order: 0}` — the exact predicate `runUpdate` used to
+ *     set the flag in the first place (see impl/updater.ts `toUpdateResult`).
+ *
+ * `update --version ` shadows the framework's own `--version`, exactly as
+ * cobra's local-flag lookup did: leaf flags are resolved before built-ins.
+ */
+
+import { Effect, Stdio, Stream } from "effect"
+import { Command, Flag } from "../effect.ts"
+import { OperationalError } from "../domain/errors.ts"
+import type { JsonObject } from "../json/value.ts"
+import { compareVersions } from "../impl/semver.ts"
+import { updateColumns, versionColumns } from "../output/columns.ts"
+import {
+  AppOptions,
+  Renderer,
+  Updater,
+  VersionInfo,
+  type AppOptionsShape,
+  type OutputFormat
+} from "../services/index.ts"
+
+/**
+ * Raw stdout, for the human `table` renderings that bypass `Renderer`.
+ *
+ * Go wrote these with `fmt.Fprintf(a.Out, …)`, i.e. straight to the same
+ * writer `output.Render` used, so both must land on the same stream in the
+ * same order. Routing through `Stdio` rather than `Console.log` keeps that
+ * true and keeps the text capturable by `Stdio.layerTest` in tests.
+ */
+const writeOut = (text: string): Effect.Effect =>
+  Effect.gen(function* () {
+    const stdio = yield* Stdio.Stdio
+    yield* Stream.run(Stream.make(text), stdio.stdout()).pipe(
+      Effect.catch((cause) =>
+        Effect.fail(new OperationalError({ message: "could not write output", cause }))
+      )
+    )
+  })
+
+/** `--columns` when the user supplied any, else the command's default list. */
+const columnsFor = (
+  options: AppOptionsShape,
+  defaults: ReadonlyArray
+): ReadonlyArray => (options.columns.length > 0 ? options.columns : defaults)
+
+const isTable = (format: OutputFormat): boolean => format === "table"
+
+// ---------------------------------------------------------------------------
+// version
+// ---------------------------------------------------------------------------
+
+export const versionCommand = Command.make("version", {}, () =>
+  Effect.gen(function* () {
+    const options = yield* AppOptions
+    const versionInfo = yield* VersionInfo
+    const info = yield* versionInfo.get
+
+    if (!isTable(options.format)) {
+      const state: JsonObject = {
+        version: info.version,
+        commit: info.commit,
+        date: info.date,
+        goVersion: info.goVersion,
+        os: info.os,
+        arch: info.arch
+      }
+      const renderer = yield* Renderer
+      return yield* renderer.renderObject(state, {
+        format: options.format,
+        columns: columnsFor(options, versionColumns),
+        noHeader: options.noHeader
+      })
+    }
+
+    yield* writeOut(
+      `oytc ${info.version}\n` +
+        `commit: ${info.commit}\n` +
+        `built: ${info.date}\n` +
+        `go: ${info.goVersion} (${info.os}/${info.arch})\n`
+    )
+  })
+).pipe(Command.withDescription("Show version, commit, and build date"))
+
+// ---------------------------------------------------------------------------
+// update
+// ---------------------------------------------------------------------------
+
+const UPDATE_DESCRIPTION =
+  "Downloads the matching release archive and checksums.txt from GitHub Releases,\n" +
+  "verifies the archive's SHA-256, and atomically replaces the current executable.\n" +
+  "The updater never reads or transmits the YouTube API key.\n\n" +
+  "'oytc upgrade' is an alias, and the installer also provides oytc_update and\n" +
+  "oytc_upgrade shims that run the same operation."
+
+/**
+ * `result.UpToDate` recovered from the contract-shaped result.
+ *
+ * `runUpdate` sets the flag when `compareVersions(tag, current)` is comparable
+ * and equal, and returns early — so an up-to-date run also has `updated: false`
+ * and an empty `asset`. Recomputing the same predicate here is exact, not an
+ * approximation.
+ */
+export const isUpToDate = (latestVersion: string, currentVersion: string): boolean => {
+  const comparison = compareVersions(latestVersion, currentVersion)
+  return comparison.comparable && comparison.order === 0
+}
+
+export const updateCommand = Command.make(
+  "update",
+  {
+    check: Flag.boolean("check").pipe(
+      Flag.withDescription("only report whether a newer release exists")
+    ),
+    /**
+     * Shadows the framework's built-in `--version`. A plain string flag with an
+     * empty default, so "not passed" and "passed empty" coincide — which is
+     * what Go's zero-value string did.
+     */
+    targetVersion: Flag.string("version").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("install this exact release tag (e.g. v0.2.0) instead of the latest")
+    )
+  },
+  ({ check, targetVersion }) =>
+    Effect.gen(function* () {
+      const options = yield* AppOptions
+      const updater = yield* Updater
+      const result = yield* updater.run({ checkOnly: check, targetVersion })
+      const upToDate = isUpToDate(result.latestVersion, result.currentVersion)
+
+      if (!isTable(options.format)) {
+        // The two renames live here and nowhere else.
+        const state: JsonObject = {
+          currentVersion: result.currentVersion,
+          targetVersion: result.latestVersion,
+          updated: result.updated,
+          upToDate,
+          asset: result.asset,
+          executable: result.executable
+        }
+        const renderer = yield* Renderer
+        return yield* renderer.renderObject(state, {
+          format: options.format,
+          columns: columnsFor(options, updateColumns),
+          noHeader: options.noHeader
+        })
+      }
+
+      if (upToDate) {
+        return yield* writeOut(`oytc ${result.currentVersion} is already the latest release.\n`)
+      }
+      if (result.updated) {
+        return yield* writeOut(
+          `Updated ${result.currentVersion} -> ${result.latestVersion} (${result.executable})\n`
+        )
+      }
+      yield* writeOut(
+        `Update available: ${result.latestVersion} (current: ${result.currentVersion})\n` +
+          "Run 'oytc update' to install it.\n"
+      )
+    })
+).pipe(Command.withDescription(UPDATE_DESCRIPTION), Command.withAlias("upgrade"))
+
+/** Registered by the orchestrator in root.ts. */
+export const versionUpdateCommands = [versionCommand, updateCommand] as const
diff --git a/src/cli/video.test.ts b/src/cli/video.test.ts
new file mode 100644
index 0000000..e671409
--- /dev/null
+++ b/src/cli/video.test.ts
@@ -0,0 +1,668 @@
+import { describe, expect, test } from "bun:test"
+import { ApiError } from "../domain/errors.ts"
+import type { JsonValue } from "../json/value.ts"
+import {
+  expectUsage,
+  object,
+  pageOf,
+  responseOf,
+  runCli,
+  summaryLine
+} from "./p8aHarness.testutil.ts"
+import type { RunResult } from "./p8aHarness.testutil.ts"
+import {
+  videoCommand,
+  videoGetCommand,
+  videoPopularCommand,
+  videoStatsCommand,
+  videoTrainabilityCommand
+} from "./video.ts"
+
+/** The five-parameter Command generic differs per command; the harness only mounts it. */
+const cmd = (c: unknown) => c as never
+
+const get = (argv: ReadonlyArray, script = {}): Promise =>
+  runCli(cmd(videoGetCommand), argv, { script })
+
+const stats = (argv: ReadonlyArray, script = {}): Promise =>
+  runCli(cmd(videoStatsCommand), argv, { script })
+
+const popular = (argv: ReadonlyArray, script = {}): Promise =>
+  runCli(cmd(videoPopularCommand), argv, { script })
+
+const trainability = (argv: ReadonlyArray, script = {}): Promise =>
+  runCli(cmd(videoTrainabilityCommand), argv, { script })
+
+const ids = (count: number, prefix = "v"): ReadonlyArray =>
+  Array.from({ length: count }, (_, i) => `${prefix}${i}`)
+
+const videoItems = (values: ReadonlyArray): string =>
+  `[${values.map((id) => `{"id":${JSON.stringify(id)}}`).join(",")}]`
+
+// ---------------------------------------------------------------------------
+// video get
+// ---------------------------------------------------------------------------
+
+describe("video get — validation", () => {
+  test("G3: no arguments", async () => {
+    expectUsage(await get(["get"]), "expected at least 1 argument(s), received 0")
+  })
+
+  test("a forbidden part is rejected before any request", async () => {
+    expectUsage(
+      await get(["get", "--parts", "fileDetails", "abc"]),
+      'part "fileDetails" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  test("processingDetails and suggestions are forbidden too", async () => {
+    expectUsage(
+      await get(["get", "--parts", "snippet,processingDetails", "abc"]),
+      'part "processingDetails" requires owner/OAuth access and is not supported'
+    )
+    expectUsage(
+      await get(["get", "--parts", "suggestions", "abc"]),
+      'part "suggestions" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  test("the arg-count check fires BEFORE the parts check", async () => {
+    expectUsage(
+      await get(["get", "--parts", "fileDetails"]),
+      "expected at least 1 argument(s), received 0"
+    )
+  })
+
+  test("a normal part list is accepted", async () => {
+    const result = await get(["get", "--parts", "snippet", "abc"], {
+      get: [responseOf('[{"id":"abc"}]')]
+    })
+    expect(result.exitCode).toBe(0)
+  })
+})
+
+describe("video get — request assembly", () => {
+  test("the default parts and a single id", async () => {
+    const result = await get(["get", "abc"], { get: [responseOf('[{"id":"abc"}]')] })
+    expect(result.calls).toHaveLength(1)
+    expect(result.calls[0]!.resource).toBe("videos")
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet,contentDetails,statistics,status",
+      id: "abc"
+    })
+  })
+
+  test("--parts overrides the default", async () => {
+    const result = await get(["get", "--parts", "snippet", "abc"], {
+      get: [responseOf('[{"id":"abc"}]')]
+    })
+    expect(result.calls[0]!.params["part"]).toBe("snippet")
+  })
+
+  test("whitespace-only --parts falls back to the default", async () => {
+    const result = await get(["get", "--parts", "   ", "abc"], {
+      get: [responseOf('[{"id":"abc"}]')]
+    })
+    expect(result.calls[0]!.params["part"]).toBe("snippet,contentDetails,statistics,status")
+  })
+
+  test("--hl is forwarded", async () => {
+    const result = await get(["get", "--hl", "fr", "abc"], {
+      get: [responseOf('[{"id":"abc"}]')]
+    })
+    expect(result.calls[0]!.params["hl"]).toBe("fr")
+  })
+
+  test("an empty --hl is NOT sent at all", async () => {
+    const result = await get(["get", "abc"], { get: [responseOf('[{"id":"abc"}]')] })
+    expect(result.calls[0]!.params).not.toHaveProperty("hl")
+    expect(result.calls[0]!.params).not.toHaveProperty("fields")
+  })
+
+  test("ids are comma-joined into one request", async () => {
+    const result = await get(["get", "a", "b", "c"], {
+      get: [responseOf('[{"id":"a"},{"id":"b"},{"id":"c"}]')]
+    })
+    expect(result.calls).toHaveLength(1)
+    expect(result.calls[0]!.params["id"]).toBe("a,b,c")
+  })
+})
+
+describe("video get — batching at 50", () => {
+  test("exactly 50 ids is ONE request", async () => {
+    const requested = ids(50)
+    const result = await get(["get", ...requested], {
+      get: [responseOf(videoItems(requested))]
+    })
+    expect(result.calls).toHaveLength(1)
+    expect(result.exitCode).toBe(0)
+  })
+
+  test("51 ids is TWO requests, split 50/1", async () => {
+    const requested = ids(51)
+    const result = await get(["get", ...requested], {
+      get: [responseOf(videoItems(requested.slice(0, 50))), responseOf(videoItems(requested.slice(50)))]
+    })
+    expect(result.calls).toHaveLength(2)
+    expect(result.calls[0]!.params["id"]!.split(",")).toHaveLength(50)
+    expect(result.calls[1]!.params["id"]).toBe("v50")
+  })
+
+  test("101 ids is THREE requests and requests counts batches, not ids", async () => {
+    const requested = ids(101)
+    const result = await get(["get", ...requested], {
+      get: [
+        responseOf(videoItems(requested.slice(0, 50))),
+        responseOf(videoItems(requested.slice(50, 100))),
+        responseOf(videoItems(requested.slice(100)))
+      ]
+    })
+    expect(result.calls).toHaveLength(3)
+    expect(result.stderr).toBe(summaryLine(101, 3))
+  })
+
+  test("items are concatenated in batch order", async () => {
+    const requested = ids(51)
+    const result = await get(["get", "--format", "jsonl", ...requested], {
+      get: [responseOf(videoItems(requested.slice(0, 50))), responseOf(videoItems(requested.slice(50)))]
+    })
+    const lines = result.stdout.trim().split("\n")
+    expect(lines).toHaveLength(51)
+    expect(lines[0]).toBe('{"id":"v0"}')
+    expect(lines[50]).toBe('{"id":"v50"}')
+  })
+})
+
+describe("video get — validateRequestedItems", () => {
+  test("a missing id fails with exit 4 and the comma-space joined list", async () => {
+    const result = await get(["get", "a", "b"], { get: [responseOf('[{"id":"a"}]')] })
+    expect(result.exitCode).toBe(4)
+    expect(result.message).toBe("videos not found: b")
+  })
+
+  test("several missing ids keep the requested order", async () => {
+    const result = await get(["get", "a", "b", "c"], {
+      get: [responseOf('[{"id":"b"}]')]
+    })
+    expect(result.message).toBe("videos not found: a, c")
+  })
+
+  test("duplicate requested ids are de-duplicated for the report", async () => {
+    const result = await get(["get", "a", "a", "b"], {
+      get: [responseOf('[{"id":"a"}]')]
+    })
+    expect(result.message).toBe("videos not found: b")
+  })
+
+  test("a duplicate id that IS returned passes", async () => {
+    const result = await get(["get", "a", "a"], { get: [responseOf('[{"id":"a"}]')] })
+    expect(result.exitCode).toBe(0)
+  })
+
+  test("the escape hatch: no recoverable ids but equal cardinality passes", async () => {
+    // A --fields selector that keeps ids out of the response entirely.
+    const result = await get(["get", "--fields", "items/snippet/title", "a", "b"], {
+      get: [responseOf('[{"snippet":{"title":"one"}},{"snippet":{"title":"two"}}]')]
+    })
+    expect(result.exitCode).toBe(0)
+  })
+
+  test("no recoverable ids AND fewer items reports every requested id", async () => {
+    const result = await get(["get", "--fields", "items/snippet/title", "a", "b"], {
+      get: [responseOf('[{"snippet":{"title":"one"}}]')]
+    })
+    expect(result.exitCode).toBe(4)
+    expect(result.message).toBe("videos not found: a, b")
+  })
+
+  test("no recoverable ids and MORE items than requested passes", async () => {
+    // returned.size === 0 and items.length > unique.length: neither branch
+    // populates `missing`, so Go accepts.
+    const result = await get(["get", "--fields", "items/snippet/title", "a"], {
+      get: [responseOf('[{"snippet":{"title":"one"}},{"snippet":{"title":"two"}}]')]
+    })
+    expect(result.exitCode).toBe(0)
+  })
+
+  test("an empty-string id in the response does not count as recoverable", async () => {
+    const result = await get(["get", "a"], { get: [responseOf('[{"id":""}]')] })
+    // returned stays empty, cardinality matches -> the escape hatch accepts.
+    expect(result.exitCode).toBe(0)
+  })
+})
+
+describe("video get — --fields injection and stripping", () => {
+  test("no --fields sends no fields param and keeps id", async () => {
+    const result = await get(["get", "--format", "jsonl", "abc"], {
+      get: [responseOf('[{"id":"abc","snippet":{"title":"T"}}]')]
+    })
+    expect(result.calls[0]!.params).not.toHaveProperty("fields")
+    expect(result.stdout).toBe('{"id":"abc","snippet":{"title":"T"}}\n')
+  })
+
+  test("a non-covering selector gets items/id appended, then stripped from output", async () => {
+    const result = await get(
+      ["get", "--fields", "items/snippet/title", "--format", "jsonl", "abc"],
+      { get: [responseOf('[{"id":"abc","snippet":{"title":"T"}}]')] }
+    )
+    expect(result.calls[0]!.params["fields"]).toBe("items/snippet/title,items/id")
+    // The injected id must not reach the user.
+    expect(result.stdout).toBe('{"snippet":{"title":"T"}}\n')
+  })
+
+  test("a selector that already covers items/id is sent unchanged and NOT stripped", async () => {
+    const result = await get(
+      ["get", "--fields", "items/id,items/snippet/title", "--format", "jsonl", "abc"],
+      { get: [responseOf('[{"id":"abc","snippet":{"title":"T"}}]')] }
+    )
+    expect(result.calls[0]!.params["fields"]).toBe("items/id,items/snippet/title")
+    expect(result.stdout).toBe('{"id":"abc","snippet":{"title":"T"}}\n')
+  })
+
+  test("a deeper selector also counts as covering", async () => {
+    const result = await get(["get", "--fields", "items/id/videoId", "abc"], {
+      get: [responseOf('[{"id":"abc"}]')]
+    })
+    expect(result.calls[0]!.params["fields"]).toBe("items/id/videoId")
+  })
+
+  test("the same injected selector goes to EVERY batch", async () => {
+    const requested = ids(51)
+    const result = await get(["get", "--fields", "items/snippet/title", ...requested], {
+      get: [
+        responseOf(videoItems(requested.slice(0, 50))),
+        responseOf(videoItems(requested.slice(50)))
+      ]
+    })
+    expect(result.calls[0]!.params["fields"]).toBe("items/snippet/title,items/id")
+    expect(result.calls[1]!.params["fields"]).toBe("items/snippet/title,items/id")
+  })
+})
+
+describe("video get — rendering", () => {
+  test("the default table columns", async () => {
+    const result = await get(["get", "--format", "tsv", "abc"], {
+      get: [
+        responseOf(
+          '[{"id":"abc","snippet":{"title":"T","channelTitle":"C"},"contentDetails":{"duration":"PT1M"},"statistics":{"viewCount":"5"}}]'
+        )
+      ]
+    })
+    expect(result.stdout).toBe(
+      "ID\tSNIPPET.TITLE\tSNIPPET.CHANNELTITLE\tCONTENTDETAILS.DURATION\tSTATISTICS.VIEWCOUNT\n" +
+        "abc\tT\tC\tPT1M\t5\n"
+    )
+  })
+
+  test("--columns overrides the defaults", async () => {
+    const result = await get(["get", "--format", "tsv", "--columns", "id", "abc"], {
+      get: [responseOf('[{"id":"abc"}]')]
+    })
+    expect(result.stdout).toBe("ID\nabc\n")
+  })
+
+  test("--quiet drops the stderr summary", async () => {
+    const result = await get(["get", "--quiet", "abc"], {
+      get: [responseOf('[{"id":"abc"}]')]
+    })
+    expect(result.stderr).toBe("")
+  })
+
+  test("a large counter keeps its exact literal (no float rounding)", async () => {
+    const result = await get(["get", "--format", "json", "abc"], {
+      get: [responseOf('[{"id":"abc","statistics":{"viewCount":9007199254740993123}}]')]
+    })
+    expect(result.stdout).toContain("9007199254740993123")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// video stats
+// ---------------------------------------------------------------------------
+
+describe("video stats", () => {
+  test("its default part is just statistics", async () => {
+    const result = await stats(["stats", "abc"], { get: [responseOf('[{"id":"abc"}]')] })
+    expect(result.calls[0]!.params["part"]).toBe("statistics")
+  })
+
+  test("its own default columns", async () => {
+    const result = await stats(["stats", "--format", "tsv", "abc"], {
+      get: [
+        responseOf('[{"id":"abc","statistics":{"viewCount":"1","likeCount":"2","commentCount":"3"}}]')
+      ]
+    })
+    expect(result.stdout).toBe(
+      "ID\tSTATISTICS.VIEWCOUNT\tSTATISTICS.LIKECOUNT\tSTATISTICS.COMMENTCOUNT\nabc\t1\t2\t3\n"
+    )
+  })
+
+  test("it shares get's validation", async () => {
+    expectUsage(await stats(["stats"]), "expected at least 1 argument(s), received 0")
+    expectUsage(
+      await stats(["stats", "--parts", "fileDetails", "a"]),
+      'part "fileDetails" requires owner/OAuth access and is not supported'
+    )
+  })
+
+  test("it shares get's batching and validateRequestedItems", async () => {
+    const result = await stats(["stats", "a", "b"], { get: [responseOf('[{"id":"a"}]')] })
+    expect(result.exitCode).toBe(4)
+    expect(result.message).toBe("videos not found: b")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// video popular
+// ---------------------------------------------------------------------------
+
+describe("video popular — validation", () => {
+  test("it accepts no positional arguments", async () => {
+    expectUsage(
+      await popular(["popular", "extra"]),
+      "expected 0 argument(s), received 1"
+    )
+  })
+
+  test("G3: --page-size bounds", async () => {
+    expectUsage(
+      await popular(["popular", "--page-size", "99"]),
+      "--page-size must be between 1 and 50"
+    )
+    expectUsage(
+      await popular(["popular", "--page-size", "0"]),
+      "--page-size must be between 1 and 50"
+    )
+  })
+
+  test("G3: --limit cannot be negative", async () => {
+    expectUsage(await popular(["popular", "--limit=-1"]), "--limit cannot be negative")
+  })
+
+  test("the arg count is checked before pagination", async () => {
+    expectUsage(
+      await popular(["popular", "--page-size", "99", "extra"]),
+      "expected 0 argument(s), received 1"
+    )
+  })
+
+  test("pagination is checked before the parts check", async () => {
+    expectUsage(
+      await popular(["popular", "--page-size", "99", "--parts", "fileDetails"]),
+      "--page-size must be between 1 and 50"
+    )
+  })
+
+  test("a forbidden part is rejected", async () => {
+    expectUsage(
+      await popular(["popular", "--parts", "fileDetails"]),
+      'part "fileDetails" requires owner/OAuth access and is not supported'
+    )
+  })
+})
+
+describe("video popular — request assembly", () => {
+  test("chart, region and the default parts", async () => {
+    const result = await popular(["popular"], { pages: [pageOf('[{"id":"a"}]')] })
+    expect(result.calls[0]!.resource).toBe("videos")
+    expect(result.calls[0]!.params).toEqual({
+      part: "snippet,contentDetails,statistics",
+      chart: "mostPopular",
+      regionCode: "US"
+    })
+  })
+
+  test("--region overrides the US default", async () => {
+    const result = await popular(["popular", "--region", "GB"], {
+      pages: [pageOf('[{"id":"a"}]')]
+    })
+    expect(result.calls[0]!.params["regionCode"]).toBe("GB")
+  })
+
+  test("an explicitly empty --region is dropped, matching setValues", async () => {
+    const result = await popular(["popular", "--region", ""], {
+      pages: [pageOf('[{"id":"a"}]')]
+    })
+    expect(result.calls[0]!.params).not.toHaveProperty("regionCode")
+  })
+
+  test("--category becomes videoCategoryId", async () => {
+    const result = await popular(["popular", "--category", "10"], {
+      pages: [pageOf('[{"id":"a"}]')]
+    })
+    expect(result.calls[0]!.params["videoCategoryId"]).toBe("10")
+  })
+
+  test("the page options carry the defaults", async () => {
+    const result = await popular(["popular"], { pages: [pageOf('[{"id":"a"}]')] })
+    expect(result.calls[0]!.page).toEqual({
+      all: false,
+      limit: 0,
+      pageSize: 25,
+      pageToken: "",
+      filter: undefined
+    })
+  })
+
+  test("--all, --limit, --page-size and --page-token reach the page options", async () => {
+    const result = await popular(
+      ["popular", "--all", "--limit", "3", "--page-size", "2", "--page-token", "T"],
+      { pages: [pageOf('[{"id":"a"},{"id":"b"}]', "N"), pageOf('[{"id":"c"},{"id":"d"}]', "M")] }
+    )
+    expect(result.calls[0]!.page).toEqual({
+      all: true,
+      limit: 3,
+      pageSize: 2,
+      pageToken: "T",
+      filter: undefined
+    })
+  })
+
+  test("popular does NOT inject a fields selector — it is not a batch get", async () => {
+    const result = await popular(["popular", "--fields", "items/snippet/title"], {
+      pages: [pageOf('[{"snippet":{"title":"T"}}]')]
+    })
+    expect(result.calls[0]!.params["fields"]).toBe("items/snippet/title")
+  })
+})
+
+describe("video popular — pagination", () => {
+  test("without --all exactly one request is made even with a next token", async () => {
+    const result = await popular(["popular"], {
+      pages: [pageOf('[{"id":"a"}]', "NEXT")]
+    })
+    expect(result.calls).toHaveLength(1)
+    expect(result.stderr).toBe(summaryLine(1, 1, "NEXT"))
+  })
+
+  test("--all follows tokens until one is empty", async () => {
+    const result = await popular(["popular", "--all"], {
+      pages: [pageOf('[{"id":"a"}]', "N"), pageOf('[{"id":"b"}]', "")]
+    })
+    expect(result.calls).toHaveLength(2)
+    expect(result.stderr).toBe(summaryLine(2, 2))
+  })
+
+  test("D2: a truncating --limit reports no resume token", async () => {
+    const result = await popular(["popular", "--all", "--limit", "3"], {
+      pages: [pageOf('[{"id":"a"},{"id":"b"}]', "N"), pageOf('[{"id":"c"},{"id":"d"}]', "unused")]
+    })
+    // 3 kept, 2 requests, and the token is suppressed because item d was
+    // discarded — DEVIATIONS.md D2.
+    expect(result.stderr).toBe(summaryLine(3, 2))
+  })
+
+  test("a limit landing exactly on a page boundary keeps its token", async () => {
+    const result = await popular(["popular", "--all", "--limit", "2"], {
+      pages: [pageOf('[{"id":"a"},{"id":"b"}]', "N")]
+    })
+    expect(result.stderr).toBe(summaryLine(2, 1, "N"))
+  })
+
+  test("the default columns", async () => {
+    const result = await popular(["popular", "--format", "tsv"], {
+      pages: [
+        pageOf('[{"id":"a","snippet":{"title":"T","channelTitle":"C"},"statistics":{"viewCount":"9"}}]')
+      ]
+    })
+    expect(result.stdout).toBe(
+      "ID\tSNIPPET.TITLE\tSNIPPET.CHANNELTITLE\tSTATISTICS.VIEWCOUNT\na\tT\tC\t9\n"
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// video trainability
+// ---------------------------------------------------------------------------
+
+describe("video trainability", () => {
+  test("exactly one argument is required", async () => {
+    expectUsage(
+      await trainability(["trainability"]),
+      "expected 1 argument(s), received 0"
+    )
+    expectUsage(
+      await trainability(["trainability", "a", "b"]),
+      "expected 1 argument(s), received 2"
+    )
+  })
+
+  test("it is UNAUTHENTICATED and sends only id — no part, no key", async () => {
+    const result = await trainability(["trainability", "abc"], {
+      json: [object('{"videoId":"abc","permitted":["None"]}')]
+    })
+    expect(result.calls).toHaveLength(1)
+    expect(result.calls[0]!.kind).toBe("getJson")
+    expect(result.calls[0]!.resource).toBe("videoTrainability")
+    expect(result.calls[0]!.authenticate).toBe(false)
+    expect(result.calls[0]!.params).toEqual({ id: "abc" })
+  })
+
+  test("it renders a bare object with the default columns and NO summary line", async () => {
+    const result = await trainability(["trainability", "--format", "tsv", "abc"], {
+      json: [object('{"videoId":"abc","permitted":["None"]}')]
+    })
+    // Matches the real binary byte for byte.
+    expect(result.stdout).toBe("VIDEOID\tPERMITTED\nabc\tNone\n")
+    expect(result.stderr).toBe("")
+  })
+
+  test("G1: the permitted array comma-joins with no brackets or quotes", async () => {
+    const result = await trainability(["trainability", "--format", "tsv", "abc"], {
+      json: [object('{"videoId":"abc","permitted":["None","Other"]}')]
+    })
+    expect(result.stdout).toBe("VIDEOID\tPERMITTED\nabc\tNone,Other\n")
+  })
+
+  test("G4: json output sorts keys", async () => {
+    const result = await trainability(["trainability", "--format", "json", "abc"], {
+      json: [object('{"videoId":"abc","kind":"youtube#videoTrainability","etag":"E"}')]
+    })
+    expect(result.stdout).toBe(
+      '{\n  "etag": "E",\n  "kind": "youtube#videoTrainability",\n  "videoId": "abc"\n}\n'
+    )
+  })
+
+  test("no envelope: there is no items/requests wrapper", async () => {
+    const result = await trainability(["trainability", "--format", "json", "abc"], {
+      json: [object('{"videoId":"abc"}')]
+    })
+    expect(result.stdout).not.toContain("items")
+    expect(result.stdout).not.toContain("requests")
+  })
+
+  test("a transport failure propagates with its own exit code", async () => {
+    const result = await trainability(["trainability", "abc"], {
+      failJson: new ApiError({
+        httpStatus: 404,
+        code: 404,
+        apiMessage: "Not Found",
+        reasons: []
+      })
+    })
+    expect(result.exitCode).toBe(4)
+  })
+
+  // json.Unmarshal into map[string]any, measured against the binary through an
+  // intercepting server. Each of these was a real mismatch before the fix.
+  describe("non-object bodies follow json.Unmarshal, not a blanket reject", () => {
+    test.each([
+      ["a string", "string"],
+      [42, "number"],
+      [true, "bool"],
+      [false, "bool"]
+    ])("%p is a decode failure at exit 6", async (body, kind) => {
+      const result = await trainability(["trainability", "abc"], {
+        json: [body as JsonValue]
+      })
+      expect(result.exitCode).toBe(6)
+      expect(result.message).toBe(
+        `decode YouTube API response: json: cannot unmarshal ${kind} into Go value of type map[string]interface {}`
+      )
+    })
+
+    test("an array reports kind 'array'", async () => {
+      const result = await trainability(["trainability", "abc"], { json: [[1, 2]] })
+      expect(result.exitCode).toBe(6)
+      expect(result.message).toBe(
+        "decode YouTube API response: json: cannot unmarshal array into Go value of type map[string]interface {}"
+      )
+    })
+
+    // Go unmarshals `null` into a NIL MAP and renders it, exiting 0. A nil map
+    // re-encodes as `null`, NOT as `{}` — verified against the binary.
+    test.each([
+      ["json", "null\n"],
+      ["jsonl", "null\n"],
+      ["tsv", "VIDEOID\tPERMITTED\n\t\n"]
+    ])("null renders as null in %s and exits 0", async (format, expected) => {
+      const result = await trainability(
+        ["trainability", "--format", format, "abc"],
+        { json: [null] }
+      )
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toBe(expected)
+      expect(result.stderr).toBe("")
+    })
+
+    test("null in table format matches the binary byte for byte", async () => {
+      const result = await trainability(["trainability", "abc"], { json: [null] })
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toBe("VIDEOID  PERMITTED\n         \n")
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// the group
+// ---------------------------------------------------------------------------
+
+describe("video — the group command", () => {
+  test("bare `oytc video` prints help and exits 0", async () => {
+    const result = await runCli(cmd(videoCommand), ["video"])
+    expect(result.exitCode).toBe(0)
+    expect(result.calls).toHaveLength(0)
+  })
+
+  test("every leaf is reachable through the group", async () => {
+    const result = await runCli(cmd(videoCommand), ["video", "get", "abc"], {
+      script: { get: [responseOf('[{"id":"abc"}]')] }
+    })
+    expect(result.exitCode).toBe(0)
+    expect(result.calls[0]!.resource).toBe("videos")
+  })
+
+  test("popular through the group", async () => {
+    const result = await runCli(cmd(videoCommand), ["video", "popular"], {
+      script: { pages: [pageOf('[{"id":"a"}]')] }
+    })
+    expect(result.exitCode).toBe(0)
+  })
+
+  test("trainability through the group", async () => {
+    const result = await runCli(cmd(videoCommand), ["video", "trainability", "abc"], {
+      script: { json: [object('{"videoId":"abc"}')] }
+    })
+    expect(result.exitCode).toBe(0)
+  })
+})
diff --git a/src/cli/video.ts b/src/cli/video.ts
index ca14f9a..62af4e9 100644
--- a/src/cli/video.ts
+++ b/src/cli/video.ts
@@ -1,2 +1,279 @@
-/** STUB — implemented in a later package. */
-export {}
+/**
+ * `oytc video {get,stats,popular,trainability}`.
+ *
+ * Ports `videoGetCommand(false)`, `videoGetCommand(true)`, `videoPopularCommand`
+ * and `videoTrainabilityCommand` from `internal/cli/channel_video.go`.
+ *
+ * `get` and `stats` are ONE Go constructor parameterised by a boolean; they are
+ * built the same way here, so the batching, `--fields` injection and
+ * `validateRequestedItems` logic cannot drift between them.
+ */
+
+import { Effect, Option } from "effect"
+import { Argument, Command, Flag } from "../effect.ts"
+import { OperationalError } from "../domain/errors.ts"
+import type { OytcError } from "../domain/errors.ts"
+import type { ListResult } from "../domain/listResult.ts"
+import type { JsonObject, JsonValue } from "../json/value.ts"
+import { DEFAULT_BASE_URL } from "../impl/httpCore.ts"
+import {
+  videoGetColumns,
+  videoPopularColumns,
+  videoStatsColumns,
+  videoTrainabilityColumns
+} from "../output/columns.ts"
+import { HttpCore, YouTubeApi } from "../services/index.ts"
+import type { Params, YouTubeApiShape } from "../services/index.ts"
+import { fieldsWithRequired, stripItemIds } from "./fields.ts"
+import { renderObject, renderResult } from "./render.ts"
+import {
+  apiFlagsWithHl,
+  BATCH_SIZE,
+  batch,
+  exactArgs,
+  firstFailure,
+  listFlags,
+  minimumArgs,
+  pageOptionsOf,
+  partsOr,
+  raise,
+  setValues,
+  validatePagination,
+  validateParts,
+  validateRequestedItems
+} from "./validate.ts"
+
+/**
+ * Parts that require owner/OAuth access. The same list for `get`, `stats` and
+ * `popular`, because all three hit the `videos` resource.
+ */
+const FORBIDDEN_VIDEO_PARTS = ["fileDetails", "processingDetails", "suggestions"]
+
+/**
+ * The kind name `encoding/json` uses in an `UnmarshalTypeError`. Go names the
+ * JSON kind, not the Go type: both booleans are "bool" and every number is
+ * "number". `null` never reaches here — it unmarshals successfully.
+ */
+const goJsonKind = (value: JsonValue): string => {
+  if (Array.isArray(value)) return "array"
+  if (typeof value === "string") return "string"
+  if (typeof value === "number") return "number"
+  return "bool"
+}
+
+// ---------------------------------------------------------------------------
+// video get / video stats
+// ---------------------------------------------------------------------------
+
+/**
+ * The shared body of `get` and `stats`: batch the IDs 50 at a time, concatenate
+ * every page in batch order, assert nothing went missing, then strip the
+ * injected `items/id` if one was injected.
+ *
+ * `requests` counts one per BATCH, not one per ID.
+ */
+const runVideoBatchGet = (
+  ids: ReadonlyArray,
+  parts: string,
+  api: { readonly fields: string; readonly hl: string }
+): Effect.Effect =>
+  Effect.gen(function* () {
+    const youtube = yield* YouTubeApi
+    const { fields: requestFields, preserve: preserveId } = fieldsWithRequired(
+      api.fields,
+      "items/id"
+    )
+
+    const collected: Array = []
+    let requests = 0
+
+    for (const group of batch(ids, BATCH_SIZE)) {
+      const params: Params = setValues(
+        [
+          ["part", parts],
+          ["id", group.join(",")]
+        ],
+        { hl: api.hl, fields: requestFields }
+      )
+      const response = yield* youtube.get("videos", params)
+      requests++
+      collected.push(...((response.items ?? []) as ReadonlyArray))
+    }
+
+    yield* validateRequestedItems("videos", ids, collected)
+
+    return {
+      items: stripItemIds(collected, preserveId),
+      nextPageToken: "",
+      requests
+    }
+  })
+
+const videoBatchCommand = (kind: "get" | "stats") => {
+  const isStats = kind === "stats"
+  const defaultParts = isStats ? "statistics" : "snippet,contentDetails,statistics,status"
+  const columns = isStats ? videoStatsColumns : videoGetColumns
+  const description = isStats ? "Get video counters" : "Get videos by ID"
+
+  return Command.make(
+    kind,
+    {
+      ids: Argument.string("VIDEO_ID").pipe(
+        Argument.withDescription("YouTube video IDs"),
+        Argument.variadic()
+      ),
+      ...apiFlagsWithHl
+    },
+    ({ ids, ...api }) =>
+      Effect.gen(function* () {
+        const parts = partsOr(api.parts, defaultParts)
+        // Arg count first, then the semantic check — Go's order.
+        const invalid = firstFailure([
+          minimumArgs(1, ids.length),
+          validateParts(parts, FORBIDDEN_VIDEO_PARTS)
+        ])
+        if (Option.isSome(invalid)) return yield* raise(invalid.value)
+
+        const result = yield* runVideoBatchGet(ids, parts, api)
+        yield* renderResult(result, columns)
+      })
+  ).pipe(Command.withDescription(description))
+}
+
+export const videoGetCommand = videoBatchCommand("get")
+export const videoStatsCommand = videoBatchCommand("stats")
+
+// ---------------------------------------------------------------------------
+// video popular
+// ---------------------------------------------------------------------------
+
+/**
+ * `--region` defaults to `US` and, unlike most flags here, is ALWAYS sent —
+ * `setValues` only skips empty strings, and the default is not empty.
+ */
+export const videoPopularCommand = Command.make(
+  "popular",
+  {
+    // `video popular` takes no positionals, and Go rejects extras with
+    // `expected 0 argument(s), received N`. A variadic argument is the only way
+    // to observe them and reproduce that message; the framework would otherwise
+    // ignore them silently.
+    extra: Argument.string("").pipe(Argument.variadic()),
+    ...listFlags({ pageSize: 25 }),
+    ...apiFlagsWithHl,
+    region: Flag.string("region").pipe(
+      Flag.withDefault("US"),
+      Flag.withDescription("ISO 3166-1 alpha-2 chart region")
+    ),
+    category: Flag.string("category").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("video category ID")
+    )
+  },
+  ({ extra, region, category, ...rest }) =>
+    Effect.gen(function* () {
+      const parts = partsOr(rest.parts, "snippet,contentDetails,statistics")
+      const invalid = firstFailure([
+        exactArgs(0, extra.length),
+        validatePagination(rest, 50),
+        validateParts(parts, FORBIDDEN_VIDEO_PARTS)
+      ])
+      if (Option.isSome(invalid)) return yield* raise(invalid.value)
+
+      const youtube = yield* YouTubeApi
+      const params: Params = setValues(
+        [
+          ["part", parts],
+          ["chart", "mostPopular"]
+        ],
+        { regionCode: region, videoCategoryId: category, hl: rest.hl, fields: rest.fields }
+      )
+      const result = yield* youtube.list("videos", params, pageOptionsOf(rest))
+      yield* renderResult(result, videoPopularColumns)
+    })
+).pipe(Command.withDescription("List the most popular videos"))
+
+// ---------------------------------------------------------------------------
+// video trainability
+// ---------------------------------------------------------------------------
+
+/**
+ * The ONLY unauthenticated endpoint, and the only command that bypasses
+ * `YouTubeApi` entirely.
+ *
+ * Go calls `client.GetJSON(ctx, "videoTrainability", …, authenticate=false, …)`
+ * — no API key, no bearer, no `part` param, and no list envelope: it decodes
+ * into a bare `map[string]any` and renders it through `RenderObject`.
+ * `YouTubeApi.get` always authenticates and always decodes the envelope, so
+ * this reaches for `HttpCore` directly, which is exactly the seam
+ * `authenticate: false` exists for.
+ *
+ * NON-OBJECT BODIES follow `json.Unmarshal` into a `map[string]any`, which is
+ * NOT simply "reject everything that is not an object" — measured against the
+ * binary through an intercepting server:
+ *
+ *   `null`             -> SUCCEEDS, leaving the map NIL. Go re-encodes a nil
+ *                         map as `null` (NOT `{}`) in json/jsonl, and the
+ *                         table/TSV writers find no keys and emit a header plus
+ *                         one blank row. So `null` is rendered, not rejected.
+ *   array/string/       -> `decode YouTube API response: json: cannot unmarshal
+ *   number/bool             into Go value of type map[string]interface {}`,
+ *                         an OperationalError at exit 6 — not a NotFoundError
+ *                         at exit 4.
+ *
+ * Go's kind names come from `reflect`, so a JSON array is "array", a string is
+ * "string", any number is "number" and both booleans are "bool".
+ */
+export const videoTrainabilityCommand = Command.make(
+  "trainability",
+  {
+    ids: Argument.string("VIDEO_ID").pipe(
+      Argument.withDescription("YouTube video ID"),
+      Argument.variadic()
+    )
+  },
+  ({ ids }) =>
+    Effect.gen(function* () {
+      const invalid = exactArgs(1, ids.length)
+      if (Option.isSome(invalid)) return yield* raise(invalid.value)
+
+      const core = yield* HttpCore
+      const body = yield* core.getJson({
+        baseUrl: DEFAULT_BASE_URL,
+        resource: "videoTrainability",
+        params: [["id", ids[0]!]],
+        authenticate: false
+      })
+      // `null` unmarshals into a NIL map, which Go's encoder writes back as
+      // `null` (not `{}`), while the table/TSV writers see no keys and emit a
+      // header plus one blank row. The renderer reproduces all four formats
+      // byte for byte from `null` itself, so it is passed straight through.
+      if (body === null) {
+        yield* renderObject(null as unknown as JsonObject, videoTrainabilityColumns)
+        return
+      }
+      if (typeof body !== "object" || Array.isArray(body)) {
+        return yield* Effect.fail(
+          new OperationalError({
+            message: `decode YouTube API response: json: cannot unmarshal ${goJsonKind(body)} into Go value of type map[string]interface {}`
+          })
+        )
+      }
+      yield* renderObject(body as JsonObject, videoTrainabilityColumns)
+    })
+).pipe(Command.withDescription("Get third-party AI trainability (no key or quota required)"))
+
+// ---------------------------------------------------------------------------
+// The group
+// ---------------------------------------------------------------------------
+
+/** A group command with NO handler: `oytc video` prints help and exits 0. */
+export const videoCommand = Command.make("video").pipe(
+  Command.withDescription("Read videos, statistics, charts, and trainability"),
+  Command.withSubcommands([
+    videoGetCommand,
+    videoStatsCommand,
+    videoPopularCommand,
+    videoTrainabilityCommand
+  ])
+)
diff --git a/src/main.ts b/src/main.ts
index 1bc4b31..ae2fe1a 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -1,16 +1,25 @@
 /**
  * Entrypoint.
  *
- * Errors are printed as exactly one line: `oytc: ` on stderr, with no
- * usage block, stack, or color — matching the Go implementation, which routed
- * every failure through a single printer with SilenceErrors/SilenceUsage.
+ * Every failure is printed as exactly one line — `oytc: ` on stderr —
+ * with no usage block, stack trace, or color. Go achieved this by setting
+ * cobra's SilenceErrors/SilenceUsage and routing every error through a single
+ * printer in main().
  *
- * Exit codes come from `Runtime.errorExitCode` on each tagged error, which
- * BunRuntime.runMain reads off the squashed error. The one translation needed
- * is for the CLI framework's own parse failures: it exits 1 where Go exits 2.
+ * Reproducing it here takes two pieces:
+ *
+ *   1. Every tagged error carries `Runtime.errorReported = false`, which stops
+ *      the runtime's default (multi-line, annotated) reporter from firing.
+ *      That alone leaves stderr EMPTY, so...
+ *   2. ...this file installs the printer. `Effect.tapErrorCause` catches the
+ *      failure on its way out, writes the single line, and re-fails so the
+ *      exit code still comes from `Runtime.errorExitCode`.
+ *
+ * The CLI framework's own parse errors need translating: it exits 1 where Go
+ * exits 2, and its messages differ in wording. Both are handled below.
  */
 
-import { Effect, Layer } from "effect"
+import { Cause, Effect, Layer, Runtime } from "effect"
 import { BunRuntime, BunServices } from "@effect/platform-bun"
 import { Command } from "./effect.ts"
 import { AppLayer } from "./layers.ts"
@@ -19,6 +28,110 @@ import { resolveVersionDetails } from "./impl/versionInfo.ts"
 
 const cli = Command.run(root, { version: resolveVersionDetails().version })
 
+/**
+ * Translate the CLI framework's own parse errors into Go's wording.
+ *
+ * The framework reports these with a multi-line help dump; Go emits one line.
+ * Only the cases a user can actually hit are translated — anything else falls
+ * through to the framework's message, which is still printed as a single line.
+ */
+const frameworkMessage = (error: {
+  readonly _tag?: unknown
+  readonly errors?: ReadonlyArray
+  readonly option?: unknown
+  readonly subcommand?: unknown
+  readonly value?: unknown
+}): string | undefined => {
+  const nested = error.errors
+  if (Array.isArray(nested) && nested.length > 0) {
+    // ShowHelp wraps the real parse failures. Report the first one that
+    // translates: a single user mistake can produce several framework errors
+    // (a `--limit -1` yields both a missing-value and an unrecognized-flag),
+    // and Go reports only the underlying cause.
+    for (const candidate of nested) {
+      const translated = frameworkMessage(candidate as never)
+      if (translated !== undefined) return translated
+    }
+    return undefined
+  }
+  switch (error._tag) {
+    // NOTE: the framework spells this tag with one "m" — "UnknownSubcomand".
+    // Both spellings are matched so a future upstream fix does not silently
+    // reintroduce the generic "Help requested" message.
+    case "UnknownSubcomand":
+    case "UnknownSubcommand":
+      return `unknown command ${goQuote(String(error.subcommand ?? ""))} for "oytc"`
+    case "UnrecognizedOption": {
+      const option = String(error.option ?? "")
+      // `--limit -1` lexes as two flags: a valueless --limit, then "-1" as an
+      // unrecognized flag. Go's pflag accepts the negative value, so report the
+      // range error the user actually tripped rather than a lexer artifact.
+      if (/^-\d/.test(option)) return "--limit cannot be negative"
+      return `unknown flag: ${option}`
+    }
+    case "InvalidValue": {
+      // The only enum flag on the root is --format, whose Go message is bespoke.
+      if (String(error.option ?? "").includes("format")) {
+        return `unsupported format ${goQuote(String(error.value ?? ""))} (use table, json, jsonl, or tsv)`
+      }
+      return undefined
+    }
+    default:
+      return undefined
+  }
+}
+
+/** Go's %q for the strings that reach these messages (plain identifiers). */
+const goQuote = (value: string): string => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`
+
+/**
+ * The single-line message for a failure, mirroring Go's `%v` on the flattened
+ * `%w` chain. Tagged errors expose `.message`; framework errors are translated
+ * above so their wording and exit code match Go.
+ */
+const messageFor = (error: unknown): string => {
+  if (typeof error === "object" && error !== null) {
+    const translated = frameworkMessage(error as never)
+    if (translated !== undefined) return translated
+    const withMessage = error as { readonly message?: unknown }
+    if (typeof withMessage.message === "string" && withMessage.message !== "") {
+      return withMessage.message
+    }
+  }
+  return String(error)
+}
+
+/**
+ * `--help` and `--version` surface as a ShowHelp failure carrying no errors;
+ * that is a successful invocation and must print nothing extra.
+ *
+ * A ShowHelp that DOES carry errors is a parse failure. The framework has
+ * already dumped the help text and its own error block by the time we see it —
+ * that is unavoidable without forking `Command.runWith` — so for those we add
+ * Go's single line and correct the exit code to 2.
+ */
+const isHelpRequest = (error: unknown): boolean =>
+  typeof error === "object" &&
+  error !== null &&
+  (error as { readonly _tag?: unknown })._tag === "ShowHelp" &&
+  ((error as { readonly errors?: ReadonlyArray }).errors?.length ?? 0) === 0
+
+const printFailure = (cause: Cause.Cause): Effect.Effect => {
+  const failure = Cause.findErrorOption(cause)
+  if (failure._tag === "None") {
+    // A defect (a genuine bug, not a user-facing error): let the default
+    // reporter show it in full, since the message alone would not be actionable.
+    return Effect.sync(() => {
+      process.stderr.write(`oytc: ${Cause.pretty(cause)}\n`)
+    })
+  }
+  const error = failure.value
+  if (isHelpRequest(error)) return Effect.void
+  return Effect.sync(() => {
+    process.stderr.write(`oytc: ${messageFor(error)}\n`)
+  })
+}
+
 /**
  * BunServices supplies FileSystem/Path/Stdio/Terminal/Spawner. AppLayer's
  * members depend on those, and so does the CLI runtime itself, so
@@ -29,4 +142,25 @@ const cli = Command.run(root, { version: resolveVersionDetails().version })
  */
 const MainLayer = Layer.provideMerge(AppLayer, BunServices.layer)
 
-BunRuntime.runMain(cli.pipe(Effect.provide(MainLayer)))
+/**
+ * Framework parse failures exit 1; Go exits 2 for every usage error. Re-tag
+ * them so the exit code matches.
+ */
+const withGoExitCodes = (effect: Effect.Effect): Effect.Effect =>
+  effect.pipe(
+    Effect.catch((error: E) => {
+      const tagged = error as { readonly _tag?: unknown }
+      if (tagged._tag === "ShowHelp" && !isHelpRequest(error)) {
+        return Effect.fail(
+          Object.assign(Object.create(Object.getPrototypeOf(error)), error, {
+            [Runtime.errorExitCode]: 2
+          }) as E
+        )
+      }
+      return Effect.fail(error)
+    })
+  )
+
+BunRuntime.runMain(
+  cli.pipe(Effect.provide(MainLayer), withGoExitCodes, Effect.tapCause(printFailure))
+)

From 7022fdded88b2fb452895b859c1a00584b9aea85 Mon Sep 17 00:00:00 2001
From: Benjamin Davis 
Date: Sat, 25 Jul 2026 02:51:25 -0700
Subject: [PATCH 5/6] fix(ts): repair defects found by running the compiled
 binary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A smoke-test pass ran the compiled binary against the Go one across all
32 leaf commands, ~150 validation invocations, every output format, and
config handling. Unit tests had not caught any of these.

CRITICAL — `oytc update ` performed a real self-update.
`Command.make("update", ...)` declared no positional argument, so the
framework silently discarded extras and no arity check ever ran. The
command printed nothing, downloaded the last Go release from GitHub,
replaced its own executable and exited 0. A typo like `oytc update
latest` destroyed the installed binary. It fired during the audit
itself, overwriting the test binary with the Go one — which briefly made
the two "agree" perfectly, since both were the same program.

The same missing-arity bug affected 11 more commands: `logout X` deleted
credentials, `skills install X` reached the overwrite prompt, and
`analytics video A B` silently ran the report for A while discarding B,
returning a plausible but wrong answer.

HIGH — `login` never validated the key you just typed. `keyScopedApi`
resolves an `HttpClient` via `Effect.serviceOption`, but AppLayer did
not expose one in its output, so it always saw None and fell back to the
ambient client. `login` probed an empty store and reported "no API key
configured"; `status --check` validated the API key using OAuth
credentials and reported key failures through OAuth error text. Unit
tests provided their own HttpClient, so only the compiled binary showed
it — a genuine test-versus-production gap.

HIGH — the `-f` and `-q` shorthands were missing, breaking any script
using `-f json`, and `--no-color` was rejected outright. Go accepts and
ignores it, and scripts pass it.

Also: leading-dash values now name the flag the user actually wrote
rather than always blaming --limit, and a valueless flag reports pflag's
"flag needs an argument" instead of "Help requested".

Verified after the fix: `update bogus-arg` exits 2 with the binary's
SHA-256 unchanged; all 12 arity cases match Go's message and exit code;
`status --check` is byte-identical to Go; no secret leaks in any of the
four formats with or without --check. 2136 tests pass, tsc clean.

Two known issues remain, both upstream in the CLI framework and
documented in /tmp/go-spec/SMOKE_TEST.md: parse errors dump help to
stdout where Go writes nothing, and `--` drops the operand for
subcommands.

Co-Authored-By: Claude Opus 5 (1M context) 
---
 src/cli/analyticsCmd.ts  | 78 +++++++++++++++++++++++++--------
 src/cli/auth.ts          | 25 +++++++++--
 src/cli/flags.ts         | 12 ++++++
 src/cli/livechat.ts      | 24 ++++++++++-
 src/cli/skillsCmd.ts     | 12 +++++-
 src/cli/versionUpdate.ts | 22 ++++++++--
 src/layers.ts            | 18 ++++++++
 src/main.ts              | 93 +++++++++++++++++++++++++++++++++++++---
 8 files changed, 248 insertions(+), 36 deletions(-)

diff --git a/src/cli/analyticsCmd.ts b/src/cli/analyticsCmd.ts
index c59ec5c..cdc2394 100644
--- a/src/cli/analyticsCmd.ts
+++ b/src/cli/analyticsCmd.ts
@@ -214,6 +214,19 @@ interface AnalyticsFlagValues {
   readonly limit: number
 }
 
+/**
+ * `Args: exactArgs(0)` in Go (analytics.go:44,71,108,124). Without a variadic
+ * argument the framework drops extra positionals silently and the handler runs
+ * anyway, so `oytc analytics overview extra` would issue a real API call.
+ */
+const noPositionals = { extra: Argument.string("").pipe(Argument.variadic()) }
+
+/** Go's arity check, run before anything else in each analytics handler. */
+const rejectExtraArgs = (extra: ReadonlyArray) =>
+  extra.length === 0
+    ? undefined
+    : new UsageError({ message: `expected 0 argument(s), received ${extra.length}` })
+
 // ---------------------------------------------------------------------------
 // The shared runner
 // ---------------------------------------------------------------------------
@@ -276,6 +289,7 @@ const runAnalytics = (flags: AnalyticsFlagValues, request: AnalyticsRequest) =>
 export const analyticsReportCommand = Command.make(
   "report",
   {
+    ...noPositionals,
     ...analyticsFlags,
     metrics: Flag.string("metrics").pipe(
       Flag.withDefault(""),
@@ -288,6 +302,8 @@ export const analyticsReportCommand = Command.make(
   },
   (config) =>
     Effect.gen(function* () {
+      const arity = rejectExtraArgs(config.extra)
+      if (arity !== undefined) return yield* Effect.fail(arity)
       const metrics = csvValues(config.metrics)
       // Runs before the date and limit checks, and before any credential load.
       if (metrics.length === 0) {
@@ -306,6 +322,7 @@ export const analyticsReportCommand = Command.make(
 export const analyticsOverviewCommand = Command.make(
   "overview",
   {
+    ...noPositionals,
     ...analyticsFlags,
     by: Flag.string("by").pipe(
       Flag.withDefault(""),
@@ -314,6 +331,8 @@ export const analyticsOverviewCommand = Command.make(
   },
   (config) =>
     Effect.gen(function* () {
+      const arity = rejectExtraArgs(config.extra)
+      if (arity !== undefined) return yield* Effect.fail(arity)
       const enumError = validateEnum("--by", config.by, ["day", "month"])
       if (enumError !== undefined) return yield* Effect.fail(enumError)
       // `--by` goes through csvValues, so a whitespace-only value contributes
@@ -332,37 +351,60 @@ export const analyticsOverviewCommand = Command.make(
 
 export const analyticsVideoCommand = Command.make(
   "video",
-  { ...analyticsFlags, videoId: Argument.string("VIDEO_ID") },
+  // `Args: exactArgs(1)`. A plain `Argument.string` reports the framework's own
+  // "Missing required argument" for 0 args and silently DROPS extras, so the
+  // arity is observed variadically and checked here, as everywhere else.
+  {
+    ...analyticsFlags,
+    ids: Argument.string("VIDEO_ID").pipe(Argument.variadic())
+  },
   (config) =>
-    runAnalytics(config, {
-      metrics: analyticsVideoColumns,
-      dimensions: [],
-      builtInFilter: `video==${config.videoId}`,
-      columns: analyticsVideoColumns
+    Effect.gen(function* () {
+      if (config.ids.length !== 1) {
+        return yield* Effect.fail(
+          new UsageError({
+            message: `expected 1 argument(s), received ${config.ids.length}`
+          })
+        )
+      }
+      yield* runAnalytics(config, {
+        metrics: analyticsVideoColumns,
+        dimensions: [],
+        builtInFilter: `video==${config.ids[0]!}`,
+        columns: analyticsVideoColumns
+      })
     })
 ).pipe(Command.withDescription("Show core analytics metrics for one owned video"))
 
 export const analyticsTrafficSourcesCommand = Command.make(
   "traffic-sources",
-  analyticsFlags,
+  { ...noPositionals, ...analyticsFlags },
   (config) =>
-    runAnalytics(config, {
-      metrics: ["views", "estimatedMinutesWatched"],
-      dimensions: ["insightTrafficSourceType"],
-      builtInFilter: "",
-      columns: analyticsTrafficSourcesColumns
+    Effect.gen(function* () {
+      const arity = rejectExtraArgs(config.extra)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      yield* runAnalytics(config, {
+        metrics: ["views", "estimatedMinutesWatched"],
+        dimensions: ["insightTrafficSourceType"],
+        builtInFilter: "",
+        columns: analyticsTrafficSourcesColumns
+      })
     })
 ).pipe(Command.withDescription("Break views and watch time down by traffic source"))
 
 export const analyticsDemographicsCommand = Command.make(
   "demographics",
-  analyticsFlags,
+  { ...noPositionals, ...analyticsFlags },
   (config) =>
-    runAnalytics(config, {
-      metrics: ["viewerPercentage"],
-      dimensions: ["ageGroup", "gender"],
-      builtInFilter: "",
-      columns: analyticsDemographicsColumns
+    Effect.gen(function* () {
+      const arity = rejectExtraArgs(config.extra)
+      if (arity !== undefined) return yield* Effect.fail(arity)
+      yield* runAnalytics(config, {
+        metrics: ["viewerPercentage"],
+        dimensions: ["ageGroup", "gender"],
+        builtInFilter: "",
+        columns: analyticsDemographicsColumns
+      })
     })
 ).pipe(Command.withDescription("Break viewer percentage down by age group and gender"))
 
diff --git a/src/cli/auth.ts b/src/cli/auth.ts
index 81a89c0..570fe14 100644
--- a/src/cli/auth.ts
+++ b/src/cli/auth.ts
@@ -45,7 +45,7 @@
  */
 
 import { Effect, Option, Redacted, Result, Stdio, Stream } from "effect"
-import { Command, Flag, HttpClient } from "../effect.ts"
+import { Argument, Command, Flag, HttpClient } from "../effect.ts"
 import {
   ApiError,
   AuthHintError,
@@ -61,6 +61,7 @@ import { statusCheckDateRange } from "../impl/analyticsApi.ts"
 import { makeHttpCore } from "../impl/httpCore.ts"
 import { makeYouTubeApi } from "../impl/youtubeApi.ts"
 import { statusCheckColumns, statusColumns } from "../output/columns.ts"
+import { exactArgs } from "./playlist.ts"
 import {
   AnalyticsApi,
   AppOptions,
@@ -407,9 +408,18 @@ const loginOAuth = Effect.gen(function* () {
   )
 })
 
+/**
+ * `Args: exactArgs(0)` in Go (auth.go:37,51,61). A variadic argument is the
+ * only way to observe extra positionals; without it the framework drops them
+ * silently and the handler runs, so `oytc login extra` would prompt for a key
+ * and `oytc logout extra` would delete credentials.
+ */
+const noPositionals = { extra: Argument.string("").pipe(Argument.variadic()) }
+
 export const loginCommand = Command.make(
   "login",
   {
+    ...noPositionals,
     oauth: Flag.boolean("oauth").pipe(
       Flag.withDescription("authorize read-only access to your channel and Analytics")
     )
@@ -417,8 +427,10 @@ export const loginCommand = Command.make(
   // A ternary between two Effects with DIFFERENT requirement sets produces a
   // union type that is not assignable to a single Effect; suspending inside a
   // gen block unifies both arms' R instead.
-  ({ oauth }) =>
+  ({ extra, oauth }) =>
     Effect.gen(function* () {
+      const arity = exactArgs(0, extra)
+      if (arity !== undefined) return yield* Effect.fail(arity)
       if (oauth) yield* loginOAuth
       else yield* loginApiKey
     })
@@ -431,12 +443,15 @@ export const loginCommand = Command.make(
 export const statusCommand = Command.make(
   "status",
   {
+    ...noPositionals,
     check: Flag.boolean("check").pipe(
       Flag.withDescription("validate configured credentials with the API")
     )
   },
-  ({ check }) =>
+  ({ extra, check }) =>
     Effect.gen(function* () {
+      const arity = exactArgs(0, extra)
+      if (arity !== undefined) return yield* Effect.fail(arity)
       const options = yield* AppOptions
       const store = yield* CredentialStore
       const credentials = yield* store.load
@@ -510,8 +525,10 @@ const failureOf = (
 // logout
 // ---------------------------------------------------------------------------
 
-export const logoutCommand = Command.make("logout", {}, () =>
+export const logoutCommand = Command.make("logout", noPositionals, ({ extra }) =>
   Effect.gen(function* () {
+    const arity = exactArgs(0, extra)
+    if (arity !== undefined) return yield* Effect.fail(arity)
     const store = yield* CredentialStore
     const oauth = yield* OAuthService
 
diff --git a/src/cli/flags.ts b/src/cli/flags.ts
index 501e4d0..bd4b2f9 100644
--- a/src/cli/flags.ts
+++ b/src/cli/flags.ts
@@ -19,6 +19,7 @@ export const FORMATS = ["table", "json", "jsonl", "tsv"] as const
  */
 export const globalFlags = {
   format: Flag.choice("format", FORMATS).pipe(
+    Flag.withAlias("f"),
     Flag.withDescription("Output format (default: table on a terminal, json when piped)"),
     Flag.optional
   ),
@@ -30,8 +31,17 @@ export const globalFlags = {
     Flag.withDescription("Omit the header row in table and tsv output")
   ),
   quiet: Flag.boolean("quiet").pipe(
+    Flag.withAlias("q"),
     Flag.withDescription("Suppress the request-count summary on stderr")
   ),
+  /**
+   * Accepted and ignored, exactly as in Go: "disable color (accepted for
+   * scripting; first draft emits no color)". Scripts and CI configs pass it,
+   * so rejecting it is a regression even though it has no effect.
+   */
+  noColor: Flag.boolean("no-color").pipe(
+    Flag.withDescription("disable color (accepted for scripting; first draft emits no color)")
+  ),
   timeout: Flag.string("timeout").pipe(
     Flag.withDescription("Request timeout, e.g. 20s or 1m30s"),
     Flag.withDefault("20s")
@@ -43,5 +53,7 @@ export interface GlobalFlagValues {
   readonly columns: Option.Option
   readonly noHeader: boolean
   readonly quiet: boolean
+  /** Parsed for compatibility and deliberately unused; see globalFlags. */
+  readonly noColor: boolean
   readonly timeout: string
 }
diff --git a/src/cli/livechat.ts b/src/cli/livechat.ts
index 9f74fc9..d391c59 100644
--- a/src/cli/livechat.ts
+++ b/src/cli/livechat.ts
@@ -45,7 +45,7 @@
  */
 
 import { Effect, Option, Stdio, Stream } from "effect"
-import { Command, Flag } from "../effect.ts"
+import { Argument, Command, Flag } from "../effect.ts"
 import {
   ApiError,
   NotFoundError,
@@ -246,9 +246,21 @@ const renderResult = (
     yield* writeErr(`${result.items.length} item(s), ${result.requests} request(s)${more}\n`)
   })
 
+/**
+ * `Args: exactArgs(0)` in Go (live_chat.go:38,67). Observed variadically
+ * because the framework otherwise drops extra positionals silently.
+ */
+const noPositionals = { extra: Argument.string("").pipe(Argument.variadic()) }
+
+const rejectExtraArgs = (extra: ReadonlyArray) =>
+  extra.length === 0
+    ? undefined
+    : new UsageError({ message: `expected 0 argument(s), received ${extra.length}` })
+
 export const liveChatListCommand = Command.make(
   "list",
   {
+    ...noPositionals,
     ...liveChatFlags,
     all: Flag.boolean("all").pipe(
       Flag.withDescription("not supported for finite live chat; use stream")
@@ -256,6 +268,9 @@ export const liveChatListCommand = Command.make(
   },
   (config) =>
     Effect.gen(function* () {
+      // Arity is cobra's `Args`, which runs before PreRunE.
+      const arity = rejectExtraArgs(config.extra)
+      if (arity !== undefined) return yield* Effect.fail(arity)
       // PreRunE first…
       const invalid = validateLiveChatFlags(config)
       if (invalid !== undefined) return yield* Effect.fail(invalid)
@@ -498,8 +513,13 @@ const withOwnSigint = (
     )
   })
 
-export const liveChatStreamCommand = Command.make("stream", liveChatFlags, (config) =>
+export const liveChatStreamCommand = Command.make(
+  "stream",
+  { ...noPositionals, ...liveChatFlags },
+  (config) =>
   Effect.gen(function* () {
+    const arity = rejectExtraArgs(config.extra)
+    if (arity !== undefined) return yield* Effect.fail(arity)
     const invalid = validateLiveChatFlags(config)
     if (invalid !== undefined) return yield* Effect.fail(invalid)
 
diff --git a/src/cli/skillsCmd.ts b/src/cli/skillsCmd.ts
index c115151..497428c 100644
--- a/src/cli/skillsCmd.ts
+++ b/src/cli/skillsCmd.ts
@@ -33,9 +33,10 @@
  */
 
 import { Effect, FileSystem, Stdio, Stream } from "effect"
-import { Command } from "../effect.ts"
+import { Argument, Command } from "../effect.ts"
 import { OperationalError } from "../domain/errors.ts"
 import { Prompts, SkillInstaller } from "../services/index.ts"
+import { exactArgs } from "./playlist.ts"
 
 /** stdout, via the same `Stdio` seam the renderer writes through. */
 const writeOut = (text: string): Effect.Effect =>
@@ -87,8 +88,15 @@ export const confirmationBlock = (target: string, action: "create" | "replace"):
   `Permission requested: ${action} this directory and write SKILL.md plus references.\n` +
   "Continue? [y/N] "
 
-export const skillsInstallCommand = Command.make("install", {}, () =>
+export const skillsInstallCommand = Command.make(
+  "install",
+  // Go: `Args: exactArgs(0)`. Checked before the confirmation prompt, which
+  // otherwise writes to the destination directory.
+  { extra: Argument.string("").pipe(Argument.variadic()) },
+  ({ extra }) =>
   Effect.gen(function* () {
+    const arity = exactArgs(0, extra)
+    if (arity !== undefined) return yield* Effect.fail(arity)
     const installer = yield* SkillInstaller
     const prompts = yield* Prompts
     const fs = yield* FileSystem.FileSystem
diff --git a/src/cli/versionUpdate.ts b/src/cli/versionUpdate.ts
index a9224d9..c179c6b 100644
--- a/src/cli/versionUpdate.ts
+++ b/src/cli/versionUpdate.ts
@@ -28,8 +28,9 @@
  */
 
 import { Effect, Stdio, Stream } from "effect"
-import { Command, Flag } from "../effect.ts"
+import { Argument, Command, Flag } from "../effect.ts"
 import { OperationalError } from "../domain/errors.ts"
+import { exactArgs } from "./playlist.ts"
 import type { JsonObject } from "../json/value.ts"
 import { compareVersions } from "../impl/semver.ts"
 import { updateColumns, versionColumns } from "../output/columns.ts"
@@ -72,8 +73,17 @@ const isTable = (format: OutputFormat): boolean => format === "table"
 // version
 // ---------------------------------------------------------------------------
 
-export const versionCommand = Command.make("version", {}, () =>
+/**
+ * `Args: exactArgs(0)` in Go. A variadic argument is the only way to observe
+ * extra positionals and reproduce Go's message; without it the framework
+ * silently drops them and the handler runs anyway.
+ */
+const noPositionals = { extra: Argument.string("").pipe(Argument.variadic()) }
+
+export const versionCommand = Command.make("version", noPositionals, ({ extra }) =>
   Effect.gen(function* () {
+    const arity = exactArgs(0, extra)
+    if (arity !== undefined) return yield* Effect.fail(arity)
     const options = yield* AppOptions
     const versionInfo = yield* VersionInfo
     const info = yield* versionInfo.get
@@ -131,6 +141,7 @@ export const isUpToDate = (latestVersion: string, currentVersion: string): boole
 export const updateCommand = Command.make(
   "update",
   {
+    ...noPositionals,
     check: Flag.boolean("check").pipe(
       Flag.withDescription("only report whether a newer release exists")
     ),
@@ -144,8 +155,13 @@ export const updateCommand = Command.make(
       Flag.withDescription("install this exact release tag (e.g. v0.2.0) instead of the latest")
     )
   },
-  ({ check, targetVersion }) =>
+  ({ extra, check, targetVersion }) =>
     Effect.gen(function* () {
+      // MUST run before `updater.run`: this handler REPLACES THE EXECUTABLE.
+      // Without the guard, `oytc update ` printed the arity error, then
+      // self-updated anyway and exited 0.
+      const arity = exactArgs(0, extra)
+      if (arity !== undefined) return yield* Effect.fail(arity)
       const options = yield* AppOptions
       const updater = yield* Updater
       const result = yield* updater.run({ checkOnly: check, targetVersion })
diff --git a/src/layers.ts b/src/layers.ts
index b559b58..d3ec09c 100644
--- a/src/layers.ts
+++ b/src/layers.ts
@@ -94,6 +94,24 @@ const AnalyticsLive = AnalyticsApiLive.pipe(Layer.provide(HttpCoreLive))
 
 export const AppLayer = Layer.mergeAll(
   EnvLive,
+  /**
+   * The raw HTTP client is part of AppLayer's OUTPUT, not just an internal
+   * dependency of HttpCoreLive.
+   *
+   * `cli/auth.ts:keyScopedApi` builds a throwaway `YouTubeApi` bound to a
+   * specific key — the key just typed at the `login` prompt, or the stored key
+   * being validated by `status --check` — via
+   * `Effect.serviceOption(HttpClient.HttpClient)`. Without HttpClient in the
+   * output that lookup returned None in the compiled binary and the code fell
+   * back to the AMBIENT `YouTubeApi`, which is bound to whatever is in the
+   * credential store. Consequences, both verified against the Go binary:
+   *   - `login` on an empty config probed with NO key and reported
+   *     "no API key configured" instead of the API's rejection.
+   *   - `status --check` probed the API key using the OAUTH credentials, so a
+   *     bad key was reported through an OAuth error message.
+   * The unit tests never caught it because they provide HttpClient themselves.
+   */
+  HttpClientLive,
   CredentialsLive,
   HttpCoreLive,
   YouTubeApiLive,
diff --git a/src/main.ts b/src/main.ts
index ae2fe1a..644397b 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -44,10 +44,17 @@ const frameworkMessage = (error: {
 }): string | undefined => {
   const nested = error.errors
   if (Array.isArray(nested) && nested.length > 0) {
-    // ShowHelp wraps the real parse failures. Report the first one that
-    // translates: a single user mistake can produce several framework errors
-    // (a `--limit -1` yields both a missing-value and an unrecognized-flag),
-    // and Go reports only the underlying cause.
+    // ShowHelp wraps the real parse failures. A single user mistake can produce
+    // SEVERAL framework errors, and Go reports only the underlying cause.
+    //
+    // The important pair: a leading-dash value (`--page-size -1`, `--timeout
+    // -1s`) lexes as a valueless flag followed by an unrecognized flag, i.e.
+    //   InvalidValue{option: "page-size", value: ""}   <- names the real flag
+    //   UnrecognizedOption{option: "-1"}               <- lexer artifact
+    // Go's pflag accepts the value, so the message must name the flag the user
+    // actually wrote. Recover it from the FIRST error and drop the artifact.
+    const negated = negativeValueMessage(nested)
+    if (negated !== undefined) return negated
     for (const candidate of nested) {
       const translated = frameworkMessage(candidate as never)
       if (translated !== undefined) return translated
@@ -63,9 +70,9 @@ const frameworkMessage = (error: {
       return `unknown command ${goQuote(String(error.subcommand ?? ""))} for "oytc"`
     case "UnrecognizedOption": {
       const option = String(error.option ?? "")
-      // `--limit -1` lexes as two flags: a valueless --limit, then "-1" as an
-      // unrecognized flag. Go's pflag accepts the negative value, so report the
-      // range error the user actually tripped rather than a lexer artifact.
+      // Reached only when the paired InvalidValue is absent (see
+      // negativeValueMessage). Keep the historical --limit wording for a bare
+      // negative so the golden `search --limit -1` case is unaffected.
       if (/^-\d/.test(option)) return "--limit cannot be negative"
       return `unknown flag: ${option}`
     }
@@ -81,6 +88,78 @@ const frameworkMessage = (error: {
   }
 }
 
+/**
+ * The Go range message for a flag whose value the lexer mistook for a flag.
+ *
+ * Go's pflag accepts `--page-size -1`; this framework's lexer does not, and
+ * emits the pair described in `frameworkMessage`. Recovering the flag NAME from
+ * the paired `InvalidValue` lets the range error name the flag the user wrote
+ * instead of always blaming `--limit`.
+ *
+ * The bounds are per-command (SPEC_API §3.2), and the framework's `InvalidValue`
+ * carries no command path, so `UnrecognizedOption.command` supplies it.
+ */
+const negativeRangeMessage = (
+  option: string,
+  commandPath: ReadonlyArray
+): string | undefined => {
+  const path = commandPath.join(" ")
+  switch (option) {
+    case "timeout":
+      return "--timeout must be positive"
+    case "limit":
+      // `analytics *` bounds --limit; every other command only rejects
+      // negatives.
+      return path.includes("analytics")
+        ? "--limit must be between 1 and 200"
+        : "--limit cannot be negative"
+    case "profile-image-size":
+      return "--profile-image-size must be between 16 and 720"
+    case "page-size": {
+      if (path.includes("live-chat")) return "--page-size must be between 200 and 2000"
+      if (path.includes("comment")) return "--page-size must be between 1 and 100"
+      return "--page-size must be between 1 and 50"
+    }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Detect the "leading-dash value" error pair and translate it.
+ *
+ * Returns undefined unless the batch contains BOTH a valueless `InvalidValue`
+ * naming a real flag and an `UnrecognizedOption` that looks like the value.
+ */
+const negativeValueMessage = (
+  errors: ReadonlyArray
+): string | undefined => {
+  let option: string | undefined
+  let commandPath: ReadonlyArray = []
+  let sawArtifact = false
+  for (const raw of errors) {
+    const error = raw as {
+      readonly _tag?: unknown
+      readonly option?: unknown
+      readonly value?: unknown
+      readonly command?: unknown
+    }
+    if (error._tag === "InvalidValue" && error.value === "") {
+      // The FIRST valueless flag is the one the user wrote; a later one (e.g.
+      // the inherited --format) is collateral from the same lexer confusion.
+      option ??= String(error.option ?? "")
+    } else if (error._tag === "UnrecognizedOption" && /^-/.test(String(error.option ?? ""))) {
+      sawArtifact = true
+      if (Array.isArray(error.command)) commandPath = error.command as ReadonlyArray
+    }
+  }
+  if (option === undefined) return undefined
+  // No lexer artifact means the flag simply ran off the end of argv
+  // (`oytc search foo --order`). pflag's wording for that is bespoke.
+  if (!sawArtifact) return `flag needs an argument: --${option}`
+  return negativeRangeMessage(option, commandPath)
+}
+
 /** Go's %q for the strings that reach these messages (plain identifiers). */
 const goQuote = (value: string): string => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`
 

From a2bf316afbcec38af8dee0e8de251c31783c3f8d Mon Sep 17 00:00:00 2001
From: Benjamin Davis 
Date: Sat, 25 Jul 2026 02:56:54 -0700
Subject: [PATCH 6/6] fix(ts): bound `--all` pagination, and remove the Go
 implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## `--all` could run forever (DEVIATIONS.md D3)

The pagination loop terminated only when the server returned an empty
`nextPageToken`, which trusts the server completely. A server that
repeats a token — a bug, a caching proxy, a hostile endpoint — made
`--all` loop forever, accumulating every page in memory with no ceiling
and never flushing output.

Not hypothetical: a test harness whose fake server returned a constant
token ran `search --all` and consumed ~59 GB of RSS across two processes
before being killed, taking the machine to 127 GB used with 44 GB in the
compressor. A verifier had already seen the hang and recorded "verified
both Go and TS hang identically", treating the match as faithful. It was
faithful. Faithfully reproducing an unbounded loop is still an unbounded
loop.

Two guards, neither reachable on a well-behaved server:

- Loop detection: a token already followed can only return a page
  already fetched, so stop and report `nextPageToken = ""` — the same
  "no valid resume point" signal D2 uses.
- Request ceiling: MAX_PAGES = 10000 as a backstop for a server emitting
  distinct tokens forever, which the loop check cannot catch. It fails
  with an OperationalError naming `--limit` as the remedy. At the largest
  page size any endpoint accepts (2000, live chat) the ceiling allows
  20M items; every other endpoint caps at 50 or 100 per page.

`--limit` still terminates before either guard, so a bounded request
against a repeating server stops at the limit.

Verified against the exact failing scenario: a local server returning a
constant token now terminates in 11ms after 2 requests at 104 MB RSS.

## Go implementation removed

Deletes cmd/, internal/, go.mod, go.sum, and skills/oytc/embed.go, and
updates the README's build instructions for Bun. The Go source stayed in
place for the whole port so it could serve as the behavioral oracle —
the differential tests that caught the JSON codec bugs, the error
envelope's case-insensitivity, and the `video trainability` body
handling all ran against a binary built from it.

2141 tests pass; TypeScript 7 typechecks clean.

Co-Authored-By: Claude Opus 5 (1M context) 
---
 README.md                           |   3 +-
 cmd/oytc/main.go                    | 105 -----
 cmd/oytc/main_test.go               |  70 ----
 go.mod                              |  15 -
 go.sum                              |  16 -
 internal/analytics/client.go        | 116 ------
 internal/analytics/client_test.go   |  53 ---
 internal/cli/analytics.go           | 211 ----------
 internal/cli/app.go                 | 532 -------------------------
 internal/cli/app_test.go            | 487 -----------------------
 internal/cli/auth.go                | 357 -----------------
 internal/cli/channel_video.go       | 295 --------------
 internal/cli/fields.go              |  79 ----
 internal/cli/fields_test.go         |  44 ---
 internal/cli/live_chat.go           | 227 -----------
 internal/cli/resources.go           | 289 --------------
 internal/cli/skills.go              |  65 ----
 internal/cli/skills_test.go         |  55 ---
 internal/cli/version_update.go      |  97 -----
 internal/cli/version_update_test.go | 129 -------
 internal/config/config.go           | 356 -----------------
 internal/config/config_test.go      | 231 -----------
 internal/config/lock_unix.go        |  17 -
 internal/config/lock_windows.go     |  19 -
 internal/config/rename_unix.go      |   9 -
 internal/config/rename_windows.go   |  17 -
 internal/oauth/oauth.go             | 426 --------------------
 internal/oauth/oauth_test.go        | 263 -------------
 internal/output/output.go           | 151 --------
 internal/output/output_test.go      |  48 ---
 internal/skill/install.go           |  93 -----
 internal/skill/install_test.go      |  68 ----
 internal/update/update.go           | 580 ----------------------------
 internal/update/update_test.go      | 349 -----------------
 internal/version/version.go         |  67 ----
 internal/version/version_test.go    |  29 --
 internal/youtube/client.go          | 231 -----------
 internal/youtube/client_test.go     | 199 ----------
 internal/youtube/list.go            | 159 --------
 skills/oytc/embed.go                |   8 -
 src/impl/youtubeApi.test.ts         |  89 ++++-
 src/impl/youtubeApi.ts              |  46 +++
 42 files changed, 136 insertions(+), 6564 deletions(-)
 delete mode 100644 cmd/oytc/main.go
 delete mode 100644 cmd/oytc/main_test.go
 delete mode 100644 go.mod
 delete mode 100644 go.sum
 delete mode 100644 internal/analytics/client.go
 delete mode 100644 internal/analytics/client_test.go
 delete mode 100644 internal/cli/analytics.go
 delete mode 100644 internal/cli/app.go
 delete mode 100644 internal/cli/app_test.go
 delete mode 100644 internal/cli/auth.go
 delete mode 100644 internal/cli/channel_video.go
 delete mode 100644 internal/cli/fields.go
 delete mode 100644 internal/cli/fields_test.go
 delete mode 100644 internal/cli/live_chat.go
 delete mode 100644 internal/cli/resources.go
 delete mode 100644 internal/cli/skills.go
 delete mode 100644 internal/cli/skills_test.go
 delete mode 100644 internal/cli/version_update.go
 delete mode 100644 internal/cli/version_update_test.go
 delete mode 100644 internal/config/config.go
 delete mode 100644 internal/config/config_test.go
 delete mode 100644 internal/config/lock_unix.go
 delete mode 100644 internal/config/lock_windows.go
 delete mode 100644 internal/config/rename_unix.go
 delete mode 100644 internal/config/rename_windows.go
 delete mode 100644 internal/oauth/oauth.go
 delete mode 100644 internal/oauth/oauth_test.go
 delete mode 100644 internal/output/output.go
 delete mode 100644 internal/output/output_test.go
 delete mode 100644 internal/skill/install.go
 delete mode 100644 internal/skill/install_test.go
 delete mode 100644 internal/update/update.go
 delete mode 100644 internal/update/update_test.go
 delete mode 100644 internal/version/version.go
 delete mode 100644 internal/version/version_test.go
 delete mode 100644 internal/youtube/client.go
 delete mode 100644 internal/youtube/client_test.go
 delete mode 100644 internal/youtube/list.go
 delete mode 100644 skills/oytc/embed.go

diff --git a/README.md b/README.md
index c2aeed7..a0d799d 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,8 @@ curl -fsSL https://davis7dotsh.github.io/open-yt-cli/install.sh | sh
 Windows (PowerShell): `irm https://davis7dotsh.github.io/open-yt-cli/install.ps1 | iex`,
 or download a zip from [releases](https://github.com/davis7dotsh/open-yt-cli/releases).
 
-From source (Go 1.26+): `go install ./cmd/oytc` from a clone, or `make build`.
+From source ([Bun](https://bun.com) 1.3+): `bun install && bun run build` from a clone, or
+`make build`. The result is a single self-contained native binary at `bin/oytc`.
 
 ## Quick start
 
diff --git a/cmd/oytc/main.go b/cmd/oytc/main.go
deleted file mode 100644
index b34acdc..0000000
--- a/cmd/oytc/main.go
+++ /dev/null
@@ -1,105 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"os"
-	"os/signal"
-	"path/filepath"
-	"strings"
-	"syscall"
-
-	"open-yt-cli/internal/cli"
-	"open-yt-cli/internal/oauth"
-	"open-yt-cli/internal/youtube"
-)
-
-func main() {
-	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
-	defer stop()
-	app := cli.New()
-	root := app.Root()
-	root.SetArgs(dispatchArgs(os.Args[0], os.Args[1:]))
-	err := root.ExecuteContext(ctx)
-	if err == nil {
-		return
-	}
-	fmt.Fprintf(os.Stderr, "oytc: %v\n", err)
-	os.Exit(exitCode(err))
-}
-
-// dispatchArgs implements argv[0] dispatch: when the binary is invoked as
-// oytc_update or oytc_upgrade (for example through an installer-created
-// symlink or shim), it behaves exactly like `oytc update`. Any extra
-// arguments (such as --check) are passed through to the update command.
-func dispatchArgs(argv0 string, rest []string) []string {
-	// Split on both separators so Windows-style argv[0] values work everywhere.
-	base := filepath.Base(strings.ReplaceAll(argv0, `\`, "/"))
-	name := strings.TrimSuffix(base, ".exe")
-	switch name {
-	case "oytc_update", "oytc-update", "oytc_upgrade", "oytc-upgrade":
-		return append([]string{"update"}, rest...)
-	}
-	return rest
-}
-
-func exitCode(err error) int {
-	var usage *cli.UsageError
-	if errors.As(err, &usage) {
-		return 2
-	}
-	if errors.Is(err, youtube.ErrMissingKey) || errors.Is(err, youtube.ErrMissingOAuth) {
-		return 3
-	}
-	var oauthErr *oauth.Error
-	if errors.As(err, &oauthErr) {
-		// Every structured OAuth failure is an auth problem (exit 3)
-		// except clearly transient Google-side errors.
-		switch oauthErr.Code {
-		case "server_error", "temporarily_unavailable":
-			return 6
-		}
-		if oauthErr.HTTPStatus == 429 {
-			return 5
-		}
-		if oauthErr.HTTPStatus >= 500 {
-			return 6
-		}
-		return 3
-	}
-	var apiErr *youtube.APIError
-	if errors.As(err, &apiErr) {
-		reasons := strings.ToLower(strings.Join(apiErr.Reasons, ","))
-		normalizedReasons := strings.NewReplacer("_", "", "-", "").Replace(reasons)
-		if strings.Contains(normalizedReasons, "keyinvalid") || strings.Contains(normalizedReasons, "apikeyinvalid") || strings.Contains(normalizedReasons, "accessnotconfigured") || strings.Contains(normalizedReasons, "insufficientpermissions") || apiErr.HTTPStatus == 401 {
-			return 3
-		}
-		if apiErr.HTTPStatus == 404 {
-			return 4
-		}
-		if apiErr.HTTPStatus == 429 || strings.Contains(strings.ToLower(reasons), "quota") || strings.Contains(strings.ToLower(reasons), "ratelimit") {
-			return 5
-		}
-		if apiErr.HTTPStatus == 403 {
-			return 4
-		}
-		if apiErr.HTTPStatus >= 500 {
-			return 6
-		}
-	}
-	message := strings.ToLower(err.Error())
-	if strings.Contains(message, "invalid_grant") || strings.Contains(message, "re-run 'oytc login --oauth'") {
-		return 3
-	}
-	if strings.Contains(message, "unknown command") || strings.Contains(message, "unknown flag") {
-		return 2
-	}
-	if strings.Contains(message, "not found") || strings.Contains(message, "no active public live chat") || strings.Contains(message, "no public uploads") {
-		return 4
-	}
-	if errors.Is(err, context.Canceled) {
-		return 130
-	}
-	return 6
-}
diff --git a/cmd/oytc/main_test.go b/cmd/oytc/main_test.go
deleted file mode 100644
index 7265c46..0000000
--- a/cmd/oytc/main_test.go
+++ /dev/null
@@ -1,70 +0,0 @@
-package main
-
-import (
-	"errors"
-	"reflect"
-	"testing"
-
-	"open-yt-cli/internal/cli"
-	"open-yt-cli/internal/oauth"
-	"open-yt-cli/internal/youtube"
-)
-
-func TestDispatchArgs(t *testing.T) {
-	tests := []struct {
-		argv0 string
-		rest  []string
-		want  []string
-	}{
-		{"oytc", []string{"search", "cats"}, []string{"search", "cats"}},
-		{"/usr/local/bin/oytc", nil, nil},
-		{"oytc_update", nil, []string{"update"}},
-		{"/home/user/.local/bin/oytc_update", []string{"--check"}, []string{"update", "--check"}},
-		{"oytc_upgrade", nil, []string{"update"}},
-		{"oytc-update", nil, []string{"update"}},
-		{"oytc-upgrade", []string{"--version", "v1.0.0"}, []string{"update", "--version", "v1.0.0"}},
-		{`C:\Users\u\oytc_update.exe`, nil, []string{"update"}},
-		{"oytc_updater", []string{"x"}, []string{"x"}},
-	}
-	for _, test := range tests {
-		got := dispatchArgs(test.argv0, test.rest)
-		if !reflect.DeepEqual(got, test.want) {
-			t.Errorf("dispatchArgs(%q, %v) = %v, want %v", test.argv0, test.rest, got, test.want)
-		}
-	}
-}
-
-func TestExitCodes(t *testing.T) {
-	tests := []struct {
-		name string
-		err  error
-		want int
-	}{
-		{"usage", &cli.UsageError{Message: "bad flag"}, 2},
-		{"unknown command", errors.New(`unknown command "wat"`), 2},
-		{"missing key", youtube.ErrMissingKey, 3},
-		{"missing OAuth", youtube.ErrMissingOAuth, 3},
-		{"invalid OAuth grant", &oauth.Error{HTTPStatus: 400, Code: "invalid_grant"}, 3},
-		{"unlisted OAuth code", &oauth.Error{HTTPStatus: 400, Code: "invalid_scope"}, 3},
-		{"codeless OAuth error", &oauth.Error{HTTPStatus: 400}, 3},
-		{"transient OAuth error", &oauth.Error{HTTPStatus: 503, Code: "temporarily_unavailable"}, 6},
-		{"OAuth server error", &oauth.Error{HTTPStatus: 500, Code: "server_error"}, 6},
-		{"OAuth rate limited", &oauth.Error{HTTPStatus: 429}, 5},
-		{"insufficient OAuth permissions", &youtube.APIError{HTTPStatus: 403, Code: 403, Reasons: []string{"insufficientPermissions"}}, 3},
-		{"invalid key camel case", &youtube.APIError{HTTPStatus: 400, Code: 400, Reasons: []string{"keyInvalid"}}, 3},
-		{"invalid key uppercase underscore", &youtube.APIError{HTTPStatus: 400, Code: 400, Reasons: []string{"badRequest", "API_KEY_INVALID"}}, 3},
-		{"API not enabled", &youtube.APIError{HTTPStatus: 403, Code: 403, Reasons: []string{"accessNotConfigured"}}, 3},
-		{"not found", &youtube.APIError{HTTPStatus: 404, Code: 404}, 4},
-		{"local not found", errors.New("videos not found: missing"), 4},
-		{"quota", &youtube.APIError{HTTPStatus: 403, Code: 403, Reasons: []string{"quotaExceeded"}}, 5},
-		{"rate limit", &youtube.APIError{HTTPStatus: 429, Code: 429}, 5},
-		{"upstream", &youtube.APIError{HTTPStatus: 503, Code: 503}, 6},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			if got := exitCode(test.err); got != test.want {
-				t.Fatalf("exitCode(%v) = %d, want %d", test.err, got, test.want)
-			}
-		})
-	}
-}
diff --git a/go.mod b/go.mod
deleted file mode 100644
index c221511..0000000
--- a/go.mod
+++ /dev/null
@@ -1,15 +0,0 @@
-module open-yt-cli
-
-go 1.26.0
-
-require (
-	github.com/spf13/cobra v1.10.2
-	golang.org/x/oauth2 v0.36.0
-	golang.org/x/sys v0.47.0
-	golang.org/x/term v0.45.0
-)
-
-require (
-	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/spf13/pflag v1.0.9 // indirect
-)
diff --git a/go.sum b/go.sum
deleted file mode 100644
index b014642..0000000
--- a/go.sum
+++ /dev/null
@@ -1,16 +0,0 @@
-github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
-github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
-github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
-github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
-github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
-github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
-github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
-github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
-go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
-golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
-golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
-golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
-golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
diff --git a/internal/analytics/client.go b/internal/analytics/client.go
deleted file mode 100644
index 0143822..0000000
--- a/internal/analytics/client.go
+++ /dev/null
@@ -1,116 +0,0 @@
-// Package analytics provides a read-only YouTube Analytics reports client.
-package analytics
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"net/http"
-	"net/url"
-	"strconv"
-	"strings"
-	"time"
-
-	"open-yt-cli/internal/youtube"
-)
-
-const (
-	DefaultBaseURL = "https://youtubeanalytics.googleapis.com/v2"
-	MaxResults     = 200
-)
-
-type ColumnHeader struct {
-	Name       string `json:"name"`
-	ColumnType string `json:"columnType"`
-	DataType   string `json:"dataType"`
-}
-
-type Response struct {
-	ColumnHeaders []ColumnHeader `json:"columnHeaders"`
-	Rows          [][]any        `json:"rows"`
-}
-
-type Query struct {
-	StartDate  string
-	EndDate    string
-	Metrics    []string
-	Dimensions []string
-	Filters    string
-	Sort       string
-	Limit      int
-	StartIndex int
-}
-
-type Client struct {
-	client *youtube.Client
-}
-
-func NewClient(source youtube.TokenSource, timeout time.Duration) *Client {
-	client := youtube.NewClient("", timeout)
-	client.BaseURL = DefaultBaseURL
-	client.TokenSource = source
-	return &Client{client: client}
-}
-
-func (c *Client) SetBaseURL(baseURL string) {
-	c.client.BaseURL = baseURL
-}
-
-func (c *Client) SetHTTPClient(client *http.Client) {
-	c.client.HTTPClient = client
-}
-
-func (c *Client) Report(ctx context.Context, query Query) (youtube.ListResult, error) {
-	if len(query.Metrics) == 0 {
-		return youtube.ListResult{}, errors.New("analytics metrics cannot be empty")
-	}
-	limit := query.Limit
-	if limit == 0 {
-		limit = MaxResults
-	}
-	if limit < 1 || limit > MaxResults {
-		return youtube.ListResult{}, fmt.Errorf("analytics limit must be between 1 and %d", MaxResults)
-	}
-	startIndex := query.StartIndex
-	if startIndex == 0 {
-		startIndex = 1
-	}
-	params := url.Values{
-		"ids":        {"channel==MINE"},
-		"startDate":  {query.StartDate},
-		"endDate":    {query.EndDate},
-		"metrics":    {strings.Join(query.Metrics, ",")},
-		"maxResults": {strconv.Itoa(limit)},
-		"startIndex": {strconv.Itoa(startIndex)},
-	}
-	if len(query.Dimensions) > 0 {
-		params.Set("dimensions", strings.Join(query.Dimensions, ","))
-	}
-	if query.Filters != "" {
-		params.Set("filters", query.Filters)
-	}
-	if query.Sort != "" {
-		params.Set("sort", query.Sort)
-	}
-	var response Response
-	if err := c.client.GetJSON(ctx, "reports", params, true, &response); err != nil {
-		return youtube.ListResult{}, err
-	}
-	return youtube.ListResult{Items: Normalize(response), Requests: 1}, nil
-}
-
-func Normalize(response Response) []map[string]any {
-	items := make([]map[string]any, 0, len(response.Rows))
-	for _, row := range response.Rows {
-		item := make(map[string]any, len(response.ColumnHeaders))
-		for index, header := range response.ColumnHeaders {
-			if index < len(row) {
-				item[header.Name] = row[index]
-			} else {
-				item[header.Name] = nil
-			}
-		}
-		items = append(items, item)
-	}
-	return items
-}
diff --git a/internal/analytics/client_test.go b/internal/analytics/client_test.go
deleted file mode 100644
index 7d1d9d0..0000000
--- a/internal/analytics/client_test.go
+++ /dev/null
@@ -1,53 +0,0 @@
-package analytics
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-	"time"
-)
-
-func TestReportNormalizesRowsByColumnName(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v2/reports" {
-			t.Errorf("path = %q", r.URL.Path)
-		}
-		if r.Header.Get("Authorization") != "Bearer analytics-token" {
-			t.Errorf("authorization = %q", r.Header.Get("Authorization"))
-		}
-		query := r.URL.Query()
-		if query.Get("ids") != "channel==MINE" || query.Get("metrics") != "views,estimatedMinutesWatched" || query.Get("dimensions") != "day" || query.Get("maxResults") != "25" || query.Get("startIndex") != "1" {
-			t.Errorf("query = %s", r.URL.RawQuery)
-		}
-		_, _ = w.Write([]byte(`{"columnHeaders":[{"name":"day","columnType":"DIMENSION","dataType":"STRING"},{"name":"views","columnType":"METRIC","dataType":"INTEGER"},{"name":"estimatedMinutesWatched","columnType":"METRIC","dataType":"FLOAT"}],"rows":[["2026-01-01",12,3.5],["2026-01-02",8,2.25]]}`))
-	}))
-	defer server.Close()
-	client := NewClient(func(context.Context, bool) (string, error) { return "analytics-token", nil }, time.Second)
-	client.SetBaseURL(server.URL + "/v2")
-	client.SetHTTPClient(server.Client())
-	result, err := client.Report(context.Background(), Query{
-		StartDate: "2026-01-01", EndDate: "2026-01-02", Metrics: []string{"views", "estimatedMinutesWatched"}, Dimensions: []string{"day"}, Limit: 25,
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(result.Items) != 2 || result.Requests != 1 || result.Items[0]["day"] != "2026-01-01" {
-		t.Fatalf("result = %#v", result)
-	}
-	views, ok := result.Items[0]["views"].(json.Number)
-	if !ok || views.String() != "12" {
-		t.Fatalf("views = %T(%v)", result.Items[0]["views"], result.Items[0]["views"])
-	}
-}
-
-func TestNormalizeFillsMissingCells(t *testing.T) {
-	items := Normalize(Response{
-		ColumnHeaders: []ColumnHeader{{Name: "day"}, {Name: "views"}},
-		Rows:          [][]any{{"2026-01-01"}},
-	})
-	if len(items) != 1 || items[0]["day"] != "2026-01-01" || items[0]["views"] != nil {
-		t.Fatalf("items = %#v", items)
-	}
-}
diff --git a/internal/cli/analytics.go b/internal/cli/analytics.go
deleted file mode 100644
index ff6198c..0000000
--- a/internal/cli/analytics.go
+++ /dev/null
@@ -1,211 +0,0 @@
-package cli
-
-import (
-	"fmt"
-	"strings"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"open-yt-cli/internal/analytics"
-	"open-yt-cli/internal/config"
-	"open-yt-cli/internal/youtube"
-)
-
-type analyticsFlags struct {
-	start   string
-	end     string
-	filters string
-	sort    string
-	limit   int
-}
-
-func (a *App) analyticsCommand() *cobra.Command {
-	command := &cobra.Command{
-		Use:   "analytics",
-		Short: "Read analytics for your authorized YouTube channel (OAuth required)",
-	}
-	command.AddCommand(
-		a.analyticsReportCommand(),
-		a.analyticsOverviewCommand(),
-		a.analyticsVideoCommand(),
-		a.analyticsTrafficSourcesCommand(),
-		a.analyticsDemographicsCommand(),
-	)
-	return command
-}
-
-func (a *App) analyticsReportCommand() *cobra.Command {
-	var flags analyticsFlags
-	var metrics, dimensions string
-	cmd := &cobra.Command{
-		Use:   "report",
-		Short: "Run a raw YouTube Analytics report",
-		Args:  exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			metricList := csvValues(metrics)
-			if len(metricList) == 0 {
-				return &UsageError{Message: "--metrics is required"}
-			}
-			return a.runAnalytics(cmd, flags, analytics.Query{
-				Metrics:    metricList,
-				Dimensions: csvValues(dimensions),
-			}, append(csvValues(dimensions), metricList...))
-		},
-	}
-	a.addAnalyticsFlags(cmd, &flags)
-	cmd.Flags().StringVar(&metrics, "metrics", "", "required comma-separated Analytics metrics")
-	cmd.Flags().StringVar(&dimensions, "dimensions", "", "comma-separated Analytics dimensions")
-	return cmd
-}
-
-func (a *App) analyticsOverviewCommand() *cobra.Command {
-	var flags analyticsFlags
-	var by string
-	// Note: thumbnail impressions and impression CTR are Studio-only; the
-	// Analytics API has no such metrics.
-	metrics := []string{"views", "estimatedMinutesWatched", "averageViewDuration", "averageViewPercentage", "subscribersGained"}
-	cmd := &cobra.Command{
-		Use:   "overview",
-		Short: "Show channel views, watch time, retention, and subscribers gained",
-		Args:  exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			if err := validateEnum("--by", by, "day", "month"); err != nil {
-				return err
-			}
-			dimensions := csvValues(by)
-			return a.runAnalytics(cmd, flags, analytics.Query{Metrics: metrics, Dimensions: dimensions}, append(dimensions, metrics...))
-		},
-	}
-	a.addAnalyticsFlags(cmd, &flags)
-	cmd.Flags().StringVar(&by, "by", "", "group by day or month")
-	return cmd
-}
-
-func (a *App) analyticsVideoCommand() *cobra.Command {
-	var flags analyticsFlags
-	metrics := []string{"views", "estimatedMinutesWatched", "averageViewDuration", "likes", "comments", "subscribersGained"}
-	cmd := &cobra.Command{
-		Use:   "video ",
-		Short: "Show core analytics metrics for one owned video",
-		Args:  exactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			query := analytics.Query{Metrics: metrics, Filters: "video==" + args[0]}
-			return a.runAnalytics(cmd, flags, query, metrics)
-		},
-	}
-	a.addAnalyticsFlags(cmd, &flags)
-	return cmd
-}
-
-func (a *App) analyticsTrafficSourcesCommand() *cobra.Command {
-	var flags analyticsFlags
-	metrics := []string{"views", "estimatedMinutesWatched"}
-	dimensions := []string{"insightTrafficSourceType"}
-	cmd := &cobra.Command{
-		Use:   "traffic-sources",
-		Short: "Break views and watch time down by traffic source",
-		Args:  exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			return a.runAnalytics(cmd, flags, analytics.Query{Metrics: metrics, Dimensions: dimensions}, append(dimensions, metrics...))
-		},
-	}
-	a.addAnalyticsFlags(cmd, &flags)
-	return cmd
-}
-
-func (a *App) analyticsDemographicsCommand() *cobra.Command {
-	var flags analyticsFlags
-	metrics := []string{"viewerPercentage"}
-	dimensions := []string{"ageGroup", "gender"}
-	cmd := &cobra.Command{
-		Use:   "demographics",
-		Short: "Break viewer percentage down by age group and gender",
-		Args:  exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			return a.runAnalytics(cmd, flags, analytics.Query{Metrics: metrics, Dimensions: dimensions}, append(dimensions, metrics...))
-		},
-	}
-	a.addAnalyticsFlags(cmd, &flags)
-	return cmd
-}
-
-func (a *App) addAnalyticsFlags(cmd *cobra.Command, flags *analyticsFlags) {
-	now := time.Now
-	if a.Now != nil {
-		now = a.Now
-	}
-	end := now().UTC().AddDate(0, 0, -1)
-	start := end.AddDate(0, 0, -27)
-	cmd.Flags().StringVar(&flags.start, "start", start.Format(time.DateOnly), "report start date (YYYY-MM-DD; default: 28 days ending yesterday)")
-	cmd.Flags().StringVar(&flags.end, "end", end.Format(time.DateOnly), "report end date (YYYY-MM-DD; default: yesterday)")
-	cmd.Flags().StringVar(&flags.filters, "filters", "", "Analytics filter expression")
-	cmd.Flags().StringVar(&flags.sort, "sort", "", "comma-separated Analytics sort fields")
-	cmd.Flags().IntVar(&flags.limit, "limit", analytics.MaxResults, fmt.Sprintf("maximum rows (1-%d)", analytics.MaxResults))
-}
-
-func (a *App) runAnalytics(cmd *cobra.Command, flags analyticsFlags, query analytics.Query, defaultColumns []string) error {
-	if err := validateAnalyticsDates(flags.start, flags.end); err != nil {
-		return err
-	}
-	if flags.limit < 1 || flags.limit > analytics.MaxResults {
-		return &UsageError{Message: fmt.Sprintf("--limit must be between 1 and %d", analytics.MaxResults)}
-	}
-	credentials, err := config.Load()
-	if err != nil {
-		return err
-	}
-	if credentials.OAuth == nil {
-		return fmt.Errorf("%w; analytics requires OAuth", youtube.ErrMissingOAuth)
-	}
-	source, err := a.oauthTokenSource(credentials.OAuth)
-	if err != nil {
-		return err
-	}
-	client := analytics.NewClient(source.AccessToken, a.timeout)
-	if a.AnalyticsBaseURL != "" {
-		client.SetBaseURL(a.AnalyticsBaseURL)
-	}
-	if a.HTTPClient != nil {
-		client.SetHTTPClient(a.HTTPClient)
-	}
-	query.StartDate = flags.start
-	query.EndDate = flags.end
-	if query.Filters == "" {
-		query.Filters = flags.filters
-	} else if flags.filters != "" {
-		query.Filters += ";" + flags.filters
-	}
-	query.Sort = flags.sort
-	query.Limit = flags.limit
-	result, err := client.Report(cmd.Context(), query)
-	if err != nil {
-		return oauthAuthHint(err)
-	}
-	return a.renderResult(result, defaultColumns)
-}
-
-func validateAnalyticsDates(start, end string) error {
-	startDate, err := time.Parse(time.DateOnly, start)
-	if err != nil || startDate.Format(time.DateOnly) != start {
-		return &UsageError{Message: "--start must use YYYY-MM-DD"}
-	}
-	endDate, err := time.Parse(time.DateOnly, end)
-	if err != nil || endDate.Format(time.DateOnly) != end {
-		return &UsageError{Message: "--end must use YYYY-MM-DD"}
-	}
-	if startDate.After(endDate) {
-		return &UsageError{Message: "--start cannot be after --end"}
-	}
-	return nil
-}
-
-func csvValues(value string) []string {
-	var values []string
-	for _, entry := range strings.Split(value, ",") {
-		if entry = strings.TrimSpace(entry); entry != "" {
-			values = append(values, entry)
-		}
-	}
-	return values
-}
diff --git a/internal/cli/app.go b/internal/cli/app.go
deleted file mode 100644
index fdd8b59..0000000
--- a/internal/cli/app.go
+++ /dev/null
@@ -1,532 +0,0 @@
-// Package cli defines the oytc command-line interface.
-package cli
-
-import (
-	"bufio"
-	"errors"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"os"
-	"strings"
-	"time"
-
-	"github.com/spf13/cobra"
-	"golang.org/x/term"
-
-	"open-yt-cli/internal/config"
-	"open-yt-cli/internal/output"
-	"open-yt-cli/internal/update"
-	"open-yt-cli/internal/version"
-	"open-yt-cli/internal/youtube"
-)
-
-type UsageError struct{ Message string }
-
-func (e *UsageError) Error() string { return e.Message }
-
-type App struct {
-	In               io.Reader
-	Out              io.Writer
-	Err              io.Writer
-	HTTPClient       *http.Client
-	BaseURL          string
-	AnalyticsBaseURL string
-	OAuthAuthURL     string
-	OAuthTokenURL    string
-	OAuthRevokeURL   string
-	OpenBrowser      func(string) error
-	Now              func() time.Time
-	ReadSecret       func() (string, error)
-	// stdin buffers a.In so consecutive prompts (e.g. OAuth client ID then
-	// secret) never lose bytes prefetched by an earlier bufio.Reader.
-	stdin       *bufio.Reader
-	IsOutputTTY bool
-	// UpdaterFactory lets tests replace the self-updater's endpoints,
-	// HTTP client, and target executable.
-	UpdaterFactory func(*update.Updater) *update.Updater
-	// SkillInstallPath overrides ~/.agents/skills/oytc in tests.
-	SkillInstallPath string
-
-	format   string
-	columns  []string
-	noHeader bool
-	noColor  bool
-	quiet    bool
-	timeout  time.Duration
-}
-
-type listFlags struct {
-	pageSize  int
-	pageToken string
-	all       bool
-	limit     int
-}
-
-type apiFlags struct {
-	parts  string
-	fields string
-	hl     string
-}
-
-func New() *App {
-	app := &App{In: os.Stdin, Out: os.Stdout, Err: os.Stderr, BaseURL: youtube.DefaultBaseURL, timeout: 20 * time.Second, Now: time.Now}
-	app.IsOutputTTY = term.IsTerminal(int(os.Stdout.Fd()))
-	app.ReadSecret = app.readSecret
-	return app
-}
-
-func (a *App) Root() *cobra.Command {
-	root := &cobra.Command{
-		Use:           "oytc",
-		Short:         "Read YouTube data and your channel analytics",
-		Version:       version.Get().Version,
-		SilenceErrors: true,
-		SilenceUsage:  true,
-		Long: "oytc is a read-only CLI for public YouTube data and your own channel analytics.\n" +
-			"API keys cover public data; OAuth enables read-only owner analytics.\n\n" +
-			"Get started: oytc login, then oytc status --check.\n" +
-			"Docs: https://github.com/davis7dotsh/open-yt-cli/blob/main/docs/commands.md",
-	}
-	root.SetIn(a.In)
-	root.SetOut(a.Out)
-	root.SetErr(a.Err)
-	root.SetVersionTemplate("oytc {{.Version}}\n")
-	root.PersistentFlags().StringVarP(&a.format, "format", "f", "", "output format: table, json, jsonl, or tsv (default: table on a TTY, json otherwise)")
-	root.PersistentFlags().StringSliceVar(&a.columns, "columns", nil, "table/TSV property paths (comma-separated)")
-	root.PersistentFlags().BoolVar(&a.noHeader, "no-header", false, "omit table/TSV header")
-	root.PersistentFlags().BoolVar(&a.noColor, "no-color", false, "disable color (accepted for scripting; first draft emits no color)")
-	root.PersistentFlags().BoolVarP(&a.quiet, "quiet", "q", false, "suppress human request summaries")
-	root.PersistentFlags().DurationVar(&a.timeout, "timeout", 20*time.Second, "per-request timeout")
-	root.SetFlagErrorFunc(func(_ *cobra.Command, err error) error { return &UsageError{Message: err.Error()} })
-	root.PersistentPreRunE = func(_ *cobra.Command, _ []string) error {
-		format := a.outputFormat()
-		if format != "table" && format != "json" && format != "jsonl" && format != "tsv" {
-			return &UsageError{Message: fmt.Sprintf("unsupported format %q (use table, json, jsonl, or tsv)", format)}
-		}
-		if a.timeout <= 0 {
-			return &UsageError{Message: "--timeout must be positive"}
-		}
-		return nil
-	}
-
-	root.AddCommand(a.authenticationCommands()...)
-	root.AddCommand(a.analyticsCommand())
-	root.AddCommand(a.searchCommand())
-	root.AddCommand(a.channelCommand())
-	root.AddCommand(a.videoCommand())
-	root.AddCommand(a.playlistCommand())
-	root.AddCommand(a.commentCommand())
-	root.AddCommand(a.subscriptionCommand())
-	root.AddCommand(a.liveChatCommand())
-	root.AddCommand(a.categoryCommand(), a.languageCommand(), a.regionCommand())
-	root.AddCommand(a.versionCommand(), a.updateCommand(), a.skillsCommand())
-	return root
-}
-
-func (a *App) searchCommand() *cobra.Command {
-	var flags listFlags
-	var api apiFlags
-	var channelID, channelType, order, publishedAfter, publishedBefore, region, language, safeSearch, resourceType string
-	var eventType, location, locationRadius, topicID, videoCaption, videoCategory, videoDuration, videoEmbeddable, videoLicense, videoPaidProductPlacement, videoSyndicated string
-	cmd := &cobra.Command{
-		Use:   "search [QUERY]",
-		Short: "Search public YouTube resources (1 call from the 100 calls/day search bucket)",
-		Args:  maximumArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			params := url.Values{"part": {partsOr(api.parts, "snippet")}}
-			if len(args) == 1 {
-				params.Set("q", args[0])
-			}
-			requestFields, preserveKind := fieldsWithRequired(api.fields, "items/id/kind")
-			setValues(params, map[string]string{"channelId": channelID, "channelType": channelType, "order": order, "publishedAfter": publishedAfter, "publishedBefore": publishedBefore, "regionCode": region, "relevanceLanguage": language, "safeSearch": safeSearch, "type": resourceType, "eventType": eventType, "location": location, "locationRadius": locationRadius, "topicId": topicID, "videoCaption": videoCaption, "videoCategoryId": videoCategory, "videoDuration": videoDuration, "videoEmbeddable": videoEmbeddable, "videoLicense": videoLicense, "videoPaidProductPlacement": videoPaidProductPlacement, "videoSyndicated": videoSyndicated, "fields": requestFields})
-			if err := validateEnum("--order", order, "date", "rating", "relevance", "title", "videoCount", "viewCount"); err != nil {
-				return err
-			}
-			if err := validateEnum("--safe-search", safeSearch, "moderate", "none", "strict"); err != nil {
-				return err
-			}
-			if err := validateCSVEnum("--type", resourceType, "video", "channel", "playlist"); err != nil {
-				return err
-			}
-			for _, check := range []struct {
-				flag, value string
-				allowed     []string
-			}{
-				{"--channel-type", channelType, []string{"any", "show"}},
-				{"--event-type", eventType, []string{"completed", "live", "upcoming"}},
-				{"--video-caption", videoCaption, []string{"any", "closedCaption", "none"}},
-				{"--video-duration", videoDuration, []string{"any", "short", "medium", "long"}},
-				{"--video-embeddable", videoEmbeddable, []string{"any", "true"}},
-				{"--video-license", videoLicense, []string{"any", "creativeCommon", "youtube"}},
-				{"--video-paid-product-placement", videoPaidProductPlacement, []string{"any", "true"}},
-				{"--video-syndicated", videoSyndicated, []string{"any", "true"}},
-			} {
-				if err := validateEnum(check.flag, check.value, check.allowed...); err != nil {
-					return err
-				}
-			}
-			if err := validateTimestamp("--published-after", publishedAfter); err != nil {
-				return err
-			}
-			if err := validateTimestamp("--published-before", publishedBefore); err != nil {
-				return err
-			}
-			if (location == "") != (locationRadius == "") {
-				return &UsageError{Message: "--location and --location-radius must be used together"}
-			}
-			videoFilter := eventType != "" || location != "" || videoCaption != "" || videoCategory != "" || videoDuration != "" || videoEmbeddable != "" || videoLicense != "" || videoPaidProductPlacement != "" || videoSyndicated != ""
-			if videoFilter && resourceType != "video" {
-				return &UsageError{Message: "video-specific filters require --type video"}
-			}
-			if channelType != "" && resourceType != "channel" {
-				return &UsageError{Message: "--channel-type requires --type channel"}
-			}
-			return a.runFilteredList(cmd, "search", params, flags, searchResultFilter(resourceType, preserveKind), []string{"id.kind", "id.videoId", "id.channelId", "id.playlistId", "snippet.title"})
-		},
-	}
-	addListFlags(cmd, &flags, 25, 50)
-	addAPIFlags(cmd, &api, false)
-	cmd.Flags().StringVar(&channelID, "channel", "", "only resources created by this channel ID")
-	cmd.Flags().StringVar(&channelType, "channel-type", "", "any or show (requires --type channel)")
-	cmd.Flags().StringVar(&order, "order", "relevance", "date, rating, relevance, title, videoCount, or viewCount")
-	cmd.Flags().StringVar(&publishedAfter, "published-after", "", "RFC 3339 lower publication bound")
-	cmd.Flags().StringVar(&publishedBefore, "published-before", "", "RFC 3339 upper publication bound")
-	cmd.Flags().StringVar(®ion, "region", "", "ISO 3166-1 alpha-2 region code")
-	cmd.Flags().StringVar(&language, "language", "", "relevance language code")
-	cmd.Flags().StringVar(&safeSearch, "safe-search", "moderate", "moderate, none, or strict")
-	cmd.Flags().StringVar(&resourceType, "type", "video,channel,playlist", "comma-separated video, channel, and/or playlist")
-	cmd.Flags().StringVar(&eventType, "event-type", "", "completed, live, or upcoming (video searches)")
-	cmd.Flags().StringVar(&location, "location", "", "latitude,longitude for a geographic video search")
-	cmd.Flags().StringVar(&locationRadius, "location-radius", "", "radius such as 5km (requires --location)")
-	cmd.Flags().StringVar(&topicID, "topic", "", "Freebase topic ID")
-	cmd.Flags().StringVar(&videoCaption, "video-caption", "", "any, closedCaption, or none")
-	cmd.Flags().StringVar(&videoCategory, "video-category", "", "video category ID")
-	cmd.Flags().StringVar(&videoDuration, "video-duration", "", "any, short, medium, or long")
-	cmd.Flags().StringVar(&videoEmbeddable, "video-embeddable", "", "any or true")
-	cmd.Flags().StringVar(&videoLicense, "video-license", "", "any, creativeCommon, or youtube")
-	cmd.Flags().StringVar(&videoPaidProductPlacement, "video-paid-product-placement", "", "any or true")
-	cmd.Flags().StringVar(&videoSyndicated, "video-syndicated", "", "any or true")
-	return cmd
-}
-
-func (a *App) client(key string) *youtube.Client {
-	client := youtube.NewClient(key, a.timeout)
-	if a.BaseURL != "" {
-		client.BaseURL = a.BaseURL
-	}
-	if a.HTTPClient != nil {
-		client.HTTPClient = a.HTTPClient
-	}
-	return client
-}
-
-func (a *App) authenticatedClient() (*youtube.Client, error) {
-	credentials, err := config.Load()
-	if err != nil {
-		return nil, err
-	}
-	if credentials.Key != "" {
-		return a.client(credentials.Key), nil
-	}
-	// Only fall back to OAuth for Data API reads when the stored grant
-	// actually covers them; the default analytics-only authorization would
-	// produce an opaque 401/403 instead of a clear "run login" hint.
-	if credentials.OAuth == nil || !hasScope(credentials.OAuth.Scopes, youtubeReadonlyScope) {
-		return nil, youtube.ErrMissingKey
-	}
-	source, err := a.oauthTokenSource(credentials.OAuth)
-	if err != nil {
-		return nil, err
-	}
-	client := a.client("")
-	client.TokenSource = source.AccessToken
-	return client, nil
-}
-
-func hasScope(scopes []string, scope string) bool {
-	for _, granted := range scopes {
-		if granted == scope {
-			return true
-		}
-	}
-	return false
-}
-
-func (a *App) runList(cmd *cobra.Command, resource string, params url.Values, flags listFlags, defaultColumns []string) error {
-	return a.runFilteredList(cmd, resource, params, flags, nil, defaultColumns)
-}
-
-func (a *App) runFilteredList(cmd *cobra.Command, resource string, params url.Values, flags listFlags, filter func(map[string]any) bool, defaultColumns []string) error {
-	client, err := a.authenticatedClient()
-	if err != nil {
-		return err
-	}
-	result, err := client.List(cmd.Context(), resource, params, youtube.PageOptions{All: flags.all, Limit: flags.limit, PageSize: flags.pageSize, PageToken: flags.pageToken, Filter: filter})
-	if err != nil {
-		return err
-	}
-	return a.renderResult(result, defaultColumns)
-}
-
-func searchResultFilter(resourceTypes string, preserveKind bool) func(map[string]any) bool {
-	allowed := make(map[string]bool)
-	for _, resourceType := range strings.Split(resourceTypes, ",") {
-		allowed[strings.TrimSpace(resourceType)] = true
-	}
-	return func(item map[string]any) bool {
-		id, _ := item["id"].(map[string]any)
-		if kind, _ := id["kind"].(string); strings.HasPrefix(kind, "youtube#") {
-			accepted := allowed[strings.TrimPrefix(kind, "youtube#")]
-			if accepted && !preserveKind {
-				delete(id, "kind")
-				if len(id) == 0 {
-					delete(item, "id")
-				}
-			}
-			return accepted
-		}
-		return false
-	}
-}
-
-func fieldsWithRequired(fields, required string) (string, bool) {
-	if fields == "" || fieldSelectorIncludes(fields, required) {
-		return fields, true
-	}
-	return fields + "," + required, false
-}
-
-func stripItemIDs(items []map[string]any, preserve bool) {
-	if preserve {
-		return
-	}
-	for _, item := range items {
-		delete(item, "id")
-	}
-}
-
-func validateRequestedItems(resource string, requested []string, items []map[string]any) error {
-	requestedSet := make(map[string]bool, len(requested))
-	uniqueRequested := make([]string, 0, len(requested))
-	for _, id := range requested {
-		if !requestedSet[id] {
-			requestedSet[id] = true
-			uniqueRequested = append(uniqueRequested, id)
-		}
-	}
-
-	returned := make(map[string]bool, len(items))
-	for _, item := range items {
-		if id, _ := item["id"].(string); id != "" {
-			returned[id] = true
-		}
-	}
-	if len(returned) == 0 && len(items) == len(uniqueRequested) {
-		// --fields may omit IDs, so equal cardinality is the strongest check
-		// available without overriding the caller's partial-response selector.
-		return nil
-	}
-
-	missing := make([]string, 0)
-	if len(returned) > 0 {
-		for _, id := range uniqueRequested {
-			if !returned[id] {
-				missing = append(missing, id)
-			}
-		}
-	} else if len(items) < len(uniqueRequested) {
-		missing = uniqueRequested
-	}
-	if len(missing) == 0 {
-		return nil
-	}
-	return fmt.Errorf("%s not found: %s", resource, strings.Join(missing, ", "))
-}
-
-func (a *App) renderResult(result youtube.ListResult, defaultColumns []string) error {
-	columns := a.columns
-	if len(columns) == 0 {
-		columns = defaultColumns
-	}
-	if err := output.Render(a.Out, result, output.Options{Format: a.outputFormat(), Columns: columns, NoHeader: a.noHeader}); err != nil {
-		return &UsageError{Message: err.Error()}
-	}
-	if !a.quiet && a.outputFormat() == "table" {
-		fmt.Fprintf(a.Err, "%d item(s), %d request(s)", len(result.Items), result.Requests)
-		if result.NextPageToken != "" {
-			fmt.Fprintf(a.Err, "; more available (next token: %s)", result.NextPageToken)
-		}
-		fmt.Fprintln(a.Err)
-	}
-	return nil
-}
-
-func (a *App) outputFormat() string {
-	if a.format != "" {
-		return strings.ToLower(a.format)
-	}
-	if a.IsOutputTTY {
-		return "table"
-	}
-	return "json"
-}
-
-func (a *App) readSecret() (string, error) {
-	if file, ok := a.In.(*os.File); ok && term.IsTerminal(int(file.Fd())) {
-		data, err := term.ReadPassword(int(file.Fd()))
-		return string(data), err
-	}
-	line, err := a.stdinReader().ReadString('\n')
-	if err != nil && !errors.Is(err, io.EOF) {
-		return "", err
-	}
-	return strings.TrimRight(line, "\r\n"), nil
-}
-
-// stdinReader returns a single shared buffered reader over a.In. Creating a
-// fresh bufio.Reader per prompt would drop bytes an earlier reader had already
-// buffered from piped input.
-func (a *App) stdinReader() *bufio.Reader {
-	if a.stdin == nil {
-		a.stdin = bufio.NewReader(a.In)
-	}
-	return a.stdin
-}
-
-func addListFlags(cmd *cobra.Command, flags *listFlags, defaultSize, maxSize int) {
-	cmd.Flags().IntVar(&flags.pageSize, "page-size", defaultSize, fmt.Sprintf("results per request (1-%d)", maxSize))
-	cmd.Flags().StringVar(&flags.pageToken, "page-token", "", "start at this API page token")
-	cmd.Flags().BoolVar(&flags.all, "all", false, "fetch all available pages")
-	cmd.Flags().IntVar(&flags.limit, "limit", 0, "maximum items to emit (0 means no additional limit)")
-	cmd.PreRunE = chainPreRun(cmd.PreRunE, func(_ *cobra.Command, _ []string) error {
-		if flags.pageSize < 1 || flags.pageSize > maxSize {
-			return &UsageError{Message: fmt.Sprintf("--page-size must be between 1 and %d", maxSize)}
-		}
-		if flags.limit < 0 {
-			return &UsageError{Message: "--limit cannot be negative"}
-		}
-		return nil
-	})
-}
-
-func addAPIFlags(cmd *cobra.Command, flags *apiFlags, withHL bool) {
-	cmd.Flags().StringVar(&flags.parts, "parts", "", "comma-separated API resource parts")
-	cmd.Flags().StringVar(&flags.fields, "fields", "", "Google partial-response fields selector")
-	if withHL {
-		cmd.Flags().StringVar(&flags.hl, "hl", "", "localization language code")
-	}
-}
-
-func chainPreRun(first func(*cobra.Command, []string) error, second func(*cobra.Command, []string) error) func(*cobra.Command, []string) error {
-	return func(cmd *cobra.Command, args []string) error {
-		if first != nil {
-			if err := first(cmd, args); err != nil {
-				return err
-			}
-		}
-		return second(cmd, args)
-	}
-}
-
-func exactArgs(count int) cobra.PositionalArgs {
-	return func(_ *cobra.Command, args []string) error {
-		if len(args) != count {
-			return &UsageError{Message: fmt.Sprintf("expected %d argument(s), received %d", count, len(args))}
-		}
-		return nil
-	}
-}
-
-func minimumArgs(count int) cobra.PositionalArgs {
-	return func(_ *cobra.Command, args []string) error {
-		if len(args) < count {
-			return &UsageError{Message: fmt.Sprintf("expected at least %d argument(s), received %d", count, len(args))}
-		}
-		return nil
-	}
-}
-
-func maximumArgs(count int) cobra.PositionalArgs {
-	return func(_ *cobra.Command, args []string) error {
-		if len(args) > count {
-			return &UsageError{Message: fmt.Sprintf("expected at most %d argument(s), received %d", count, len(args))}
-		}
-		return nil
-	}
-}
-
-func partsOr(value, fallback string) string {
-	if strings.TrimSpace(value) == "" {
-		return fallback
-	}
-	return value
-}
-
-func setValues(values url.Values, entries map[string]string) {
-	for key, value := range entries {
-		if value != "" {
-			values.Set(key, value)
-		}
-	}
-}
-
-func valueOr(value, fallback string) string {
-	if value == "" {
-		return fallback
-	}
-	return value
-}
-
-func validateTimestamp(flag, value string) error {
-	if value == "" {
-		return nil
-	}
-	if _, err := time.Parse(time.RFC3339, value); err != nil {
-		return &UsageError{Message: fmt.Sprintf("%s must be an RFC 3339 timestamp", flag)}
-	}
-	return nil
-}
-
-func validateCSVEnum(flag, value string, allowed ...string) error {
-	for _, entry := range strings.Split(value, ",") {
-		if err := validateEnum(flag, strings.TrimSpace(entry), allowed...); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-func validateEnum(flag, value string, allowed ...string) error {
-	if value == "" {
-		return nil
-	}
-	for _, candidate := range allowed {
-		if value == candidate {
-			return nil
-		}
-	}
-	return &UsageError{Message: fmt.Sprintf("%s must be one of: %s", flag, strings.Join(allowed, ", "))}
-}
-
-func validateParts(parts string, forbidden ...string) error {
-	for _, value := range strings.Split(parts, ",") {
-		for _, blocked := range forbidden {
-			if strings.TrimSpace(value) == blocked {
-				return &UsageError{Message: fmt.Sprintf("part %q requires owner/OAuth access and is not supported", blocked)}
-			}
-		}
-	}
-	return nil
-}
-
-func batch(values []string, size int) [][]string {
-	var batches [][]string
-	for len(values) > 0 {
-		count := min(size, len(values))
-		batches = append(batches, values[:count])
-		values = values[count:]
-	}
-	return batches
-}
diff --git a/internal/cli/app_test.go b/internal/cli/app_test.go
deleted file mode 100644
index 23abd13..0000000
--- a/internal/cli/app_test.go
+++ /dev/null
@@ -1,487 +0,0 @@
-package cli
-
-import (
-	"bytes"
-	"encoding/json"
-	"errors"
-	"net/http"
-	"net/http/httptest"
-	"net/url"
-	"os"
-	"path/filepath"
-	"strings"
-	"sync/atomic"
-	"testing"
-
-	"open-yt-cli/internal/config"
-	"open-yt-cli/internal/youtube"
-)
-
-func TestLoginValidatesAndAtomicallySaves(t *testing.T) {
-	var requestKey string
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		requestKey = r.Header.Get("X-Goog-Api-Key")
-		if r.URL.Path != "/youtube/v3/i18nLanguages" {
-			t.Errorf("path = %q", r.URL.Path)
-		}
-		_, _ = w.Write([]byte(`{"items":[{"id":"en"}]}`))
-	}))
-	defer server.Close()
-	dir := t.TempDir()
-	t.Setenv("OYTC_CONFIG_DIR", dir)
-	t.Setenv("OYTC_API_KEY", "")
-	app, out, _ := testApp(server)
-	app.ReadSecret = func() (string, error) { return "login-secret", nil }
-	if err := execute(t, app, "login"); err != nil {
-		t.Fatal(err)
-	}
-	if requestKey != "login-secret" {
-		t.Fatalf("validation header = %q", requestKey)
-	}
-	credentials, err := config.Load()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if credentials.Key != "login-secret" {
-		t.Fatalf("saved key = %q", credentials.Key)
-	}
-	if bytes.Contains(out.Bytes(), []byte("login-secret")) {
-		t.Fatalf("key leaked in output: %s", out.String())
-	}
-}
-
-func TestOAuthLoginLoopbackSavesWithoutClobberingAPIKey(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("OYTC_CONFIG_DIR", dir)
-	t.Setenv("OYTC_API_KEY", "")
-	t.Setenv("OYTC_OAUTH_CLIENT_ID", "desktop-id")
-	t.Setenv("OYTC_OAUTH_CLIENT_SECRET", "desktop-secret")
-	if _, err := config.Save("existing-key"); err != nil {
-		t.Fatal(err)
-	}
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/token" {
-			t.Errorf("path = %q", r.URL.Path)
-		}
-		if err := r.ParseForm(); err != nil {
-			t.Error(err)
-		}
-		if r.Form.Get("code") != "login-code" || r.Form.Get("client_secret") != "desktop-secret" {
-			t.Errorf("token form = %v", r.Form)
-		}
-		// x/oauth2 parses token responses by Content-Type.
-		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write([]byte(`{"access_token":"access-secret","refresh_token":"refresh-secret","expires_in":3600,"token_type":"Bearer","scope":"https://www.googleapis.com/auth/youtube.readonly https://www.googleapis.com/auth/yt-analytics.readonly"}`))
-	}))
-	defer server.Close()
-	app, out, _ := testApp(server)
-	app.OpenBrowser = func(target string) error {
-		parsed, err := url.Parse(target)
-		if err != nil {
-			return err
-		}
-		callback := parsed.Query().Get("redirect_uri") + "?code=login-code&state=" + url.QueryEscape(parsed.Query().Get("state"))
-		go func() {
-			request, err := http.NewRequestWithContext(t.Context(), http.MethodGet, callback, nil)
-			if err != nil {
-				return
-			}
-			if response, err := http.DefaultClient.Do(request); err == nil {
-				response.Body.Close()
-			}
-		}()
-		return nil
-	}
-	if err := execute(t, app, "login", "--oauth"); err != nil {
-		t.Fatal(err)
-	}
-	credentials, err := config.Load()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if credentials.Key != "existing-key" || credentials.OAuth == nil || credentials.OAuth.RefreshToken != "refresh-secret" {
-		t.Fatalf("credentials = %#v", credentials)
-	}
-	for _, secret := range []string{"desktop-secret", "access-secret", "refresh-secret"} {
-		if bytes.Contains(out.Bytes(), []byte(secret)) {
-			t.Fatalf("OAuth secret leaked in output: %s", out.String())
-		}
-	}
-}
-
-func TestAnalyticsCommands(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "")
-	if _, err := config.SaveOAuth(config.OAuthCredentials{
-		ClientID: "id", ClientSecret: "secret", AccessToken: "oauth-access", RefreshToken: "oauth-refresh",
-		Expiry: "2099-01-01T00:00:00Z", Scopes: []string{youtubeReadonlyScope, analyticsReadonlyScope},
-	}); err != nil {
-		t.Fatal(err)
-	}
-	tests := []struct {
-		name       string
-		args       []string
-		metrics    string
-		dimensions string
-		filters    string
-	}{
-		{"report", []string{"analytics", "report", "--metrics", "views,likes", "--dimensions", "day"}, "views,likes", "day", ""},
-		{"overview", []string{"analytics", "overview", "--by", "month"}, "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained", "month", ""},
-		{"video", []string{"analytics", "video", "video-id"}, "views,estimatedMinutesWatched,averageViewDuration,likes,comments,subscribersGained", "", "video==video-id"},
-		{"traffic", []string{"analytics", "traffic-sources"}, "views,estimatedMinutesWatched", "insightTrafficSourceType", ""},
-		{"demographics", []string{"analytics", "demographics"}, "viewerPercentage", "ageGroup,gender", ""},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-				if r.URL.Path != "/youtubeanalytics/v2/reports" || r.Header.Get("Authorization") != "Bearer oauth-access" {
-					t.Errorf("request = %s, authorization = %q", r.URL.Path, r.Header.Get("Authorization"))
-				}
-				query := r.URL.Query()
-				if query.Get("ids") != "channel==MINE" || query.Get("metrics") != test.metrics || query.Get("dimensions") != test.dimensions || query.Get("filters") != test.filters {
-					t.Errorf("query = %s", r.URL.RawQuery)
-				}
-				_, _ = w.Write([]byte(`{"columnHeaders":[{"name":"views"}],"rows":[[42]]}`))
-			}))
-			defer server.Close()
-			app, out, _ := testApp(server)
-			args := append(append([]string(nil), test.args...), "--start", "2026-01-01", "--end", "2026-01-28", "--format", "json")
-			if err := execute(t, app, args...); err != nil {
-				t.Fatal(err)
-			}
-			if !bytes.Contains(out.Bytes(), []byte(`"views": 42`)) {
-				t.Fatalf("output = %s", out.String())
-			}
-		})
-	}
-}
-
-func TestAnalyticsRequiresOAuthAndValidDates(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "")
-	app, _, _ := testApp(nil)
-	err := execute(t, app, "analytics", "report", "--metrics", "views", "--start", "not-a-date")
-	var usage *UsageError
-	if !errors.As(err, &usage) {
-		t.Fatalf("expected UsageError, got %T: %v", err, err)
-	}
-	err = execute(t, app, "analytics", "report", "--metrics", "views", "--start", "2026-01-01", "--end", "2026-01-28")
-	if !errors.Is(err, youtube.ErrMissingOAuth) || !bytes.Contains([]byte(err.Error()), []byte("login --oauth")) {
-		t.Fatalf("expected missing OAuth hint, got %T: %v", err, err)
-	}
-}
-
-func TestStatusHidesOAuthSecretsAndLogoutRevokes(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "")
-	if _, err := config.SaveOAuth(config.OAuthCredentials{
-		ClientID: "visible-client-id", ClientSecret: "hidden-client-secret", AccessToken: "hidden-access-token",
-		RefreshToken: "hidden-refresh-token", Expiry: "2099-01-01T00:00:00Z", Scopes: []string{analyticsReadonlyScope},
-	}); err != nil {
-		t.Fatal(err)
-	}
-	var revoked string
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/revoke" {
-			t.Errorf("path = %q", r.URL.Path)
-		}
-		if err := r.ParseForm(); err != nil {
-			t.Error(err)
-		}
-		revoked = r.Form.Get("token")
-	}))
-	defer server.Close()
-	app, out, _ := testApp(server)
-	if err := execute(t, app, "status", "--format", "json"); err != nil {
-		t.Fatal(err)
-	}
-	if !bytes.Contains(out.Bytes(), []byte("visible-client-id")) {
-		t.Fatalf("status omitted client ID: %s", out.String())
-	}
-	for _, secret := range []string{"hidden-client-secret", "hidden-access-token", "hidden-refresh-token"} {
-		if bytes.Contains(out.Bytes(), []byte(secret)) {
-			t.Fatalf("status leaked OAuth secret: %s", out.String())
-		}
-	}
-	app, _, _ = testApp(server)
-	if err := execute(t, app, "logout"); err != nil {
-		t.Fatal(err)
-	}
-	if revoked != "hidden-refresh-token" {
-		t.Fatalf("revoked token = %q", revoked)
-	}
-	credentials, err := config.Load()
-	if err != nil || credentials.OAuth != nil {
-		t.Fatalf("credentials after logout = %#v, %v", credentials, err)
-	}
-}
-
-func TestSearchRequestAndPagination(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "search-secret")
-	var requests atomic.Int32
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		request := requests.Add(1)
-		if r.Header.Get("X-Goog-Api-Key") != "search-secret" {
-			t.Errorf("missing key header")
-		}
-		if r.URL.Query().Get("key") != "" {
-			t.Errorf("key leaked in query")
-		}
-		if r.URL.Query().Get("q") != "go testing" || r.URL.Query().Get("type") != "video" || r.URL.Query().Get("regionCode") != "CA" {
-			t.Errorf("unexpected query: %s", r.URL.RawQuery)
-		}
-		if request == 1 {
-			_, _ = w.Write([]byte(`{"items":[{"id":{"kind":"youtube#video","videoId":"a"}}],"nextPageToken":"p2"}`))
-		} else {
-			if r.URL.Query().Get("pageToken") != "p2" {
-				t.Errorf("page token = %q", r.URL.Query().Get("pageToken"))
-			}
-			_, _ = w.Write([]byte(`{"items":[{"id":{"kind":"youtube#video","videoId":"b"}}]}`))
-		}
-	}))
-	defer server.Close()
-	app, out, _ := testApp(server)
-	err := execute(t, app, "search", "go testing", "--type", "video", "--region", "CA", "--all", "--format", "json")
-	if err != nil {
-		t.Fatal(err)
-	}
-	var result struct {
-		Items    []map[string]any `json:"items"`
-		Requests int              `json:"requests"`
-	}
-	if err := json.Unmarshal(out.Bytes(), &result); err != nil {
-		t.Fatal(err)
-	}
-	if len(result.Items) != 2 || result.Requests != 2 {
-		t.Fatalf("unexpected output: %s", out.String())
-	}
-}
-
-func TestSearchFiltersUnexpectedResourceKindsBeforeLimit(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "key")
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Query().Get("type") != "video" {
-			t.Errorf("type = %q", r.URL.Query().Get("type"))
-		}
-		if !strings.Contains(r.URL.Query().Get("fields"), "items/id/kind") {
-			t.Errorf("fields = %q", r.URL.Query().Get("fields"))
-		}
-		_, _ = w.Write([]byte(`{"items":[{"id":{"kind":"youtube#channel","channelId":"wrong"},"snippet":{"title":"wrong"}},{"id":{"kind":"youtube#video"},"snippet":{"title":"right"}}]}`))
-	}))
-	defer server.Close()
-	app, out, _ := testApp(server)
-	if err := execute(t, app, "search", "OpenAI", "--type", "video", "--limit", "1", "--fields", "items(id/channelId,snippet/title)", "--format", "json"); err != nil {
-		t.Fatal(err)
-	}
-	var result youtube.ListResult
-	if err := json.Unmarshal(out.Bytes(), &result); err != nil {
-		t.Fatal(err)
-	}
-	if len(result.Items) != 1 {
-		t.Fatalf("items = %s", out.String())
-	}
-	if _, present := result.Items[0]["id"]; present {
-		t.Fatalf("internally required ID leaked into output: %s", out.String())
-	}
-	snippet, _ := result.Items[0]["snippet"].(map[string]any)
-	if snippet["title"] != "right" {
-		t.Fatalf("unexpected item: %s", out.String())
-	}
-}
-
-func TestDirectGetCommandsRejectMissingResources(t *testing.T) {
-	tests := []struct {
-		name string
-		args []string
-	}{
-		{"channel", []string{"channel", "get", "UC1234567890123456789012"}},
-		{"video", []string{"video", "get", "missing-video"}},
-		{"video stats", []string{"video", "stats", "missing-video"}},
-		{"playlist", []string{"playlist", "get", "missing-playlist"}},
-		{"comment", []string{"comment", "get", "missing-comment"}},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-			t.Setenv("OYTC_API_KEY", "key")
-			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-				_, _ = w.Write([]byte(`{"items":[]}`))
-			}))
-			defer server.Close()
-			app, _, _ := testApp(server)
-			err := execute(t, app, append(test.args, "--format", "json")...)
-			if err == nil || !strings.Contains(err.Error(), "not found") {
-				t.Fatalf("expected not-found error, got %v", err)
-			}
-		})
-	}
-}
-
-func TestDirectGetReportsOnlyMissingIDs(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "key")
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if !strings.Contains(r.URL.Query().Get("fields"), "items/id") {
-			t.Errorf("fields = %q", r.URL.Query().Get("fields"))
-		}
-		_, _ = w.Write([]byte(`{"items":[{"id":"present"}]}`))
-	}))
-	defer server.Close()
-	app, _, _ := testApp(server)
-	err := execute(t, app, "video", "get", "present", "missing", "--fields", "items(snippet/title)", "--format", "json")
-	if err == nil || err.Error() != "videos not found: missing" {
-		t.Fatalf("error = %v", err)
-	}
-}
-
-func TestValidateRequestedItemsHandlesDuplicatesAcrossBatches(t *testing.T) {
-	requested := make([]string, 51)
-	for index := range requested {
-		requested[index] = "present"
-	}
-	requested = append(requested, "missing")
-	items := []map[string]any{{"id": "present"}, {"id": "present"}}
-	if err := validateRequestedItems("videos", requested, items); err == nil || err.Error() != "videos not found: missing" {
-		t.Fatalf("error = %v", err)
-	}
-}
-
-func TestVideoTrainabilityRequiresNoKeyAndSendsNone(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "")
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Header.Get("X-Goog-Api-Key") != "" || r.URL.Query().Get("key") != "" {
-			t.Errorf("trainability sent a key")
-		}
-		if r.URL.Query().Get("id") != "video123" {
-			t.Errorf("id = %q", r.URL.Query().Get("id"))
-		}
-		_, _ = w.Write([]byte(`{"kind":"youtube#videoTrainability","videoId":"video123","permitted":["none"]}`))
-	}))
-	defer server.Close()
-	app, out, _ := testApp(server)
-	if err := execute(t, app, "video", "trainability", "video123", "--format", "json"); err != nil {
-		t.Fatal(err)
-	}
-	if !bytes.Contains(out.Bytes(), []byte(`"videoId": "video123"`)) {
-		t.Fatalf("unexpected output: %s", out.String())
-	}
-}
-
-func TestChannelUploadsResolvesPlaylistAndListsItems(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "key")
-	channelID := "UC1234567890123456789012"
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch r.URL.Path {
-		case "/youtube/v3/channels":
-			if r.URL.Query().Get("id") != channelID || r.URL.Query().Get("part") != "contentDetails" {
-				t.Errorf("channel query: %s", r.URL.RawQuery)
-			}
-			_, _ = w.Write([]byte(`{"items":[{"contentDetails":{"relatedPlaylists":{"uploads":"UUuploads"}}}]}`))
-		case "/youtube/v3/playlistItems":
-			if r.URL.Query().Get("playlistId") != "UUuploads" {
-				t.Errorf("playlist query: %s", r.URL.RawQuery)
-			}
-			_, _ = w.Write([]byte(`{"items":[{"contentDetails":{"videoId":"v1"}}]}`))
-		default:
-			t.Errorf("unexpected path %q", r.URL.Path)
-		}
-	}))
-	defer server.Close()
-	app, out, _ := testApp(server)
-	if err := execute(t, app, "channel", "uploads", channelID, "--format", "json"); err != nil {
-		t.Fatal(err)
-	}
-	if !bytes.Contains(out.Bytes(), []byte(`"videoId": "v1"`)) {
-		t.Fatalf("unexpected output: %s", out.String())
-	}
-}
-
-func TestLiveChatStreamPollsWithTokenAndDeduplicates(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "key")
-	var requests atomic.Int32
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		request := requests.Add(1)
-		if request == 1 {
-			_, _ = w.Write([]byte(`{"items":[{"id":"a","snippet":{"displayMessage":"first"}}],"nextPageToken":"resume","pollingIntervalMillis":1}`))
-			return
-		}
-		if r.URL.Query().Get("pageToken") != "resume" {
-			t.Errorf("page token = %q", r.URL.Query().Get("pageToken"))
-		}
-		_, _ = w.Write([]byte(`{"items":[{"id":"a"},{"id":"b","snippet":{"displayMessage":"second"}}],"nextPageToken":"done","offlineAt":"2025-01-01T00:00:00Z"}`))
-	}))
-	defer server.Close()
-	app, out, _ := testApp(server)
-	if err := execute(t, app, "live-chat", "stream", "--chat-id", "chat", "--format", "jsonl", "--page-size", "200"); err != nil {
-		t.Fatal(err)
-	}
-	if requests.Load() != 2 {
-		t.Fatalf("requests = %d", requests.Load())
-	}
-	lines := bytes.Split(bytes.TrimSpace(out.Bytes()), []byte("\n"))
-	if len(lines) != 2 || bytes.Count(out.Bytes(), []byte(`"id":"a"`)) != 1 || bytes.Count(out.Bytes(), []byte(`"id":"b"`)) != 1 {
-		t.Fatalf("unexpected stream: %s", out.String())
-	}
-}
-
-func TestCommentThreadsRejectsIncompatibleFiltersWithoutRequest(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "key")
-	server := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { t.Fatal("unexpected request") }))
-	defer server.Close()
-	app, _, _ := testApp(server)
-	err := execute(t, app, "comment", "threads", "--video", "v", "--channel", "c")
-	var usage *UsageError
-	if err == nil || !errors.As(err, &usage) {
-		t.Fatalf("expected UsageError, got %T: %v", err, err)
-	}
-}
-
-func TestStatusIsLocalOnlyByDefault(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("OYTC_CONFIG_DIR", dir)
-	t.Setenv("OYTC_API_KEY", "ephemeral-secret")
-	server := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { t.Fatal("status made a remote request") }))
-	defer server.Close()
-	app, out, _ := testApp(server)
-	if err := execute(t, app, "status", "--format", "json"); err != nil {
-		t.Fatal(err)
-	}
-	if bytes.Contains(out.Bytes(), []byte("ephemeral-secret")) || !bytes.Contains(out.Bytes(), []byte("sha256:")) {
-		t.Fatalf("unsafe status output: %s", out.String())
-	}
-	if _, err := os.Stat(filepath.Join(dir, "auth.json")); !os.IsNotExist(err) {
-		t.Fatalf("status changed config: %v", err)
-	}
-}
-
-func execute(t *testing.T, app *App, args ...string) error {
-	t.Helper()
-	root := app.Root()
-	root.SetArgs(args)
-	return root.ExecuteContext(t.Context())
-}
-
-func testApp(server *httptest.Server) (*App, *bytes.Buffer, *bytes.Buffer) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	app := New()
-	app.In = bytes.NewBuffer(nil)
-	app.Out = out
-	app.Err = errOut
-	if server != nil {
-		app.BaseURL = server.URL + "/youtube/v3"
-		app.AnalyticsBaseURL = server.URL + "/youtubeanalytics/v2"
-		app.OAuthAuthURL = server.URL + "/authorize"
-		app.OAuthTokenURL = server.URL + "/token"
-		app.OAuthRevokeURL = server.URL + "/revoke"
-		app.HTTPClient = server.Client()
-	}
-	app.IsOutputTTY = false
-	return app, out, errOut
-}
diff --git a/internal/cli/auth.go b/internal/cli/auth.go
deleted file mode 100644
index 8ccfc5b..0000000
--- a/internal/cli/auth.go
+++ /dev/null
@@ -1,357 +0,0 @@
-package cli
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"net/url"
-	"strings"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"open-yt-cli/internal/analytics"
-	"open-yt-cli/internal/config"
-	"open-yt-cli/internal/oauth"
-	"open-yt-cli/internal/output"
-	"open-yt-cli/internal/youtube"
-)
-
-const (
-	youtubeReadonlyScope   = "https://www.googleapis.com/auth/youtube.readonly"
-	analyticsReadonlyScope = "https://www.googleapis.com/auth/yt-analytics.readonly"
-)
-
-// oauthScopes covers Analytics reports plus read-only Data API access, so an
-// OAuth-only setup (no API key) can run every public-data command too.
-// Caveat: youtube.readonly is classified sensitive; unverified apps requesting
-// it are hard-blocked for accounts with Advanced Protection or restrictive
-// Workspace policies. Such accounts must verify the consent app first.
-var oauthScopes = []string{analyticsReadonlyScope, youtubeReadonlyScope}
-
-func (a *App) authenticationCommands() []*cobra.Command {
-	var useOAuth bool
-	login := &cobra.Command{
-		Use:   "login",
-		Short: "Validate and save an API key or read-only OAuth authorization",
-		Args:  exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			if useOAuth {
-				return a.loginOAuth(cmd)
-			}
-			return a.loginAPIKey(cmd)
-		},
-	}
-	login.Flags().BoolVar(&useOAuth, "oauth", false, "authorize read-only access to your channel and Analytics")
-
-	var check bool
-	status := &cobra.Command{
-		Use:   "status",
-		Short: "Show API-key and OAuth status; optionally validate them",
-		Args:  exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			return a.runStatus(cmd, check)
-		},
-	}
-	status.Flags().BoolVar(&check, "check", false, "validate configured credentials with the API")
-
-	logout := &cobra.Command{
-		Use:   "logout",
-		Short: "Revoke OAuth best-effort and remove stored credentials",
-		Args:  exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			return a.runLogout(cmd.Context())
-		},
-	}
-	return []*cobra.Command{login, status, logout}
-}
-
-func (a *App) loginAPIKey(cmd *cobra.Command) error {
-	fmt.Fprint(a.Err, "YouTube Data API key: ")
-	key, err := a.ReadSecret()
-	fmt.Fprintln(a.Err)
-	if err != nil {
-		return fmt.Errorf("read API key: %w", err)
-	}
-	key = strings.TrimSpace(key)
-	if key == "" {
-		return &UsageError{Message: "API key cannot be empty"}
-	}
-	client := a.client(key)
-	if _, err := client.Get(cmd.Context(), "i18nLanguages", url.Values{"part": {"snippet"}}); err != nil {
-		return fmt.Errorf("API key validation failed: %w", err)
-	}
-	path, err := config.Save(key)
-	if err != nil {
-		return err
-	}
-	fmt.Fprintf(a.Out, "API key validated and saved to %s (%s)\n", path, config.Fingerprint(key))
-	if config.EnvKeySet() {
-		fmt.Fprintln(a.Out, "Note: OYTC_API_KEY remains the active, higher-precedence credential.")
-	}
-	return nil
-}
-
-func (a *App) loginOAuth(cmd *cobra.Command) error {
-	clientID, clientSecret := config.OAuthBootstrap()
-	var err error
-	if clientID == "" {
-		fmt.Fprint(a.Err, "OAuth client ID: ")
-		clientID, err = a.stdinReader().ReadString('\n')
-		if err != nil && strings.TrimSpace(clientID) == "" {
-			return fmt.Errorf("read OAuth client ID: %w", err)
-		}
-		clientID = strings.TrimSpace(clientID)
-	}
-	if clientSecret == "" {
-		fmt.Fprint(a.Err, "OAuth client secret: ")
-		clientSecret, err = a.ReadSecret()
-		fmt.Fprintln(a.Err)
-		if err != nil {
-			return fmt.Errorf("read OAuth client secret: %w", err)
-		}
-		clientSecret = strings.TrimSpace(clientSecret)
-	}
-	if clientID == "" || clientSecret == "" {
-		return &UsageError{Message: "OAuth client ID and client secret cannot be empty"}
-	}
-
-	token, err := oauth.Login(cmd.Context(), a.oauthConfig(clientID, clientSecret))
-	if err != nil {
-		return fmt.Errorf("OAuth login failed: %w", err)
-	}
-	path, err := config.SaveOAuth(storedOAuth(clientID, clientSecret, token))
-	if err != nil {
-		return err
-	}
-	fmt.Fprintf(a.Out, "OAuth authorization saved to %s\nGranted scopes: %s\n", path, strings.Join(token.Scopes, ", "))
-	return nil
-}
-
-func (a *App) runStatus(cmd *cobra.Command, check bool) error {
-	credentials, err := config.Load()
-	if err != nil {
-		return err
-	}
-	keyConfigured := credentials.Key != ""
-	oauthConfigured := credentials.OAuth != nil
-	state := map[string]any{
-		"path": credentials.Path,
-		"api_key": map[string]any{
-			"configured": keyConfigured,
-			"source":     valueOr(credentials.Source, "none"),
-		},
-		"oauth": oauthStatus(credentials.OAuth),
-	}
-	if keyConfigured {
-		state["api_key"].(map[string]any)["fingerprint"] = config.Fingerprint(credentials.Key)
-	}
-	// Validate every configured credential before failing, so a stale API
-	// key cannot mask a working OAuth authorization (or vice versa).
-	var keyErr, oauthErr error
-	if check {
-		if !keyConfigured && !oauthConfigured {
-			return youtube.ErrMissingKey
-		}
-		if keyConfigured {
-			_, keyErr = a.client(credentials.Key).Get(cmd.Context(), "i18nLanguages", url.Values{"part": {"snippet"}})
-			state["api_key"].(map[string]any)["valid"] = keyErr == nil
-		}
-		if oauthConfigured {
-			oauthErr = a.checkOAuth(cmd.Context(), credentials.OAuth)
-			state["oauth"].(map[string]any)["valid"] = oauthErr == nil
-		}
-	}
-
-	if a.outputFormat() != "table" {
-		columns := a.columns
-		if len(columns) == 0 {
-			columns = []string{"path", "api_key.configured", "api_key.source", "api_key.fingerprint", "oauth.configured", "oauth.client_id", "oauth.scopes", "oauth.expiry"}
-			if check {
-				columns = []string{"path", "api_key.configured", "api_key.source", "api_key.fingerprint", "api_key.valid", "oauth.configured", "oauth.client_id", "oauth.scopes", "oauth.expiry", "oauth.valid"}
-			}
-		}
-		if err := output.RenderObject(a.Out, state, a.outputFormat(), columns, a.noHeader); err != nil {
-			return err
-		}
-		return statusCheckError(keyErr, oauthErr)
-	}
-	fmt.Fprintf(a.Out, "Path: %s\nAPI key configured: %t\nAPI key source: %s\n", credentials.Path, keyConfigured, valueOr(credentials.Source, "none"))
-	if keyConfigured {
-		fmt.Fprintf(a.Out, "API key fingerprint: %s\n", config.Fingerprint(credentials.Key))
-	}
-	fmt.Fprintf(a.Out, "OAuth configured: %t\n", oauthConfigured)
-	if oauthConfigured {
-		fmt.Fprintf(a.Out, "OAuth client ID: %s\nOAuth scopes: %s\nOAuth token expiry: %s\n", credentials.OAuth.ClientID, strings.Join(credentials.OAuth.Scopes, ", "), valueOr(credentials.OAuth.Expiry, "unknown"))
-	}
-	if check {
-		if keyConfigured {
-			fmt.Fprintf(a.Out, "API key remote check: %s\n", checkVerdict(keyErr))
-		}
-		if oauthConfigured {
-			fmt.Fprintf(a.Out, "OAuth remote check: %s\n", checkVerdict(oauthErr))
-		}
-	}
-	return statusCheckError(keyErr, oauthErr)
-}
-
-// checkOAuth validates the stored OAuth authorization against the Analytics
-// API, which is the service analytics commands require.
-func (a *App) checkOAuth(ctx context.Context, stored *config.OAuthCredentials) error {
-	source, err := a.oauthTokenSource(stored)
-	if err != nil {
-		return err
-	}
-	client := analytics.NewClient(source.AccessToken, a.timeout)
-	if a.AnalyticsBaseURL != "" {
-		client.SetBaseURL(a.AnalyticsBaseURL)
-	}
-	if a.HTTPClient != nil {
-		client.SetHTTPClient(a.HTTPClient)
-	}
-	now := time.Now().UTC()
-	_, err = client.Report(ctx, analytics.Query{
-		StartDate: now.AddDate(0, 0, -7).Format("2006-01-02"),
-		EndDate:   now.Format("2006-01-02"),
-		Metrics:   []string{"views"},
-		Limit:     1,
-	})
-	if err != nil {
-		return oauthAuthHint(err)
-	}
-	return nil
-}
-
-func checkVerdict(err error) string {
-	if err != nil {
-		return fmt.Sprintf("invalid (%v)", err)
-	}
-	return "valid"
-}
-
-func statusCheckError(keyErr, oauthErr error) error {
-	if keyErr != nil {
-		return keyErr
-	}
-	return oauthErr
-}
-
-func (a *App) runLogout(ctx context.Context) error {
-	credentials, loadErr := config.Load()
-	if loadErr != nil {
-		// Removal must still work when the file is corrupt; revocation is
-		// impossible without parsed credentials, so warn and continue.
-		fmt.Fprintf(a.Err, "Warning: could not read stored credentials (skipping OAuth revocation): %v\n", loadErr)
-	}
-	if credentials.OAuth != nil {
-		token := credentials.OAuth.RefreshToken
-		if token == "" {
-			token = credentials.OAuth.AccessToken
-		}
-		if err := oauth.Revoke(ctx, a.oauthConfig(credentials.OAuth.ClientID, credentials.OAuth.ClientSecret), token); err != nil {
-			fmt.Fprintf(a.Err, "Warning: could not revoke OAuth token: %v\n", err)
-		}
-	}
-	path, removed, err := config.Remove()
-	if err != nil {
-		return err
-	}
-	if removed {
-		fmt.Fprintf(a.Out, "Removed stored credentials at %s.\n", path)
-	} else {
-		fmt.Fprintf(a.Out, "No stored credentials at %s.\n", path)
-	}
-	if config.EnvKeySet() {
-		fmt.Fprintln(a.Out, "OYTC_API_KEY is still set; environment credentials remain active.")
-	}
-	return nil
-}
-
-func (a *App) oauthConfig(clientID, clientSecret string) oauth.Config {
-	return oauth.Config{
-		ClientID:         clientID,
-		ClientSecret:     clientSecret,
-		Scopes:           oauthScopes,
-		AuthorizationURL: a.OAuthAuthURL,
-		TokenURL:         a.OAuthTokenURL,
-		RevokeURL:        a.OAuthRevokeURL,
-		HTTPClient:       a.HTTPClient,
-		OpenBrowser:      a.OpenBrowser,
-		Out:              a.Err,
-		Timeout:          3 * time.Minute,
-		Now:              a.Now,
-	}
-}
-
-func (a *App) oauthTokenSource(credentials *config.OAuthCredentials) (*oauth.TokenSource, error) {
-	if credentials == nil {
-		return nil, youtube.ErrMissingOAuth
-	}
-	expiry, err := oauth.ParseExpiry(credentials.Expiry)
-	if err != nil {
-		return nil, err
-	}
-	persisted := *credentials
-	persisted.Scopes = append([]string(nil), credentials.Scopes...)
-	clientID, clientSecret := credentials.ClientID, credentials.ClientSecret
-	source := &oauth.TokenSource{
-		Config: a.oauthConfig(clientID, clientSecret),
-		Token: oauth.Token{
-			AccessToken:  credentials.AccessToken,
-			RefreshToken: credentials.RefreshToken,
-			Expiry:       expiry,
-			Scopes:       append([]string(nil), credentials.Scopes...),
-		},
-	}
-	source.OnUpdate = func(token oauth.Token) error {
-		updated := storedOAuth(clientID, clientSecret, token)
-		saved, err := config.SaveRefreshedOAuth(persisted, updated)
-		if saved {
-			persisted = updated
-		}
-		return err
-	}
-	return source, nil
-}
-
-func storedOAuth(clientID, clientSecret string, token oauth.Token) config.OAuthCredentials {
-	return config.OAuthCredentials{
-		ClientID:     clientID,
-		ClientSecret: clientSecret,
-		AccessToken:  token.AccessToken,
-		RefreshToken: token.RefreshToken,
-		Expiry:       oauth.FormatExpiry(token.Expiry),
-		Scopes:       append([]string(nil), token.Scopes...),
-	}
-}
-
-func oauthStatus(credentials *config.OAuthCredentials) map[string]any {
-	if credentials == nil {
-		return map[string]any{"configured": false}
-	}
-	return map[string]any{
-		"configured": true,
-		"client_id":  credentials.ClientID,
-		"scopes":     append([]string(nil), credentials.Scopes...),
-		"expiry":     credentials.Expiry,
-	}
-}
-
-func oauthAuthHint(err error) error {
-	var apiErr *youtube.APIError
-	if strings.Contains(strings.ToLower(err.Error()), "invalid_grant") {
-		return fmt.Errorf("OAuth authorization failed; re-run 'oytc login --oauth': %w", err)
-	}
-	if !errors.As(err, &apiErr) {
-		return err
-	}
-	if apiErr.HTTPStatus == 401 {
-		return fmt.Errorf("OAuth authorization failed; re-run 'oytc login --oauth': %w", err)
-	}
-	for _, reason := range apiErr.Reasons {
-		if strings.EqualFold(reason, "insufficientPermissions") {
-			return fmt.Errorf("OAuth scopes are insufficient; re-run 'oytc login --oauth': %w", err)
-		}
-	}
-	return err
-}
diff --git a/internal/cli/channel_video.go b/internal/cli/channel_video.go
deleted file mode 100644
index 6e371a4..0000000
--- a/internal/cli/channel_video.go
+++ /dev/null
@@ -1,295 +0,0 @@
-package cli
-
-import (
-	"fmt"
-	"net/url"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	"open-yt-cli/internal/output"
-	"open-yt-cli/internal/youtube"
-)
-
-func (a *App) channelCommand() *cobra.Command {
-	channel := &cobra.Command{Use: "channel", Short: "Read channels, activities, sections, and uploads"}
-	channel.AddCommand(a.channelGetCommand(), a.channelActivitiesCommand(), a.channelSectionsCommand(), a.channelUploadsCommand())
-	return channel
-}
-
-func (a *App) channelGetCommand() *cobra.Command {
-	var api apiFlags
-	cmd := &cobra.Command{
-		Use:   "get ...",
-		Short: "Get channels by ID, @handle, or common channel URL",
-		Args:  minimumArgs(1),
-		RunE: func(cmd *cobra.Command, references []string) error {
-			parts := partsOr(api.parts, "snippet,contentDetails,statistics")
-			if err := validateParts(parts, "auditDetails", "contentOwnerDetails"); err != nil {
-				return err
-			}
-			client, err := a.authenticatedClient()
-			if err != nil {
-				return err
-			}
-			ids := make([]string, 0, len(references))
-			requests := 0
-			for _, reference := range references {
-				id, used, err := client.ResolveChannel(cmd.Context(), reference)
-				requests += used
-				if err != nil {
-					return err
-				}
-				ids = append(ids, id)
-			}
-			result := youtube.ListResult{Items: make([]map[string]any, 0), Requests: requests}
-			requestFields, preserveID := fieldsWithRequired(api.fields, "items/id")
-			for _, group := range batch(ids, 50) {
-				params := url.Values{"part": {parts}, "id": {strings.Join(group, ",")}}
-				setValues(params, map[string]string{"hl": api.hl, "fields": requestFields})
-				response, err := client.Get(cmd.Context(), "channels", params)
-				if err != nil {
-					return err
-				}
-				result.Requests++
-				result.Items = append(result.Items, response.Items...)
-			}
-			if err := validateRequestedItems("channels", ids, result.Items); err != nil {
-				return err
-			}
-			stripItemIDs(result.Items, preserveID)
-			return a.renderResult(result, []string{"id", "snippet.title", "statistics.subscriberCount", "statistics.videoCount", "statistics.viewCount"})
-		},
-	}
-	addAPIFlags(cmd, &api, true)
-	return cmd
-}
-
-func (a *App) channelActivitiesCommand() *cobra.Command {
-	var flags listFlags
-	var api apiFlags
-	var publishedAfter, publishedBefore string
-	cmd := &cobra.Command{
-		Use:   "activities ",
-		Short: "List a channel's public activities",
-		Args:  exactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateTimestamp("--published-after", publishedAfter); err != nil {
-				return err
-			}
-			if err := validateTimestamp("--published-before", publishedBefore); err != nil {
-				return err
-			}
-			client, err := a.authenticatedClient()
-			if err != nil {
-				return err
-			}
-			channelID, requests, err := client.ResolveChannel(cmd.Context(), args[0])
-			if err != nil {
-				return err
-			}
-			params := url.Values{"part": {partsOr(api.parts, "snippet,contentDetails")}, "channelId": {channelID}}
-			setValues(params, map[string]string{"publishedAfter": publishedAfter, "publishedBefore": publishedBefore, "fields": api.fields})
-			result, err := client.List(cmd.Context(), "activities", params, youtube.PageOptions{All: flags.all, Limit: flags.limit, PageSize: flags.pageSize, PageToken: flags.pageToken})
-			if err != nil {
-				return err
-			}
-			result.Requests += requests
-			return a.renderResult(result, []string{"id", "snippet.publishedAt", "snippet.type", "snippet.title"})
-		},
-	}
-	addListFlags(cmd, &flags, 25, 50)
-	addAPIFlags(cmd, &api, false)
-	cmd.Flags().StringVar(&publishedAfter, "published-after", "", "RFC 3339 lower publication bound")
-	cmd.Flags().StringVar(&publishedBefore, "published-before", "", "RFC 3339 upper publication bound")
-	return cmd
-}
-
-func (a *App) channelSectionsCommand() *cobra.Command {
-	var api apiFlags
-	var ids string
-	cmd := &cobra.Command{
-		Use:   "sections [CHANNEL]",
-		Short: "List a channel's sections or get section IDs",
-		Args:  maximumArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if (ids == "") == (len(args) == 0) {
-				return &UsageError{Message: "provide exactly one of CHANNEL or --id"}
-			}
-			client, err := a.authenticatedClient()
-			if err != nil {
-				return err
-			}
-			params := url.Values{"part": {partsOr(api.parts, "snippet,contentDetails")}}
-			requests := 0
-			if ids != "" {
-				params.Set("id", ids)
-			} else {
-				channelID, used, err := client.ResolveChannel(cmd.Context(), args[0])
-				if err != nil {
-					return err
-				}
-				requests += used
-				params.Set("channelId", channelID)
-			}
-			setValues(params, map[string]string{"hl": api.hl, "fields": api.fields})
-			response, err := client.Get(cmd.Context(), "channelSections", params)
-			if err != nil {
-				return err
-			}
-			return a.renderResult(youtube.ListResult{Items: response.Items, Requests: requests + 1}, []string{"id", "snippet.type", "snippet.position", "snippet.title"})
-		},
-	}
-	addAPIFlags(cmd, &api, true)
-	cmd.Flags().StringVar(&ids, "id", "", "comma-separated channel section IDs")
-	return cmd
-}
-
-func (a *App) channelUploadsCommand() *cobra.Command {
-	var flags listFlags
-	var api apiFlags
-	cmd := &cobra.Command{
-		Use:   "uploads ",
-		Short: "Resolve and enumerate a channel's uploads playlist",
-		Args:  exactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			client, err := a.authenticatedClient()
-			if err != nil {
-				return err
-			}
-			channelID, requests, err := client.ResolveChannel(cmd.Context(), args[0])
-			if err != nil {
-				return err
-			}
-			channelResponse, err := client.Get(cmd.Context(), "channels", url.Values{"part": {"contentDetails"}, "id": {channelID}})
-			if err != nil {
-				return err
-			}
-			requests++
-			if len(channelResponse.Items) == 0 {
-				return fmt.Errorf("channel %q not found", args[0])
-			}
-			uploads, ok := mapPathString(channelResponse.Items[0], "contentDetails", "relatedPlaylists", "uploads")
-			if !ok || uploads == "" {
-				return fmt.Errorf("channel %q has no public uploads playlist", args[0])
-			}
-			params := url.Values{"part": {partsOr(api.parts, "snippet,contentDetails")}, "playlistId": {uploads}}
-			setValues(params, map[string]string{"fields": api.fields})
-			result, err := client.List(cmd.Context(), "playlistItems", params, youtube.PageOptions{All: flags.all, Limit: flags.limit, PageSize: flags.pageSize, PageToken: flags.pageToken})
-			if err != nil {
-				return err
-			}
-			result.Requests += requests
-			return a.renderResult(result, []string{"snippet.position", "contentDetails.videoId", "snippet.title", "snippet.publishedAt"})
-		},
-	}
-	addListFlags(cmd, &flags, 50, 50)
-	addAPIFlags(cmd, &api, false)
-	return cmd
-}
-
-func (a *App) videoCommand() *cobra.Command {
-	video := &cobra.Command{Use: "video", Short: "Read videos, statistics, charts, and trainability"}
-	video.AddCommand(a.videoGetCommand(false), a.videoGetCommand(true), a.videoPopularCommand(), a.videoTrainabilityCommand())
-	return video
-}
-
-func (a *App) videoGetCommand(stats bool) *cobra.Command {
-	var api apiFlags
-	use, short, defaults := "get ...", "Get videos by ID", "snippet,contentDetails,statistics,status"
-	columns := []string{"id", "snippet.title", "snippet.channelTitle", "contentDetails.duration", "statistics.viewCount"}
-	if stats {
-		use, short, defaults = "stats ...", "Get video counters", "statistics"
-		columns = []string{"id", "statistics.viewCount", "statistics.likeCount", "statistics.commentCount"}
-	}
-	cmd := &cobra.Command{
-		Use: use, Short: short, Args: minimumArgs(1),
-		RunE: func(cmd *cobra.Command, ids []string) error {
-			parts := partsOr(api.parts, defaults)
-			if err := validateParts(parts, "fileDetails", "processingDetails", "suggestions"); err != nil {
-				return err
-			}
-			client, err := a.authenticatedClient()
-			if err != nil {
-				return err
-			}
-			result := youtube.ListResult{Items: make([]map[string]any, 0)}
-			requestFields, preserveID := fieldsWithRequired(api.fields, "items/id")
-			for _, group := range batch(ids, 50) {
-				params := url.Values{"part": {parts}, "id": {strings.Join(group, ",")}}
-				setValues(params, map[string]string{"hl": api.hl, "fields": requestFields})
-				response, err := client.Get(cmd.Context(), "videos", params)
-				if err != nil {
-					return err
-				}
-				result.Requests++
-				result.Items = append(result.Items, response.Items...)
-			}
-			if err := validateRequestedItems("videos", ids, result.Items); err != nil {
-				return err
-			}
-			stripItemIDs(result.Items, preserveID)
-			return a.renderResult(result, columns)
-		},
-	}
-	addAPIFlags(cmd, &api, true)
-	return cmd
-}
-
-func (a *App) videoPopularCommand() *cobra.Command {
-	var flags listFlags
-	var api apiFlags
-	var region, category string
-	cmd := &cobra.Command{
-		Use: "popular", Short: "List the most popular videos", Args: exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			parts := partsOr(api.parts, "snippet,contentDetails,statistics")
-			if err := validateParts(parts, "fileDetails", "processingDetails", "suggestions"); err != nil {
-				return err
-			}
-			params := url.Values{"part": {parts}, "chart": {"mostPopular"}}
-			setValues(params, map[string]string{"regionCode": region, "videoCategoryId": category, "hl": api.hl, "fields": api.fields})
-			return a.runList(cmd, "videos", params, flags, []string{"id", "snippet.title", "snippet.channelTitle", "statistics.viewCount"})
-		},
-	}
-	addListFlags(cmd, &flags, 25, 50)
-	addAPIFlags(cmd, &api, true)
-	cmd.Flags().StringVar(®ion, "region", "US", "ISO 3166-1 alpha-2 chart region")
-	cmd.Flags().StringVar(&category, "category", "", "video category ID")
-	return cmd
-}
-
-func (a *App) videoTrainabilityCommand() *cobra.Command {
-	cmd := &cobra.Command{
-		Use: "trainability ", Short: "Get third-party AI trainability (no key or quota required)", Args: exactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			client := a.client("")
-			var result map[string]any
-			if err := client.GetJSON(cmd.Context(), "videoTrainability", url.Values{"id": {args[0]}}, false, &result); err != nil {
-				return err
-			}
-			columns := a.columns
-			if len(columns) == 0 {
-				columns = []string{"videoId", "permitted"}
-			}
-			return output.RenderObject(a.Out, result, a.outputFormat(), columns, a.noHeader)
-		},
-	}
-	return cmd
-}
-
-func mapPathString(item map[string]any, path ...string) (string, bool) {
-	var value any = item
-	for _, key := range path {
-		object, ok := value.(map[string]any)
-		if !ok {
-			return "", false
-		}
-		value, ok = object[key]
-		if !ok {
-			return "", false
-		}
-	}
-	result, ok := value.(string)
-	return result, ok
-}
diff --git a/internal/cli/fields.go b/internal/cli/fields.go
deleted file mode 100644
index 438363c..0000000
--- a/internal/cli/fields.go
+++ /dev/null
@@ -1,79 +0,0 @@
-package cli
-
-import "strings"
-
-type fieldSelectorParser struct {
-	selector string
-	position int
-}
-
-func fieldSelectorIncludes(selector, target string) bool {
-	parser := fieldSelectorParser{selector: selector}
-	for _, path := range parser.parseList(nil, 0) {
-		wildcardParent := strings.TrimSuffix(path, "/*")
-		if path == "*" || path == "items" || path == target || strings.HasPrefix(path, target+"/") || strings.HasPrefix(target, path+"/") || wildcardParent != path && strings.HasPrefix(target, wildcardParent+"/") {
-			return true
-		}
-	}
-	return false
-}
-
-func (p *fieldSelectorParser) parseList(prefix []string, terminator byte) []string {
-	var paths []string
-	for p.position < len(p.selector) {
-		p.skipSpacesAndCommas()
-		if p.position >= len(p.selector) {
-			break
-		}
-		if terminator != 0 && p.selector[p.position] == terminator {
-			p.position++
-			break
-		}
-		paths = append(paths, p.parseField(prefix)...)
-	}
-	return paths
-}
-
-func (p *fieldSelectorParser) parseField(prefix []string) []string {
-	name := p.readName()
-	if name == "" {
-		p.position++
-		return nil
-	}
-	path := append(append([]string(nil), prefix...), name)
-	p.skipSpaces()
-	if p.position >= len(p.selector) {
-		return []string{strings.Join(path, "/")}
-	}
-	switch p.selector[p.position] {
-	case '/':
-		p.position++
-		p.skipSpaces()
-		return p.parseField(path)
-	case '(':
-		p.position++
-		return p.parseList(path, ')')
-	default:
-		return []string{strings.Join(path, "/")}
-	}
-}
-
-func (p *fieldSelectorParser) readName() string {
-	start := p.position
-	for p.position < len(p.selector) && !strings.ContainsRune("/(), \t\r\n", rune(p.selector[p.position])) {
-		p.position++
-	}
-	return p.selector[start:p.position]
-}
-
-func (p *fieldSelectorParser) skipSpacesAndCommas() {
-	for p.position < len(p.selector) && (p.selector[p.position] == ',' || strings.ContainsRune(" \t\r\n", rune(p.selector[p.position]))) {
-		p.position++
-	}
-}
-
-func (p *fieldSelectorParser) skipSpaces() {
-	for p.position < len(p.selector) && strings.ContainsRune(" \t\r\n", rune(p.selector[p.position])) {
-		p.position++
-	}
-}
diff --git a/internal/cli/fields_test.go b/internal/cli/fields_test.go
deleted file mode 100644
index 14a45c5..0000000
--- a/internal/cli/fields_test.go
+++ /dev/null
@@ -1,44 +0,0 @@
-package cli
-
-import "testing"
-
-func TestFieldSelectorIncludes(t *testing.T) {
-	tests := []struct {
-		selector string
-		want     bool
-	}{
-		{"", false},
-		{"items", true},
-		{"items/*", true},
-		{"items/id", true},
-		{"items(id/videoId,snippet/title),nextPageToken", true},
-		{"items(snippet/title),nextPageToken", false},
-		{"items/snippet/resourceId/channelId", false},
-	}
-	for _, test := range tests {
-		if got := fieldSelectorIncludes(test.selector, "items/id"); got != test.want {
-			t.Errorf("fieldSelectorIncludes(%q) = %v, want %v", test.selector, got, test.want)
-		}
-	}
-}
-
-func TestFieldSelectorIncludesNestedSearchKind(t *testing.T) {
-	tests := []struct {
-		selector string
-		want     bool
-	}{
-		{"items", true},
-		{"items/id", true},
-		{"items/id/*", true},
-		{"items/id/kind", true},
-		{"items(id/kind,snippet/title)", true},
-		{"items(id/*,snippet/title)", true},
-		{"items(id/channelId,snippet/title)", false},
-		{"items(id/videoId,snippet/title)", false},
-	}
-	for _, test := range tests {
-		if got := fieldSelectorIncludes(test.selector, "items/id/kind"); got != test.want {
-			t.Errorf("fieldSelectorIncludes(%q) = %v, want %v", test.selector, got, test.want)
-		}
-	}
-}
diff --git a/internal/cli/live_chat.go b/internal/cli/live_chat.go
deleted file mode 100644
index c0bda91..0000000
--- a/internal/cli/live_chat.go
+++ /dev/null
@@ -1,227 +0,0 @@
-package cli
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"net/url"
-	"strings"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"open-yt-cli/internal/output"
-	"open-yt-cli/internal/youtube"
-)
-
-func (a *App) liveChatCommand() *cobra.Command {
-	live := &cobra.Command{Use: "live-chat", Short: "Read public live chat using REST polling"}
-	live.AddCommand(a.liveChatListCommand(), a.liveChatStreamCommand())
-	return live
-}
-
-type liveChatFlags struct {
-	videoID     string
-	chatID      string
-	pageSize    int
-	pageToken   string
-	limit       int
-	profileSize int
-	parts       string
-	fields      string
-}
-
-func (a *App) liveChatListCommand() *cobra.Command {
-	var flags liveChatFlags
-	var all bool
-	cmd := &cobra.Command{
-		Use: "list", Short: "Fetch one finite page of live chat messages", Args: exactArgs(0),
-		Long: "Fetch one finite page of public live chat messages. Use stream for continuous, polling-aware output.",
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			if all {
-				return &UsageError{Message: "--all is not supported for live chat because its next token represents future polling; use 'live-chat stream'"}
-			}
-			client, chatID, requests, err := a.liveChatClientAndID(cmd, flags.videoID, flags.chatID)
-			if err != nil {
-				return err
-			}
-			response, err := client.Get(cmd.Context(), "liveChat/messages", liveChatParams(chatID, flags))
-			if err != nil {
-				return err
-			}
-			items := response.Items
-			if flags.limit > 0 && len(items) > flags.limit {
-				items = items[:flags.limit]
-			}
-			return a.renderResult(youtube.ListResult{Items: items, NextPageToken: response.NextPageToken, Requests: requests + 1}, liveChatColumns())
-		},
-	}
-	addLiveChatFlags(cmd, &flags)
-	cmd.Flags().BoolVar(&all, "all", false, "not supported for finite live chat; use stream")
-	return cmd
-}
-
-func (a *App) liveChatStreamCommand() *cobra.Command {
-	var flags liveChatFlags
-	cmd := &cobra.Command{
-		Use: "stream", Short: "Continuously poll live chat and emit deduplicated messages", Args: exactArgs(0),
-		Long: "Continuously polls liveChatMessages.list, respects pollingIntervalMillis, carries page tokens, and deduplicates IDs. This first draft is a REST polling fallback, not the official gRPC streamList method. JSONL is the default stream format.",
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			format := a.outputFormat()
-			if a.format == "" {
-				format = "jsonl"
-			}
-			if format == "json" {
-				return &UsageError{Message: "--format json is not valid for an unbounded stream; use jsonl, tsv, or table"}
-			}
-			client, chatID, requests, err := a.liveChatClientAndID(cmd, flags.videoID, flags.chatID)
-			if err != nil {
-				return err
-			}
-			seen := make(map[string]struct{})
-			emitted := 0
-			firstPage := true
-			for {
-				response, err := client.Get(cmd.Context(), "liveChat/messages", liveChatParams(chatID, flags))
-				if err != nil {
-					if errors.Is(err, context.Canceled) || apiErrorHasReason(err, "liveChatEnded") {
-						return nil
-					}
-					return err
-				}
-				requests++
-				items := make([]map[string]any, 0, len(response.Items))
-				for _, item := range response.Items {
-					id, _ := item["id"].(string)
-					if id != "" {
-						if _, exists := seen[id]; exists {
-							continue
-						}
-						seen[id] = struct{}{}
-					}
-					items = append(items, item)
-					if flags.limit > 0 && emitted+len(items) >= flags.limit {
-						break
-					}
-				}
-				if len(items) > 0 {
-					columns := a.columns
-					if len(columns) == 0 {
-						columns = liveChatColumns()
-					}
-					if err := output.Render(a.Out, youtube.ListResult{Items: items, Requests: requests}, output.Options{Format: format, Columns: columns, NoHeader: a.noHeader || !firstPage}); err != nil {
-						return err
-					}
-					emitted += len(items)
-					firstPage = false
-				}
-				if flags.limit > 0 && emitted >= flags.limit {
-					return nil
-				}
-				if response.OfflineAt != "" || response.NextPageToken == "" {
-					return nil
-				}
-				flags.pageToken = response.NextPageToken
-				interval := time.Duration(response.PollingIntervalMillis) * time.Millisecond
-				if interval <= 0 {
-					interval = time.Second
-				}
-				if err := waitFor(cmd.Context(), interval); err != nil {
-					if errors.Is(err, context.Canceled) {
-						return nil
-					}
-					return err
-				}
-			}
-		},
-	}
-	addLiveChatFlags(cmd, &flags)
-	return cmd
-}
-
-func addLiveChatFlags(cmd *cobra.Command, flags *liveChatFlags) {
-	cmd.Flags().StringVar(&flags.videoID, "video", "", "live video ID (resolved to activeLiveChatId)")
-	cmd.Flags().StringVar(&flags.chatID, "chat-id", "", "live chat ID")
-	cmd.Flags().IntVar(&flags.pageSize, "page-size", 500, "messages per request (200-2000)")
-	cmd.Flags().StringVar(&flags.pageToken, "page-token", "", "resume at this live chat page token")
-	cmd.Flags().IntVar(&flags.limit, "limit", 0, "stop after this many emitted messages (0 means unlimited)")
-	cmd.Flags().IntVar(&flags.profileSize, "profile-image-size", 88, "author image size in pixels (16-720)")
-	cmd.Flags().StringVar(&flags.parts, "parts", "snippet,authorDetails", "comma-separated API resource parts")
-	cmd.Flags().StringVar(&flags.fields, "fields", "", "Google partial-response fields selector")
-	cmd.PreRunE = func(_ *cobra.Command, _ []string) error {
-		if (flags.videoID == "") == (flags.chatID == "") {
-			return &UsageError{Message: "provide exactly one of --video or --chat-id"}
-		}
-		if flags.pageSize < 200 || flags.pageSize > 2000 {
-			return &UsageError{Message: "--page-size must be between 200 and 2000"}
-		}
-		if flags.profileSize < 16 || flags.profileSize > 720 {
-			return &UsageError{Message: "--profile-image-size must be between 16 and 720"}
-		}
-		if flags.limit < 0 {
-			return &UsageError{Message: "--limit cannot be negative"}
-		}
-		return nil
-	}
-}
-
-func (a *App) liveChatClientAndID(cmd *cobra.Command, videoID, chatID string) (*youtube.Client, string, int, error) {
-	client, err := a.authenticatedClient()
-	if err != nil {
-		return nil, "", 0, err
-	}
-	if chatID != "" {
-		return client, chatID, 0, nil
-	}
-	response, err := client.Get(cmd.Context(), "videos", url.Values{"part": {"liveStreamingDetails"}, "id": {videoID}})
-	if err != nil {
-		return nil, "", 1, err
-	}
-	if len(response.Items) == 0 {
-		return nil, "", 1, fmt.Errorf("video %q not found", videoID)
-	}
-	resolved, ok := mapPathString(response.Items[0], "liveStreamingDetails", "activeLiveChatId")
-	if !ok || strings.TrimSpace(resolved) == "" {
-		return nil, "", 1, fmt.Errorf("video %q has no active public live chat", videoID)
-	}
-	return client, resolved, 1, nil
-}
-
-func liveChatParams(chatID string, flags liveChatFlags) url.Values {
-	params := url.Values{
-		"part":             {flags.parts},
-		"liveChatId":       {chatID},
-		"maxResults":       {fmt.Sprint(flags.pageSize)},
-		"profileImageSize": {fmt.Sprint(flags.profileSize)},
-	}
-	setValues(params, map[string]string{"pageToken": flags.pageToken, "fields": flags.fields})
-	return params
-}
-
-func liveChatColumns() []string {
-	return []string{"snippet.publishedAt", "authorDetails.displayName", "snippet.displayMessage", "snippet.type", "id"}
-}
-
-func apiErrorHasReason(err error, wanted string) bool {
-	var apiErr *youtube.APIError
-	if !errors.As(err, &apiErr) {
-		return false
-	}
-	for _, reason := range apiErr.Reasons {
-		if reason == wanted {
-			return true
-		}
-	}
-	return false
-}
-
-func waitFor(ctx context.Context, duration time.Duration) error {
-	timer := time.NewTimer(duration)
-	defer timer.Stop()
-	select {
-	case <-ctx.Done():
-		return ctx.Err()
-	case <-timer.C:
-		return nil
-	}
-}
diff --git a/internal/cli/resources.go b/internal/cli/resources.go
deleted file mode 100644
index 815f34d..0000000
--- a/internal/cli/resources.go
+++ /dev/null
@@ -1,289 +0,0 @@
-package cli
-
-import (
-	"net/url"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	"open-yt-cli/internal/youtube"
-)
-
-func (a *App) playlistCommand() *cobra.Command {
-	playlist := &cobra.Command{Use: "playlist", Short: "Read playlists and playlist items"}
-	playlist.AddCommand(a.playlistGetCommand(), a.playlistListCommand(), a.playlistItemsCommand())
-	return playlist
-}
-
-func (a *App) playlistGetCommand() *cobra.Command {
-	var api apiFlags
-	cmd := &cobra.Command{
-		Use: "get ...", Short: "Get playlists by ID", Args: minimumArgs(1),
-		RunE: func(cmd *cobra.Command, ids []string) error {
-			client, err := a.authenticatedClient()
-			if err != nil {
-				return err
-			}
-			result := youtube.ListResult{Items: make([]map[string]any, 0)}
-			requestFields, preserveID := fieldsWithRequired(api.fields, "items/id")
-			for _, group := range batch(ids, 50) {
-				params := url.Values{"part": {partsOr(api.parts, "snippet,contentDetails,status")}, "id": {strings.Join(group, ",")}}
-				setValues(params, map[string]string{"hl": api.hl, "fields": requestFields})
-				response, err := client.Get(cmd.Context(), "playlists", params)
-				if err != nil {
-					return err
-				}
-				result.Items = append(result.Items, response.Items...)
-				result.Requests++
-			}
-			if err := validateRequestedItems("playlists", ids, result.Items); err != nil {
-				return err
-			}
-			stripItemIDs(result.Items, preserveID)
-			return a.renderResult(result, []string{"id", "snippet.title", "snippet.channelTitle", "contentDetails.itemCount", "status.privacyStatus"})
-		},
-	}
-	addAPIFlags(cmd, &api, true)
-	return cmd
-}
-
-func (a *App) playlistListCommand() *cobra.Command {
-	var flags listFlags
-	var api apiFlags
-	var channelID string
-	cmd := &cobra.Command{
-		Use: "list", Short: "List a channel's public playlists", Args: exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			if channelID == "" {
-				return &UsageError{Message: "--channel is required"}
-			}
-			params := url.Values{"part": {partsOr(api.parts, "snippet,contentDetails,status")}, "channelId": {channelID}}
-			setValues(params, map[string]string{"hl": api.hl, "fields": api.fields})
-			return a.runList(cmd, "playlists", params, flags, []string{"id", "snippet.title", "contentDetails.itemCount", "status.privacyStatus"})
-		},
-	}
-	addListFlags(cmd, &flags, 25, 50)
-	addAPIFlags(cmd, &api, true)
-	cmd.Flags().StringVar(&channelID, "channel", "", "channel ID (required)")
-	return cmd
-}
-
-func (a *App) playlistItemsCommand() *cobra.Command {
-	var flags listFlags
-	var api apiFlags
-	var videoID string
-	cmd := &cobra.Command{
-		Use: "items ", Short: "List items in a playlist", Args: exactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			params := url.Values{"part": {partsOr(api.parts, "snippet,contentDetails,status")}, "playlistId": {args[0]}}
-			setValues(params, map[string]string{"videoId": videoID, "fields": api.fields})
-			return a.runList(cmd, "playlistItems", params, flags, []string{"snippet.position", "contentDetails.videoId", "snippet.title", "snippet.videoOwnerChannelTitle"})
-		},
-	}
-	addListFlags(cmd, &flags, 50, 50)
-	addAPIFlags(cmd, &api, false)
-	cmd.Flags().StringVar(&videoID, "video", "", "only items for this video ID")
-	return cmd
-}
-
-func (a *App) commentCommand() *cobra.Command {
-	comment := &cobra.Command{Use: "comment", Short: "Read public comments and comment threads"}
-	comment.AddCommand(a.commentGetCommand(), a.commentRepliesCommand(), a.commentThreadsCommand())
-	return comment
-}
-
-func (a *App) commentGetCommand() *cobra.Command {
-	var api apiFlags
-	var textFormat string
-	cmd := &cobra.Command{
-		Use: "get ...", Short: "Get comments by ID", Args: minimumArgs(1),
-		RunE: func(cmd *cobra.Command, ids []string) error {
-			if err := validateEnum("--text-format", textFormat, "plainText", "html"); err != nil {
-				return err
-			}
-			client, err := a.authenticatedClient()
-			if err != nil {
-				return err
-			}
-			result := youtube.ListResult{Items: make([]map[string]any, 0)}
-			requestFields, preserveID := fieldsWithRequired(api.fields, "items/id")
-			for _, group := range batch(ids, 100) {
-				params := url.Values{"part": {partsOr(api.parts, "snippet")}, "id": {strings.Join(group, ",")}}
-				setValues(params, map[string]string{"textFormat": textFormat, "fields": requestFields})
-				response, err := client.Get(cmd.Context(), "comments", params)
-				if err != nil {
-					return err
-				}
-				result.Items = append(result.Items, response.Items...)
-				result.Requests++
-			}
-			if err := validateRequestedItems("comments", ids, result.Items); err != nil {
-				return err
-			}
-			stripItemIDs(result.Items, preserveID)
-			return a.renderResult(result, commentColumns())
-		},
-	}
-	addAPIFlags(cmd, &api, false)
-	cmd.Flags().StringVar(&textFormat, "text-format", "plainText", "plainText or html")
-	return cmd
-}
-
-func (a *App) commentRepliesCommand() *cobra.Command {
-	var flags listFlags
-	var api apiFlags
-	var textFormat string
-	cmd := &cobra.Command{
-		Use: "replies ", Short: "List replies to a top-level comment", Args: exactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateEnum("--text-format", textFormat, "plainText", "html"); err != nil {
-				return err
-			}
-			params := url.Values{"part": {partsOr(api.parts, "snippet")}, "parentId": {args[0]}}
-			setValues(params, map[string]string{"textFormat": textFormat, "fields": api.fields})
-			return a.runList(cmd, "comments", params, flags, commentColumns())
-		},
-	}
-	addListFlags(cmd, &flags, 20, 100)
-	addAPIFlags(cmd, &api, false)
-	cmd.Flags().StringVar(&textFormat, "text-format", "plainText", "plainText or html")
-	return cmd
-}
-
-func (a *App) commentThreadsCommand() *cobra.Command {
-	var flags listFlags
-	var api apiFlags
-	var videoID, channelID, ids, order, searchTerms, textFormat string
-	cmd := &cobra.Command{
-		Use: "threads", Short: "List comment threads by video, channel, or IDs", Args: exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			if err := validateEnum("--text-format", textFormat, "plainText", "html"); err != nil {
-				return err
-			}
-			if err := validateEnum("--order", order, "time", "relevance"); err != nil {
-				return err
-			}
-			filters := 0
-			for _, value := range []string{videoID, channelID, ids} {
-				if value != "" {
-					filters++
-				}
-			}
-			if filters != 1 {
-				return &UsageError{Message: "provide exactly one of --video, --channel, or --id"}
-			}
-			if ids != "" && (order != "time" || searchTerms != "") {
-				return &UsageError{Message: "--order and --search are incompatible with --id"}
-			}
-			params := url.Values{"part": {partsOr(api.parts, "snippet,replies")}}
-			setValues(params, map[string]string{"videoId": videoID, "allThreadsRelatedToChannelId": channelID, "id": ids, "order": order, "searchTerms": searchTerms, "textFormat": textFormat, "fields": api.fields})
-			return a.runList(cmd, "commentThreads", params, flags, []string{"id", "snippet.topLevelComment.snippet.authorDisplayName", "snippet.topLevelComment.snippet.textDisplay", "snippet.totalReplyCount"})
-		},
-	}
-	addListFlags(cmd, &flags, 20, 100)
-	addAPIFlags(cmd, &api, false)
-	cmd.Flags().StringVar(&videoID, "video", "", "video ID")
-	cmd.Flags().StringVar(&channelID, "channel", "", "channel ID")
-	cmd.Flags().StringVar(&ids, "id", "", "comma-separated thread IDs")
-	cmd.Flags().StringVar(&order, "order", "time", "time or relevance")
-	cmd.Flags().StringVar(&searchTerms, "search", "", "restrict to comments containing these terms")
-	cmd.Flags().StringVar(&textFormat, "text-format", "plainText", "plainText or html")
-	return cmd
-}
-
-func commentColumns() []string {
-	return []string{"id", "snippet.authorDisplayName", "snippet.textDisplay", "snippet.likeCount", "snippet.publishedAt"}
-}
-
-func (a *App) subscriptionCommand() *cobra.Command {
-	subscription := &cobra.Command{Use: "subscription", Short: "Read public channel subscriptions"}
-	subscription.AddCommand(a.subscriptionListCommand())
-	return subscription
-}
-
-func (a *App) subscriptionListCommand() *cobra.Command {
-	var flags listFlags
-	var api apiFlags
-	var channelID, ids, order, forChannel string
-	cmd := &cobra.Command{
-		Use: "list", Short: "List subscriptions by channel or subscription IDs", Args: exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			if err := validateParts(partsOr(api.parts, "snippet,contentDetails"), "subscriberSnippet"); err != nil {
-				return err
-			}
-			if err := validateEnum("--order", order, "alphabetical", "relevance"); err != nil {
-				return err
-			}
-			if (channelID == "") == (ids == "") {
-				return &UsageError{Message: "provide exactly one of --channel or --id"}
-			}
-			if ids != "" && (forChannel != "" || order != "relevance") {
-				return &UsageError{Message: "--for-channel and --order are incompatible with --id"}
-			}
-			params := url.Values{"part": {partsOr(api.parts, "snippet,contentDetails")}}
-			setValues(params, map[string]string{"channelId": channelID, "id": ids, "order": order, "forChannelId": forChannel, "fields": api.fields})
-			return a.runList(cmd, "subscriptions", params, flags, []string{"id", "snippet.resourceId.channelId", "snippet.title", "contentDetails.totalItemCount"})
-		},
-	}
-	addListFlags(cmd, &flags, 25, 50)
-	addAPIFlags(cmd, &api, false)
-	cmd.Flags().StringVar(&channelID, "channel", "", "subscriber channel ID")
-	cmd.Flags().StringVar(&ids, "id", "", "comma-separated subscription IDs")
-	cmd.Flags().StringVar(&order, "order", "relevance", "alphabetical or relevance")
-	cmd.Flags().StringVar(&forChannel, "for-channel", "", "only subscriptions to this channel ID")
-	return cmd
-}
-
-func (a *App) categoryCommand() *cobra.Command {
-	category := &cobra.Command{Use: "category", Short: "Read YouTube video categories"}
-	var api apiFlags
-	var region, ids string
-	list := &cobra.Command{
-		Use: "list", Short: "List categories by region or IDs", Args: exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			if (region == "") == (ids == "") {
-				return &UsageError{Message: "provide exactly one of --region or --id"}
-			}
-			params := url.Values{"part": {partsOr(api.parts, "snippet")}}
-			setValues(params, map[string]string{"regionCode": region, "id": ids, "hl": api.hl, "fields": api.fields})
-			return a.runList(cmd, "videoCategories", params, listFlags{}, []string{"id", "snippet.title", "snippet.assignable"})
-		},
-	}
-	addAPIFlags(list, &api, true)
-	list.Flags().StringVar(®ion, "region", "", "ISO 3166-1 alpha-2 region code")
-	list.Flags().StringVar(&ids, "id", "", "comma-separated category IDs")
-	category.AddCommand(list)
-	return category
-}
-
-func (a *App) languageCommand() *cobra.Command {
-	language := &cobra.Command{Use: "language", Short: "Read supported YouTube UI languages"}
-	var api apiFlags
-	list := &cobra.Command{
-		Use: "list", Short: "List supported YouTube UI languages", Args: exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			params := url.Values{"part": {partsOr(api.parts, "snippet")}}
-			setValues(params, map[string]string{"hl": api.hl, "fields": api.fields})
-			return a.runList(cmd, "i18nLanguages", params, listFlags{}, []string{"id", "snippet.name"})
-		},
-	}
-	addAPIFlags(list, &api, true)
-	language.AddCommand(list)
-	return language
-}
-
-func (a *App) regionCommand() *cobra.Command {
-	region := &cobra.Command{Use: "region", Short: "Read supported YouTube regions"}
-	var api apiFlags
-	list := &cobra.Command{
-		Use: "list", Short: "List supported YouTube regions", Args: exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			params := url.Values{"part": {partsOr(api.parts, "snippet")}}
-			setValues(params, map[string]string{"hl": api.hl, "fields": api.fields})
-			return a.runList(cmd, "i18nRegions", params, listFlags{}, []string{"id", "snippet.name", "snippet.glName"})
-		},
-	}
-	addAPIFlags(list, &api, true)
-	region.AddCommand(list)
-	return region
-}
diff --git a/internal/cli/skills.go b/internal/cli/skills.go
deleted file mode 100644
index cf91954..0000000
--- a/internal/cli/skills.go
+++ /dev/null
@@ -1,65 +0,0 @@
-package cli
-
-import (
-	"bufio"
-	"fmt"
-	"os"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	"open-yt-cli/internal/skill"
-)
-
-func (a *App) skillsCommand() *cobra.Command {
-	command := &cobra.Command{
-		Use:     "skills",
-		Aliases: []string{"skill"},
-		Short:   "Install the bundled oytc agent skill",
-	}
-	command.AddCommand(a.skillsInstallCommand())
-	return command
-}
-
-func (a *App) skillsInstallCommand() *cobra.Command {
-	return &cobra.Command{
-		Use:   "install",
-		Short: "Install or update the skill in ~/.agents/skills/oytc",
-		Args:  exactArgs(0),
-		RunE: func(_ *cobra.Command, _ []string) error {
-			target := a.SkillInstallPath
-			if target == "" {
-				var err error
-				target, err = skill.DefaultPath()
-				if err != nil {
-					return err
-				}
-			}
-
-			action := "create"
-			if _, err := os.Lstat(target); err == nil {
-				action = "replace"
-			} else if !os.IsNotExist(err) {
-				return fmt.Errorf("inspect skill destination: %w", err)
-			}
-			fmt.Fprintf(a.Err, "Install the bundled oytc agent skill?\nDestination: %s\nPermission requested: %s this directory and write SKILL.md plus references.\nContinue? [y/N] ", target, action)
-			answer, err := bufio.NewReader(a.In).ReadString('\n')
-			if err != nil && len(answer) == 0 {
-				return fmt.Errorf("read confirmation: %w", err)
-			}
-			fmt.Fprintln(a.Err)
-			switch strings.ToLower(strings.TrimSpace(answer)) {
-			case "y", "yes":
-			default:
-				fmt.Fprintln(a.Out, "Skill installation cancelled; no files were changed.")
-				return nil
-			}
-
-			if err := skill.Install(target); err != nil {
-				return err
-			}
-			fmt.Fprintf(a.Out, "Installed oytc agent skill to %s\n", target)
-			return nil
-		},
-	}
-}
diff --git a/internal/cli/skills_test.go b/internal/cli/skills_test.go
deleted file mode 100644
index 2608855..0000000
--- a/internal/cli/skills_test.go
+++ /dev/null
@@ -1,55 +0,0 @@
-package cli
-
-import (
-	"bytes"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-)
-
-func TestSkillsInstallRequiresConfirmationAndWritesBundle(t *testing.T) {
-	app, out, errOut := testApp(nil)
-	target := filepath.Join(t.TempDir(), ".agents", "skills", "oytc")
-	app.SkillInstallPath = target
-	app.In = strings.NewReader("yes\n")
-
-	if err := execute(t, app, "skills", "install"); err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(errOut.String(), target) || !strings.Contains(errOut.String(), "Permission requested") {
-		t.Fatalf("confirmation did not show path and permission: %s", errOut.String())
-	}
-	content, err := os.ReadFile(filepath.Join(target, "SKILL.md"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !bytes.Contains(content, []byte("Query public YouTube data")) {
-		t.Fatalf("installed unexpected skill: %s", content)
-	}
-	for _, name := range []string{"references/commands.md", "references/recipes.md"} {
-		if _, err := os.Stat(filepath.Join(target, filepath.FromSlash(name))); err != nil {
-			t.Fatalf("missing %s: %v", name, err)
-		}
-	}
-	if !strings.Contains(out.String(), "Installed oytc agent skill") {
-		t.Fatalf("missing success output: %s", out.String())
-	}
-}
-
-func TestSkillsInstallDeclineMakesNoChanges(t *testing.T) {
-	app, out, _ := testApp(nil)
-	target := filepath.Join(t.TempDir(), ".agents", "skills", "oytc")
-	app.SkillInstallPath = target
-	app.In = strings.NewReader("no\n")
-
-	if err := execute(t, app, "skill", "install"); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := os.Stat(target); !os.IsNotExist(err) {
-		t.Fatalf("declined install changed target: %v", err)
-	}
-	if !strings.Contains(out.String(), "cancelled") {
-		t.Fatalf("missing cancellation output: %s", out.String())
-	}
-}
diff --git a/internal/cli/version_update.go b/internal/cli/version_update.go
deleted file mode 100644
index 8317ab7..0000000
--- a/internal/cli/version_update.go
+++ /dev/null
@@ -1,97 +0,0 @@
-package cli
-
-import (
-	"fmt"
-
-	"github.com/spf13/cobra"
-
-	"open-yt-cli/internal/output"
-	"open-yt-cli/internal/update"
-	"open-yt-cli/internal/version"
-)
-
-func (a *App) versionCommand() *cobra.Command {
-	return &cobra.Command{
-		Use:   "version",
-		Short: "Show version, commit, and build date",
-		Args:  exactArgs(0),
-		RunE: func(_ *cobra.Command, _ []string) error {
-			info := version.Get()
-			if a.outputFormat() != "table" {
-				state := map[string]any{
-					"version":   info.Version,
-					"commit":    info.Commit,
-					"date":      info.Date,
-					"goVersion": info.GoVersion,
-					"os":        info.OS,
-					"arch":      info.Arch,
-				}
-				columns := a.columns
-				if len(columns) == 0 {
-					columns = []string{"version", "commit", "date", "goVersion", "os", "arch"}
-				}
-				return output.RenderObject(a.Out, state, a.outputFormat(), columns, a.noHeader)
-			}
-			fmt.Fprintf(a.Out, "oytc %s\ncommit: %s\nbuilt: %s\ngo: %s (%s/%s)\n", info.Version, info.Commit, info.Date, info.GoVersion, info.OS, info.Arch)
-			return nil
-		},
-	}
-}
-
-func (a *App) updateCommand() *cobra.Command {
-	var check bool
-	var targetVersion string
-	cmd := &cobra.Command{
-		Use:     "update",
-		Aliases: []string{"upgrade"},
-		Short:   "Self-update oytc from GitHub Releases (checksum-verified)",
-		Long: "Downloads the matching release archive and checksums.txt from GitHub Releases,\n" +
-			"verifies the archive's SHA-256, and atomically replaces the current executable.\n" +
-			"The updater never reads or transmits the YouTube API key.\n\n" +
-			"'oytc upgrade' is an alias, and the installer also provides oytc_update and\n" +
-			"oytc_upgrade shims that run the same operation.",
-		Args: exactArgs(0),
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			updater := a.newUpdater()
-			result, err := updater.Run(cmd.Context(), update.Options{TargetVersion: targetVersion, CheckOnly: check})
-			if err != nil {
-				return err
-			}
-			if a.outputFormat() != "table" {
-				state := map[string]any{
-					"currentVersion": result.CurrentVersion,
-					"targetVersion":  result.TargetVersion,
-					"updated":        result.Updated,
-					"upToDate":       result.UpToDate,
-					"asset":          result.AssetName,
-					"executable":     result.ExecutablePath,
-				}
-				columns := a.columns
-				if len(columns) == 0 {
-					columns = []string{"currentVersion", "targetVersion", "updated", "upToDate", "asset", "executable"}
-				}
-				return output.RenderObject(a.Out, state, a.outputFormat(), columns, a.noHeader)
-			}
-			switch {
-			case result.UpToDate:
-				fmt.Fprintf(a.Out, "oytc %s is already the latest release.\n", result.CurrentVersion)
-			case result.Updated:
-				fmt.Fprintf(a.Out, "Updated %s -> %s (%s)\n", result.CurrentVersion, result.TargetVersion, result.ExecutablePath)
-			default:
-				fmt.Fprintf(a.Out, "Update available: %s (current: %s)\nRun 'oytc update' to install it.\n", result.TargetVersion, result.CurrentVersion)
-			}
-			return nil
-		},
-	}
-	cmd.Flags().BoolVar(&check, "check", false, "only report whether a newer release exists")
-	cmd.Flags().StringVar(&targetVersion, "version", "", "install this exact release tag (e.g. v0.2.0) instead of the latest")
-	return cmd
-}
-
-func (a *App) newUpdater() *update.Updater {
-	updater := &update.Updater{CurrentVersion: version.Get().Version}
-	if a.UpdaterFactory != nil {
-		return a.UpdaterFactory(updater)
-	}
-	return updater
-}
diff --git a/internal/cli/version_update_test.go b/internal/cli/version_update_test.go
deleted file mode 100644
index 090e986..0000000
--- a/internal/cli/version_update_test.go
+++ /dev/null
@@ -1,129 +0,0 @@
-package cli
-
-import (
-	"archive/tar"
-	"bytes"
-	"compress/gzip"
-	"crypto/sha256"
-	"encoding/hex"
-	"encoding/json"
-	"fmt"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"path/filepath"
-	"runtime"
-	"testing"
-
-	"open-yt-cli/internal/update"
-	"open-yt-cli/internal/version"
-)
-
-func TestVersionCommandJSON(t *testing.T) {
-	oldVersion := version.Version
-	t.Cleanup(func() { version.Version = oldVersion })
-	version.Version = "v1.2.3"
-
-	app := New()
-	out := &bytes.Buffer{}
-	app.Out = out
-	app.IsOutputTTY = false
-	if err := execute(t, app, "version", "--format", "json"); err != nil {
-		t.Fatal(err)
-	}
-	var state map[string]any
-	if err := json.Unmarshal(out.Bytes(), &state); err != nil {
-		t.Fatal(err)
-	}
-	if state["version"] != "v1.2.3" || state["os"] != runtime.GOOS {
-		t.Fatalf("version output: %s", out.String())
-	}
-}
-
-func TestVersionFlag(t *testing.T) {
-	oldVersion := version.Version
-	t.Cleanup(func() { version.Version = oldVersion })
-	version.Version = "v1.2.3"
-
-	for _, flag := range []string{"-v", "--version"} {
-		t.Run(flag, func(t *testing.T) {
-			app := New()
-			var out bytes.Buffer
-			app.Out = &out
-			if err := execute(t, app, flag); err != nil {
-				t.Fatal(err)
-			}
-			if got := out.String(); got != "oytc v1.2.3\n" {
-				t.Fatalf("output = %q", got)
-			}
-		})
-	}
-}
-
-func TestUpdateCommandRunsThroughInjectedUpdater(t *testing.T) {
-	oldVersion := version.Version
-	t.Cleanup(func() { version.Version = oldVersion })
-	version.Version = "v0.1.0"
-
-	binary := []byte("released-binary")
-	var archive bytes.Buffer
-	gz := gzip.NewWriter(&archive)
-	tw := tar.NewWriter(gz)
-	if err := tw.WriteHeader(&tar.Header{Name: "oytc", Mode: 0o755, Size: int64(len(binary)), Typeflag: tar.TypeReg}); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := tw.Write(binary); err != nil {
-		t.Fatal(err)
-	}
-	_ = tw.Close()
-	_ = gz.Close()
-
-	asset := update.AssetName("v0.2.0", "linux", "amd64")
-	sum := sha256.Sum256(archive.Bytes())
-	checksums := fmt.Sprintf("%s  %s\n", hex.EncodeToString(sum[:]), asset)
-
-	var server *httptest.Server
-	mux := http.NewServeMux()
-	mux.HandleFunc("/repos/owner/repo/releases/latest", func(w http.ResponseWriter, _ *http.Request) {
-		fmt.Fprintf(w, `{"tag_name":"v0.2.0","assets":[{"name":%q,"browser_download_url":%q},{"name":"checksums.txt","browser_download_url":%q}]}`,
-			asset, server.URL+"/a", server.URL+"/c")
-	})
-	mux.HandleFunc("/a", func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write(archive.Bytes()) })
-	mux.HandleFunc("/c", func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write([]byte(checksums)) })
-	server = httptest.NewServer(mux)
-	defer server.Close()
-
-	executable := filepath.Join(t.TempDir(), "oytc")
-	if err := os.WriteFile(executable, []byte("old"), 0o755); err != nil {
-		t.Fatal(err)
-	}
-
-	app := New()
-	out := &bytes.Buffer{}
-	app.Out = out
-	app.IsOutputTTY = false
-	app.UpdaterFactory = func(u *update.Updater) *update.Updater {
-		u.Repo = "owner/repo"
-		u.APIBaseURL = server.URL
-		u.HTTPClient = server.Client()
-		u.GOOS = "linux"
-		u.GOARCH = "amd64"
-		u.ExecutablePath = executable
-		return u
-	}
-	if err := execute(t, app, "update", "--format", "json"); err != nil {
-		t.Fatal(err)
-	}
-	installed, err := os.ReadFile(executable)
-	if err != nil || !bytes.Equal(installed, binary) {
-		t.Fatalf("installed = %q, err = %v", installed, err)
-	}
-	if !bytes.Contains(out.Bytes(), []byte(`"updated": true`)) {
-		t.Fatalf("output: %s", out.String())
-	}
-
-	// The upgrade alias resolves to the same command.
-	if err := execute(t, app, "upgrade", "--check", "--format", "json"); err != nil {
-		t.Fatal(err)
-	}
-}
diff --git a/internal/config/config.go b/internal/config/config.go
deleted file mode 100644
index 04aea84..0000000
--- a/internal/config/config.go
+++ /dev/null
@@ -1,356 +0,0 @@
-// Package config manages oytc's API-key and OAuth configuration.
-package config
-
-import (
-	"crypto/sha256"
-	"encoding/hex"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"os"
-	"path/filepath"
-	"runtime"
-	"strings"
-)
-
-const (
-	envKey               = "OYTC_API_KEY"
-	envOAuthClientID     = "OYTC_OAUTH_CLIENT_ID"
-	envOAuthClientSecret = "OYTC_OAUTH_CLIENT_SECRET"
-)
-
-type File struct {
-	APIKey string            `json:"api_key,omitempty"`
-	OAuth  *OAuthCredentials `json:"oauth,omitempty"`
-}
-
-type OAuthCredentials struct {
-	ClientID     string   `json:"client_id"`
-	ClientSecret string   `json:"client_secret"`
-	AccessToken  string   `json:"access_token"`
-	RefreshToken string   `json:"refresh_token"`
-	Expiry       string   `json:"expiry"`
-	Scopes       []string `json:"scopes"`
-}
-
-type Credentials struct {
-	Key    string
-	Source string
-	OAuth  *OAuthCredentials
-	Path   string
-}
-
-func Dir() (string, error) {
-	if dir := strings.TrimSpace(os.Getenv("OYTC_CONFIG_DIR")); dir != "" {
-		return expandHome(dir), nil
-	}
-	var dir string
-	var err error
-	switch runtime.GOOS {
-	case "darwin":
-		dir, err = os.UserHomeDir()
-		if err == nil {
-			dir = filepath.Join(dir, "Library", "Application Support", "oytc")
-		}
-	case "windows":
-		dir = os.Getenv("APPDATA")
-		if dir == "" {
-			err = errors.New("APPDATA is not set")
-		} else {
-			dir = filepath.Join(dir, "oytc")
-		}
-	default:
-		dir = os.Getenv("XDG_CONFIG_HOME")
-		if dir == "" {
-			dir, err = os.UserHomeDir()
-			if err == nil {
-				dir = filepath.Join(dir, ".config")
-			}
-		}
-		dir = filepath.Join(dir, "oytc")
-	}
-	if err != nil {
-		return "", fmt.Errorf("determine config directory: %w", err)
-	}
-	return dir, nil
-}
-
-func Path() (string, error) {
-	dir, err := Dir()
-	if err != nil {
-		return "", err
-	}
-	return filepath.Join(dir, "auth.json"), nil
-}
-
-func Load() (Credentials, error) {
-	path, err := Path()
-	if err != nil {
-		return Credentials{}, err
-	}
-	file, exists, err := loadFile(path)
-	if err != nil {
-		// A corrupt or unreadable auth.json must not block the
-		// higher-precedence environment key.
-		if key := strings.TrimSpace(os.Getenv(envKey)); key != "" {
-			return Credentials{Key: key, Source: envKey, Path: path}, nil
-		}
-		return Credentials{Path: path}, err
-	}
-	credentials := Credentials{Path: path}
-	if exists {
-		credentials.Key = strings.TrimSpace(file.APIKey)
-		credentials.OAuth = cloneOAuth(file.OAuth)
-		if credentials.Key != "" {
-			credentials.Source = "auth.json"
-		}
-	}
-	if key := strings.TrimSpace(os.Getenv(envKey)); key != "" {
-		credentials.Key = key
-		credentials.Source = envKey
-	}
-	return credentials, nil
-}
-
-// OAuthBootstrap returns environment credentials used only to bootstrap `login --oauth`.
-// Each variable independently avoids its corresponding prompt, analogous to OYTC_API_KEY's
-// environment-first behavior. Authorized tokens are still loaded from auth.json.
-func OAuthBootstrap() (clientID, clientSecret string) {
-	return strings.TrimSpace(os.Getenv(envOAuthClientID)), strings.TrimSpace(os.Getenv(envOAuthClientSecret))
-}
-
-func Save(key string) (string, error) {
-	key = strings.TrimSpace(key)
-	if key == "" {
-		return "", errors.New("API key cannot be empty")
-	}
-	return updateFile(func(file *File) { file.APIKey = key })
-}
-
-func SaveOAuth(credentials OAuthCredentials) (string, error) {
-	if err := normalizeOAuth(&credentials); err != nil {
-		return "", err
-	}
-	return updateFile(func(file *File) { file.OAuth = cloneOAuth(&credentials) })
-}
-
-// SaveRefreshedOAuth persists a token refresh only if the stored authorization
-// is still the one that was refreshed. This prevents a refresh that began
-// before logout (or a new login) from restoring obsolete credentials.
-func SaveRefreshedOAuth(expected, credentials OAuthCredentials) (bool, error) {
-	if err := normalizeOAuth(&credentials); err != nil {
-		return false, err
-	}
-	path, err := Path()
-	if err != nil {
-		return false, err
-	}
-	unlock, err := acquireUpdateLock(path)
-	if err != nil {
-		return false, err
-	}
-	defer unlock()
-	file, _, err := loadFile(path)
-	if err != nil {
-		return false, err
-	}
-	if !sameOAuth(file.OAuth, &expected) {
-		return false, nil
-	}
-	_, err = saveFile(path, File{APIKey: file.APIKey, OAuth: cloneOAuth(&credentials)})
-	return err == nil, err
-}
-
-func ClearAPIKey() (string, error) {
-	return updateFile(func(file *File) { file.APIKey = "" })
-}
-
-func ClearOAuth() (string, error) {
-	return updateFile(func(file *File) { file.OAuth = nil })
-}
-
-func Remove() (string, bool, error) {
-	path, err := Path()
-	if err != nil {
-		return "", false, err
-	}
-	// Take the same lock as saves: a concurrent save that already read the
-	// file must not be able to recreate credentials after removal.
-	unlock, err := acquireUpdateLock(path)
-	if err != nil {
-		return "", false, err
-	}
-	defer unlock()
-	if err := os.Remove(path); err != nil {
-		if errors.Is(err, os.ErrNotExist) {
-			return path, false, nil
-		}
-		return path, false, fmt.Errorf("remove credentials: %w", err)
-	}
-	return path, true, nil
-}
-
-func Fingerprint(key string) string {
-	key = strings.TrimSpace(key)
-	if key == "" {
-		return ""
-	}
-	sum := sha256.Sum256([]byte(key))
-	return "sha256:" + hex.EncodeToString(sum[:])[:12]
-}
-
-func EnvKeySet() bool { return strings.TrimSpace(os.Getenv(envKey)) != "" }
-
-func EnvOAuthClientIDSet() bool {
-	return strings.TrimSpace(os.Getenv(envOAuthClientID)) != ""
-}
-
-func EnvOAuthClientSecretSet() bool {
-	return strings.TrimSpace(os.Getenv(envOAuthClientSecret)) != ""
-}
-
-func updateFile(update func(*File)) (string, error) {
-	path, err := Path()
-	if err != nil {
-		return "", err
-	}
-	// Serialize the read-modify-write across processes with an exclusive
-	// advisory lock on a sidecar file; the atomic rename alone cannot
-	// prevent one concurrent update from silently overwriting another
-	// (e.g. a token refresh racing an API-key save).
-	unlock, err := acquireUpdateLock(path)
-	if err != nil {
-		return "", err
-	}
-	defer unlock()
-	file, _, err := loadFile(path)
-	if err != nil {
-		return "", err
-	}
-	update(&file)
-	return saveFile(path, file)
-}
-
-func acquireUpdateLock(path string) (func(), error) {
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0o700); err != nil {
-		return nil, fmt.Errorf("create config directory: %w", err)
-	}
-	lock, err := os.OpenFile(filepath.Join(dir, ".auth.lock"), os.O_CREATE|os.O_RDWR, 0o600)
-	if err != nil {
-		return nil, fmt.Errorf("open credential lock file: %w", err)
-	}
-	if err := lockFile(lock); err != nil {
-		lock.Close()
-		return nil, fmt.Errorf("lock credential file: %w", err)
-	}
-	return func() {
-		_ = unlockFile(lock)
-		lock.Close()
-	}, nil
-}
-
-func loadFile(path string) (File, bool, error) {
-	data, err := os.ReadFile(path)
-	if errors.Is(err, os.ErrNotExist) {
-		return File{}, false, nil
-	}
-	if err != nil {
-		return File{}, false, fmt.Errorf("read credentials: %w", err)
-	}
-	var file File
-	if err := json.Unmarshal(data, &file); err != nil {
-		return File{}, true, fmt.Errorf("parse credentials: %w", err)
-	}
-	return file, true, nil
-}
-
-func saveFile(path string, file File) (string, error) {
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0o700); err != nil {
-		return "", fmt.Errorf("create config directory: %w", err)
-	}
-	_ = os.Chmod(dir, 0o700)
-	data, err := json.MarshalIndent(file, "", "  ")
-	if err != nil {
-		return "", err
-	}
-	data = append(data, '\n')
-	tmp, err := os.CreateTemp(dir, ".auth-*.tmp")
-	if err != nil {
-		return "", fmt.Errorf("create temporary credential file: %w", err)
-	}
-	tmpName := tmp.Name()
-	defer os.Remove(tmpName)
-	if err := tmp.Chmod(0o600); err != nil {
-		tmp.Close()
-		return "", fmt.Errorf("secure temporary credential file: %w", err)
-	}
-	if _, err := tmp.Write(data); err != nil {
-		tmp.Close()
-		return "", fmt.Errorf("write credentials: %w", err)
-	}
-	if err := tmp.Sync(); err != nil {
-		tmp.Close()
-		return "", fmt.Errorf("sync credentials: %w", err)
-	}
-	if err := tmp.Close(); err != nil {
-		return "", err
-	}
-	if err := replaceFile(tmpName, path); err != nil {
-		return "", fmt.Errorf("install credentials: %w", err)
-	}
-	_ = os.Chmod(path, 0o600)
-	return path, nil
-}
-
-func normalizeOAuth(credentials *OAuthCredentials) error {
-	credentials.ClientID = strings.TrimSpace(credentials.ClientID)
-	credentials.ClientSecret = strings.TrimSpace(credentials.ClientSecret)
-	credentials.AccessToken = strings.TrimSpace(credentials.AccessToken)
-	credentials.RefreshToken = strings.TrimSpace(credentials.RefreshToken)
-	credentials.Expiry = strings.TrimSpace(credentials.Expiry)
-	if credentials.ClientID == "" || credentials.ClientSecret == "" {
-		return errors.New("OAuth client ID and client secret cannot be empty")
-	}
-	if credentials.AccessToken == "" && credentials.RefreshToken == "" {
-		return errors.New("OAuth access token or refresh token is required")
-	}
-	return nil
-}
-
-func sameOAuth(left, right *OAuthCredentials) bool {
-	if left == nil || right == nil {
-		return left == right
-	}
-	if left.ClientID != right.ClientID || left.ClientSecret != right.ClientSecret || left.AccessToken != right.AccessToken || left.RefreshToken != right.RefreshToken || left.Expiry != right.Expiry || len(left.Scopes) != len(right.Scopes) {
-		return false
-	}
-	for i, scope := range left.Scopes {
-		if scope != right.Scopes[i] {
-			return false
-		}
-	}
-	return true
-}
-
-func cloneOAuth(credentials *OAuthCredentials) *OAuthCredentials {
-	if credentials == nil {
-		return nil
-	}
-	copy := *credentials
-	copy.Scopes = append([]string(nil), credentials.Scopes...)
-	return ©
-}
-
-func expandHome(path string) string {
-	if path == "~" || strings.HasPrefix(path, "~/") || strings.HasPrefix(path, `~\`) {
-		if home, err := os.UserHomeDir(); err == nil {
-			if len(path) == 1 {
-				return home
-			}
-			return filepath.Join(home, path[2:])
-		}
-	}
-	return path
-}
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
deleted file mode 100644
index 2ab08cc..0000000
--- a/internal/config/config_test.go
+++ /dev/null
@@ -1,231 +0,0 @@
-package config
-
-import (
-	"encoding/json"
-	"os"
-	"path/filepath"
-	"runtime"
-	"strings"
-	"sync"
-	"testing"
-)
-
-func TestSaveLoadRemoveAndModes(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("OYTC_CONFIG_DIR", filepath.Join(dir, "nested"))
-	t.Setenv("OYTC_API_KEY", "")
-
-	path, err := Save("test-secret-key")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if path != filepath.Join(dir, "nested", "auth.json") {
-		t.Fatalf("unexpected path %q", path)
-	}
-	data, err := os.ReadFile(path)
-	if err != nil {
-		t.Fatal(err)
-	}
-	var file File
-	if err := json.Unmarshal(data, &file); err != nil {
-		t.Fatal(err)
-	}
-	if file.APIKey != "test-secret-key" {
-		t.Fatalf("wrong saved key %q", file.APIKey)
-	}
-	if runtime.GOOS != "windows" {
-		if mode := mustStat(t, path).Mode().Perm(); mode != 0o600 {
-			t.Fatalf("file mode = %o, want 600", mode)
-		}
-		if mode := mustStat(t, filepath.Dir(path)).Mode().Perm(); mode != 0o700 {
-			t.Fatalf("directory mode = %o, want 700", mode)
-		}
-	}
-	credentials, err := Load()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if credentials.Key != "test-secret-key" || credentials.Source != "auth.json" {
-		t.Fatalf("unexpected credentials: %#v", credentials)
-	}
-	if _, err := Save("replacement-secret"); err != nil {
-		t.Fatalf("replace credentials: %v", err)
-	}
-	credentials, err = Load()
-	if err != nil || credentials.Key != "replacement-secret" {
-		t.Fatalf("replacement credentials: %#v, %v", credentials, err)
-	}
-	removedPath, removed, err := Remove()
-	if err != nil || !removed || removedPath != path {
-		t.Fatalf("Remove() = %q, %t, %v", removedPath, removed, err)
-	}
-	_, removed, err = Remove()
-	if err != nil || removed {
-		t.Fatalf("idempotent Remove() = %t, %v", removed, err)
-	}
-}
-
-func TestAPIKeyAndOAuthCoexistAndUpdateIndependently(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "")
-	if _, err := Save("api-secret"); err != nil {
-		t.Fatal(err)
-	}
-	oauth := OAuthCredentials{
-		ClientID: "desktop-id", ClientSecret: "client-secret", AccessToken: "access-secret",
-		RefreshToken: "refresh-secret", Expiry: "2026-02-01T12:00:00Z", Scopes: []string{"scope.one", "scope.two"},
-	}
-	if _, err := SaveOAuth(oauth); err != nil {
-		t.Fatal(err)
-	}
-	credentials, err := Load()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if credentials.Key != "api-secret" || credentials.OAuth == nil || credentials.OAuth.ClientID != "desktop-id" || credentials.OAuth.RefreshToken != "refresh-secret" {
-		t.Fatalf("coexisting credentials: %#v", credentials)
-	}
-	if _, err := Save("replacement-key"); err != nil {
-		t.Fatal(err)
-	}
-	credentials, err = Load()
-	if err != nil || credentials.OAuth == nil || credentials.OAuth.AccessToken != "access-secret" {
-		t.Fatalf("API-key update clobbered OAuth: %#v, %v", credentials, err)
-	}
-	if _, err := ClearOAuth(); err != nil {
-		t.Fatal(err)
-	}
-	credentials, err = Load()
-	if err != nil || credentials.Key != "replacement-key" || credentials.OAuth != nil {
-		t.Fatalf("OAuth clear clobbered API key: %#v, %v", credentials, err)
-	}
-}
-
-func TestOAuthBootstrapEnvironmentPrecedence(t *testing.T) {
-	t.Setenv("OYTC_OAUTH_CLIENT_ID", "environment-id")
-	t.Setenv("OYTC_OAUTH_CLIENT_SECRET", "environment-secret")
-	id, secret := OAuthBootstrap()
-	if id != "environment-id" || secret != "environment-secret" {
-		t.Fatalf("OAuthBootstrap() = %q, %q", id, secret)
-	}
-}
-
-func TestConcurrentUpdatesAreNotLost(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "")
-	oauth := OAuthCredentials{
-		ClientID: "id", ClientSecret: "secret", AccessToken: "access",
-		RefreshToken: "refresh", Expiry: "2026-02-01T12:00:00Z", Scopes: []string{"scope"},
-	}
-	var group sync.WaitGroup
-	errs := make(chan error, 2)
-	group.Add(2)
-	go func() {
-		defer group.Done()
-		_, err := Save("api-secret")
-		errs <- err
-	}()
-	go func() {
-		defer group.Done()
-		_, err := SaveOAuth(oauth)
-		errs <- err
-	}()
-	group.Wait()
-	close(errs)
-	for err := range errs {
-		if err != nil {
-			t.Fatal(err)
-		}
-	}
-	credentials, err := Load()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if credentials.Key != "api-secret" || credentials.OAuth == nil || credentials.OAuth.RefreshToken != "refresh" {
-		t.Fatalf("a concurrent update was lost: %#v", credentials)
-	}
-}
-
-func TestRefreshedOAuthDoesNotRestoreRemovedCredentials(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "")
-	initial := OAuthCredentials{
-		ClientID: "id", ClientSecret: "secret", AccessToken: "old-access",
-		RefreshToken: "refresh", Expiry: "2026-02-01T12:00:00Z", Scopes: []string{"scope"},
-	}
-	if _, err := SaveOAuth(initial); err != nil {
-		t.Fatal(err)
-	}
-	if _, removed, err := Remove(); err != nil || !removed {
-		t.Fatalf("Remove() = %t, %v", removed, err)
-	}
-	updated := initial
-	updated.AccessToken = "new-access"
-	updated.Expiry = "2026-02-01T13:00:00Z"
-	saved, err := SaveRefreshedOAuth(initial, updated)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if saved {
-		t.Fatal("stale refresh restored credentials after logout")
-	}
-	path, err := Path()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := os.Stat(path); !os.IsNotExist(err) {
-		t.Fatalf("credentials file exists after logout: %v", err)
-	}
-}
-
-func TestLoadFallsBackToEnvironmentKeyWhenFileCorrupt(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("OYTC_CONFIG_DIR", dir)
-	t.Setenv("OYTC_API_KEY", "environment-secret")
-	if err := os.WriteFile(filepath.Join(dir, "auth.json"), []byte("{not json"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	credentials, err := Load()
-	if err != nil {
-		t.Fatalf("Load with corrupt file and env key: %v", err)
-	}
-	if credentials.Key != "environment-secret" || credentials.Source != "OYTC_API_KEY" {
-		t.Fatalf("credentials = %#v", credentials)
-	}
-	t.Setenv("OYTC_API_KEY", "")
-	if _, err := Load(); err == nil {
-		t.Fatal("expected parse error without environment key")
-	}
-}
-
-func TestEnvironmentKeyHasPrecedence(t *testing.T) {
-	t.Setenv("OYTC_CONFIG_DIR", t.TempDir())
-	t.Setenv("OYTC_API_KEY", "environment-secret")
-	if _, err := Save("file-secret"); err != nil {
-		t.Fatal(err)
-	}
-	credentials, err := Load()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if credentials.Key != "environment-secret" || credentials.Source != "OYTC_API_KEY" {
-		t.Fatalf("unexpected credentials: %#v", credentials)
-	}
-}
-
-func TestFingerprintDoesNotExposeKey(t *testing.T) {
-	key := "this-is-a-secret-key"
-	fingerprint := Fingerprint(key)
-	if !strings.HasPrefix(fingerprint, "sha256:") || strings.Contains(fingerprint, key) || len(fingerprint) != len("sha256:")+12 {
-		t.Fatalf("unsafe fingerprint %q", fingerprint)
-	}
-}
-
-func mustStat(t *testing.T, path string) os.FileInfo {
-	t.Helper()
-	info, err := os.Stat(path)
-	if err != nil {
-		t.Fatal(err)
-	}
-	return info
-}
diff --git a/internal/config/lock_unix.go b/internal/config/lock_unix.go
deleted file mode 100644
index 57d58f8..0000000
--- a/internal/config/lock_unix.go
+++ /dev/null
@@ -1,17 +0,0 @@
-//go:build !windows
-
-package config
-
-import (
-	"os"
-
-	"golang.org/x/sys/unix"
-)
-
-func lockFile(file *os.File) error {
-	return unix.Flock(int(file.Fd()), unix.LOCK_EX)
-}
-
-func unlockFile(file *os.File) error {
-	return unix.Flock(int(file.Fd()), unix.LOCK_UN)
-}
diff --git a/internal/config/lock_windows.go b/internal/config/lock_windows.go
deleted file mode 100644
index a83341e..0000000
--- a/internal/config/lock_windows.go
+++ /dev/null
@@ -1,19 +0,0 @@
-//go:build windows
-
-package config
-
-import (
-	"os"
-
-	"golang.org/x/sys/windows"
-)
-
-func lockFile(file *os.File) error {
-	overlapped := new(windows.Overlapped)
-	return windows.LockFileEx(windows.Handle(file.Fd()), windows.LOCKFILE_EXCLUSIVE_LOCK, 0, 1, 0, overlapped)
-}
-
-func unlockFile(file *os.File) error {
-	overlapped := new(windows.Overlapped)
-	return windows.UnlockFileEx(windows.Handle(file.Fd()), 0, 1, 0, overlapped)
-}
diff --git a/internal/config/rename_unix.go b/internal/config/rename_unix.go
deleted file mode 100644
index 3264ee6..0000000
--- a/internal/config/rename_unix.go
+++ /dev/null
@@ -1,9 +0,0 @@
-//go:build !windows
-
-package config
-
-import "os"
-
-func replaceFile(source, destination string) error {
-	return os.Rename(source, destination)
-}
diff --git a/internal/config/rename_windows.go b/internal/config/rename_windows.go
deleted file mode 100644
index bd67185..0000000
--- a/internal/config/rename_windows.go
+++ /dev/null
@@ -1,17 +0,0 @@
-//go:build windows
-
-package config
-
-import "golang.org/x/sys/windows"
-
-func replaceFile(source, destination string) error {
-	sourcePath, err := windows.UTF16PtrFromString(source)
-	if err != nil {
-		return err
-	}
-	destinationPath, err := windows.UTF16PtrFromString(destination)
-	if err != nil {
-		return err
-	}
-	return windows.MoveFileEx(sourcePath, destinationPath, windows.MOVEFILE_REPLACE_EXISTING|windows.MOVEFILE_WRITE_THROUGH)
-}
diff --git a/internal/oauth/oauth.go b/internal/oauth/oauth.go
deleted file mode 100644
index c18c4b3..0000000
--- a/internal/oauth/oauth.go
+++ /dev/null
@@ -1,426 +0,0 @@
-// Package oauth wraps golang.org/x/oauth2 with Google's loopback redirect
-// flow, token revocation, and a self-persisting token source.
-package oauth
-
-import (
-	"context"
-	"crypto/rand"
-	"encoding/base64"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"net"
-	"net/http"
-	"net/url"
-	"os/exec"
-	"runtime"
-	"strings"
-	"sync"
-	"time"
-
-	"golang.org/x/oauth2"
-)
-
-const (
-	DefaultAuthorizationURL = "https://accounts.google.com/o/oauth2/v2/auth"
-	DefaultTokenURL         = "https://oauth2.googleapis.com/token"
-	DefaultRevokeURL        = "https://oauth2.googleapis.com/revoke"
-	DefaultLoginTimeout     = 3 * time.Minute
-)
-
-type Token struct {
-	AccessToken  string
-	RefreshToken string
-	Expiry       time.Time
-	Scopes       []string
-}
-
-type Config struct {
-	ClientID     string
-	ClientSecret string
-	Scopes       []string
-
-	AuthorizationURL string
-	TokenURL         string
-	RevokeURL        string
-	HTTPClient       *http.Client
-	OpenBrowser      func(string) error
-	Out              io.Writer
-	Timeout          time.Duration
-	// Now is used for local expiry checks; golang.org/x/oauth2 stamps
-	// token expiries with the real clock.
-	Now func() time.Time
-}
-
-type Error struct {
-	HTTPStatus  int
-	Code        string
-	Description string
-}
-
-func (e *Error) Error() string {
-	if e.Description != "" {
-		return fmt.Sprintf("OAuth error (%s): %s", valueOr(e.Code, "unknown"), e.Description)
-	}
-	return fmt.Sprintf("OAuth error (%s)", valueOr(e.Code, "unknown"))
-}
-
-func Login(ctx context.Context, cfg Config) (Token, error) {
-	cfg = withDefaults(cfg)
-	if strings.TrimSpace(cfg.ClientID) == "" {
-		return Token{}, errors.New("OAuth client ID cannot be empty")
-	}
-	if strings.TrimSpace(cfg.ClientSecret) == "" {
-		return Token{}, errors.New("OAuth client secret cannot be empty")
-	}
-
-	listener, err := net.Listen("tcp", "127.0.0.1:0")
-	if err != nil {
-		return Token{}, fmt.Errorf("start OAuth callback listener: %w", err)
-	}
-	defer listener.Close()
-
-	state, err := randomString(32)
-	if err != nil {
-		return Token{}, err
-	}
-	verifier := oauth2.GenerateVerifier()
-	redirectURI := "http://" + listener.Addr().String()
-	authorizationURL := AuthorizationURL(cfg, redirectURI, state, verifier)
-
-	type callbackResult struct {
-		code string
-		err  error
-	}
-	result := make(chan callbackResult, 1)
-	mux := http.NewServeMux()
-	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
-		query := r.URL.Query()
-		if query.Get("state") != state {
-			// Reject the request but keep the login alive: any unrelated
-			// local request (favicon probe, port scanner) must not be able
-			// to abort the flow before Google's real redirect arrives.
-			http.Error(w, "OAuth state did not match. You can close this window.", http.StatusBadRequest)
-			return
-		}
-		if code := query.Get("error"); code != "" {
-			description := query.Get("error_description")
-			http.Error(w, "Authorization was not granted. You can close this window.", http.StatusBadRequest)
-			select {
-			case result <- callbackResult{err: &Error{Code: code, Description: description}}:
-			default:
-			}
-			return
-		}
-		code := strings.TrimSpace(query.Get("code"))
-		if code == "" {
-			http.Error(w, "The OAuth callback did not include a code. You can close this window.", http.StatusBadRequest)
-			select {
-			case result <- callbackResult{err: errors.New("OAuth callback did not include an authorization code")}:
-			default:
-			}
-			return
-		}
-		w.Header().Set("Content-Type", "text/html; charset=utf-8")
-		_, _ = io.WriteString(w, "oytc authorized
Authorization complete. You can close this window and return to oytc.
")
-		select {
-		case result <- callbackResult{code: code}:
-		default:
-		}
-	})
-	server := &http.Server{Handler: mux, ReadHeaderTimeout: 5 * time.Second}
-	serveDone := make(chan error, 1)
-	go func() {
-		err := server.Serve(listener)
-		if errors.Is(err, http.ErrServerClosed) {
-			err = nil
-		}
-		serveDone <- err
-	}()
-
-	fmt.Fprintf(cfg.Out, "Open this URL to authorize oytc:\n%s\n", authorizationURL)
-	if err := cfg.OpenBrowser(authorizationURL); err != nil {
-		fmt.Fprintf(cfg.Out, "Could not open a browser automatically: %v\n", err)
-	}
-
-	loginCtx, cancel := context.WithTimeout(ctx, cfg.Timeout)
-	defer cancel()
-	var callback callbackResult
-	select {
-	case callback = <-result:
-	case err := <-serveDone:
-		if err == nil {
-			err = errors.New("OAuth callback server stopped before authorization completed")
-		}
-		return Token{}, fmt.Errorf("serve OAuth callback: %w", err)
-	case <-loginCtx.Done():
-		if errors.Is(loginCtx.Err(), context.DeadlineExceeded) {
-			return Token{}, errors.New("timed out waiting for OAuth authorization")
-		}
-		return Token{}, loginCtx.Err()
-	}
-	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), time.Second)
-	_ = server.Shutdown(shutdownCtx)
-	shutdownCancel()
-	if callback.err != nil {
-		return Token{}, callback.err
-	}
-	// The callback timeout applies only while waiting for the browser. Give the
-	// token exchange the caller's context instead of its leftover duration.
-	return Exchange(ctx, cfg, callback.code, redirectURI, verifier)
-}
-
-// AuthorizationURL builds the consent URL; verifier is the PKCE code verifier
-// whose S256 challenge is embedded.
-func AuthorizationURL(cfg Config, redirectURI, state, verifier string) string {
-	cfg = withDefaults(cfg)
-	library := cfg.library()
-	library.RedirectURL = redirectURI
-	return library.AuthCodeURL(state,
-		oauth2.AccessTypeOffline,
-		oauth2.S256ChallengeOption(verifier),
-		// Force the consent screen so Google always returns a refresh
-		// token, not only on the first authorization.
-		oauth2.SetAuthURLParam("prompt", "consent"),
-	)
-}
-
-func Exchange(ctx context.Context, cfg Config, code, redirectURI, verifier string) (Token, error) {
-	cfg = withDefaults(cfg)
-	library := cfg.library()
-	library.RedirectURL = redirectURI
-	token, err := library.Exchange(cfg.context(ctx), code, oauth2.VerifierOption(verifier))
-	if err != nil {
-		return Token{}, translateError(err, "request OAuth token")
-	}
-	return fromLibrary(token, cfg, Token{}), nil
-}
-
-func Refresh(ctx context.Context, cfg Config, current Token) (Token, error) {
-	if strings.TrimSpace(current.RefreshToken) == "" {
-		return Token{}, errors.New("OAuth refresh token is missing; re-run 'oytc login --oauth'")
-	}
-	cfg = withDefaults(cfg)
-	// A seed token with no access token forces TokenSource straight to the
-	// refresh_token grant.
-	seed := &oauth2.Token{RefreshToken: current.RefreshToken}
-	token, err := cfg.library().TokenSource(cfg.context(ctx), seed).Token()
-	if err != nil {
-		return Token{}, translateError(err, "refresh OAuth token")
-	}
-	return fromLibrary(token, cfg, current), nil
-}
-
-func Revoke(ctx context.Context, cfg Config, token string) error {
-	cfg = withDefaults(cfg)
-	if strings.TrimSpace(token) == "" {
-		return nil
-	}
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, cfg.RevokeURL, strings.NewReader(url.Values{"token": {token}}.Encode()))
-	if err != nil {
-		return err
-	}
-	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-	req.Header.Set("Accept", "application/json")
-	resp, err := cfg.HTTPClient.Do(req)
-	if err != nil {
-		return fmt.Errorf("revoke OAuth token: %w", err)
-	}
-	defer resp.Body.Close()
-	body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return parseError(resp.StatusCode, body)
-	}
-	return nil
-}
-
-type TokenSource struct {
-	Config   Config
-	Token    Token
-	OnUpdate func(Token) error
-
-	mu sync.Mutex
-}
-
-func (s *TokenSource) AccessToken(ctx context.Context, forceRefresh bool) (string, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	cfg := withDefaults(s.Config)
-	if !forceRefresh && strings.TrimSpace(s.Token.AccessToken) != "" && s.Token.Expiry.After(cfg.Now().Add(time.Minute)) {
-		return s.Token.AccessToken, nil
-	}
-	updated, err := Refresh(ctx, cfg, s.Token)
-	if err != nil {
-		var oauthErr *Error
-		if errors.As(err, &oauthErr) && (oauthErr.Code == "invalid_grant" || oauthErr.Code == "invalid_client") {
-			return "", fmt.Errorf("OAuth authorization is expired or revoked; re-run 'oytc login --oauth': %w", err)
-		}
-		return "", err
-	}
-	if s.OnUpdate != nil {
-		if err := s.OnUpdate(updated); err != nil {
-			return "", fmt.Errorf("persist refreshed OAuth token: %w", err)
-		}
-	}
-	s.Token = updated
-	return updated.AccessToken, nil
-}
-
-func (c Config) library() *oauth2.Config {
-	return &oauth2.Config{
-		ClientID:     c.ClientID,
-		ClientSecret: c.ClientSecret,
-		Scopes:       c.Scopes,
-		Endpoint: oauth2.Endpoint{
-			AuthURL:  c.AuthorizationURL,
-			TokenURL: c.TokenURL,
-			// Google accepts credentials in the POST body; pinning the
-			// style avoids the library's two-request auto-detection.
-			AuthStyle: oauth2.AuthStyleInParams,
-		},
-	}
-}
-
-// context injects cfg.HTTPClient into the oauth2 library, which only accepts
-// a custom client via context.
-func (c Config) context(ctx context.Context) context.Context {
-	return context.WithValue(ctx, oauth2.HTTPClient, c.HTTPClient)
-}
-
-// fromLibrary converts an oauth2 token, inheriting the refresh token and
-// scopes from the previous token when a response omits them.
-func fromLibrary(token *oauth2.Token, cfg Config, current Token) Token {
-	refreshToken := token.RefreshToken
-	if refreshToken == "" {
-		refreshToken = current.RefreshToken
-	}
-	granted, _ := token.Extra("scope").(string)
-	scopes := strings.Fields(granted)
-	if len(scopes) == 0 {
-		if len(current.Scopes) > 0 {
-			scopes = append([]string(nil), current.Scopes...)
-		} else {
-			scopes = append([]string(nil), cfg.Scopes...)
-		}
-	}
-	return Token{
-		AccessToken:  token.AccessToken,
-		RefreshToken: refreshToken,
-		Expiry:       token.Expiry,
-		Scopes:       scopes,
-	}
-}
-
-// translateError maps the library's *oauth2.RetrieveError onto *Error so the
-// CLI's exit-code and re-login-hint logic keeps working.
-func translateError(err error, action string) error {
-	var retrieve *oauth2.RetrieveError
-	if !errors.As(err, &retrieve) {
-		var urlErr *url.Error
-		if errors.As(err, &urlErr) {
-			return fmt.Errorf("%s: %w", action, urlErr.Err)
-		}
-		return err
-	}
-	status := 0
-	if retrieve.Response != nil {
-		status = retrieve.Response.StatusCode
-	}
-	if retrieve.ErrorCode != "" {
-		return &Error{HTTPStatus: status, Code: retrieve.ErrorCode, Description: retrieve.ErrorDescription}
-	}
-	// The library only parses RFC 6749 fields for JSON/form content types;
-	// fall back to parsing the body directly.
-	return parseError(status, retrieve.Body)
-}
-
-func parseError(status int, body []byte) error {
-	var response struct {
-		Error            string `json:"error"`
-		ErrorDescription string `json:"error_description"`
-	}
-	_ = json.Unmarshal(body, &response)
-	if response.Error == "" {
-		response.Error = http.StatusText(status)
-	}
-	if response.ErrorDescription == "" {
-		response.ErrorDescription = strings.TrimSpace(string(body))
-	}
-	return &Error{HTTPStatus: status, Code: response.Error, Description: response.ErrorDescription}
-}
-
-func withDefaults(cfg Config) Config {
-	if cfg.AuthorizationURL == "" {
-		cfg.AuthorizationURL = DefaultAuthorizationURL
-	}
-	if cfg.TokenURL == "" {
-		cfg.TokenURL = DefaultTokenURL
-	}
-	if cfg.RevokeURL == "" {
-		cfg.RevokeURL = DefaultRevokeURL
-	}
-	if cfg.HTTPClient == nil {
-		cfg.HTTPClient = &http.Client{Timeout: 20 * time.Second}
-	}
-	if cfg.OpenBrowser == nil {
-		cfg.OpenBrowser = OpenBrowser
-	}
-	if cfg.Out == nil {
-		cfg.Out = io.Discard
-	}
-	if cfg.Timeout <= 0 {
-		cfg.Timeout = DefaultLoginTimeout
-	}
-	if cfg.Now == nil {
-		cfg.Now = time.Now
-	}
-	return cfg
-}
-
-func OpenBrowser(target string) error {
-	var command string
-	var args []string
-	switch runtime.GOOS {
-	case "darwin":
-		command, args = "open", []string{target}
-	case "windows":
-		command, args = "rundll32", []string{"url.dll,FileProtocolHandler", target}
-	default:
-		command, args = "xdg-open", []string{target}
-	}
-	return exec.Command(command, args...).Start()
-}
-
-func randomString(bytes int) (string, error) {
-	data := make([]byte, bytes)
-	if _, err := rand.Read(data); err != nil {
-		return "", fmt.Errorf("generate OAuth random value: %w", err)
-	}
-	return base64.RawURLEncoding.EncodeToString(data), nil
-}
-
-func valueOr(value, fallback string) string {
-	if value == "" {
-		return fallback
-	}
-	return value
-}
-
-func ParseExpiry(value string) (time.Time, error) {
-	if strings.TrimSpace(value) == "" {
-		return time.Time{}, nil
-	}
-	expiry, err := time.Parse(time.RFC3339, value)
-	if err != nil {
-		return time.Time{}, fmt.Errorf("parse OAuth token expiry: %w", err)
-	}
-	return expiry, nil
-}
-
-func FormatExpiry(expiry time.Time) string {
-	if expiry.IsZero() {
-		return ""
-	}
-	return expiry.UTC().Format(time.RFC3339)
-}
diff --git a/internal/oauth/oauth_test.go b/internal/oauth/oauth_test.go
deleted file mode 100644
index e3b51a8..0000000
--- a/internal/oauth/oauth_test.go
+++ /dev/null
@@ -1,263 +0,0 @@
-package oauth
-
-import (
-	"context"
-	"errors"
-	"io"
-	"net/http"
-	"net/http/httptest"
-	"net/url"
-	"strings"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"golang.org/x/oauth2"
-)
-
-func writeTokenJSON(w http.ResponseWriter, body string) {
-	// x/oauth2 parses token responses by Content-Type; without this header
-	// the sniffer reports text/plain and the body is misread as form data.
-	w.Header().Set("Content-Type", "application/json")
-	_, _ = io.WriteString(w, body)
-}
-
-func TestAuthorizationURL(t *testing.T) {
-	verifier := oauth2.GenerateVerifier()
-	target := AuthorizationURL(Config{
-		ClientID:         "desktop-client",
-		Scopes:           []string{"scope.one", "scope.two"},
-		AuthorizationURL: "https://accounts.example/authorize",
-	}, "http://127.0.0.1:1234", "state-value", verifier)
-	parsed, err := url.Parse(target)
-	if err != nil {
-		t.Fatal(err)
-	}
-	query := parsed.Query()
-	for key, want := range map[string]string{
-		"client_id": "desktop-client", "redirect_uri": "http://127.0.0.1:1234",
-		"response_type": "code", "scope": "scope.one scope.two", "state": "state-value",
-		"code_challenge": oauth2.S256ChallengeFromVerifier(verifier), "code_challenge_method": "S256",
-		"access_type": "offline", "prompt": "consent",
-	} {
-		if got := query.Get(key); got != want {
-			t.Errorf("%s = %q, want %q", key, got, want)
-		}
-	}
-}
-
-func TestExchangeAndRefresh(t *testing.T) {
-	var requests atomic.Int32
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodPost || !strings.HasPrefix(r.Header.Get("Content-Type"), "application/x-www-form-urlencoded") {
-			t.Errorf("unexpected request: %s %s", r.Method, r.Header.Get("Content-Type"))
-		}
-		if err := r.ParseForm(); err != nil {
-			t.Fatal(err)
-		}
-		switch requests.Add(1) {
-		case 1:
-			if r.Form.Get("grant_type") != "authorization_code" || r.Form.Get("code") != "code" || r.Form.Get("code_verifier") != "verifier" {
-				t.Errorf("exchange form: %v", r.Form)
-			}
-			writeTokenJSON(w, `{"access_token":"access-1","refresh_token":"refresh-1","expires_in":3600,"scope":"one two","token_type":"Bearer"}`)
-		case 2:
-			if r.Form.Get("grant_type") != "refresh_token" || r.Form.Get("refresh_token") != "refresh-1" {
-				t.Errorf("refresh form: %v", r.Form)
-			}
-			writeTokenJSON(w, `{"access_token":"access-2","expires_in":1800,"token_type":"Bearer"}`)
-		}
-	}))
-	defer server.Close()
-	cfg := Config{ClientID: "id", ClientSecret: "secret", TokenURL: server.URL, HTTPClient: server.Client()}
-	token, err := Exchange(context.Background(), cfg, "code", "http://127.0.0.1/callback", "verifier")
-	if err != nil {
-		t.Fatal(err)
-	}
-	// x/oauth2 stamps expiry from the real clock, so assert a window
-	// rather than an exact instant.
-	untilExpiry := time.Until(token.Expiry)
-	if token.AccessToken != "access-1" || token.RefreshToken != "refresh-1" || len(token.Scopes) != 2 ||
-		untilExpiry < 55*time.Minute || untilExpiry > 65*time.Minute {
-		t.Fatalf("exchange token: %#v", token)
-	}
-	refreshed, err := Refresh(context.Background(), cfg, token)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if refreshed.AccessToken != "access-2" || refreshed.RefreshToken != "refresh-1" || len(refreshed.Scopes) != 2 {
-		t.Fatalf("refresh token: %#v", refreshed)
-	}
-}
-
-func TestExchangeReturnsGoogleOAuthError(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusBadRequest)
-		_, _ = io.WriteString(w, `{"error":"invalid_grant","error_description":"authorization code expired"}`)
-	}))
-	defer server.Close()
-	_, err := Exchange(context.Background(), Config{ClientID: "id", ClientSecret: "secret", TokenURL: server.URL, HTTPClient: server.Client()}, "code", "redirect", "verifier")
-	var oauthErr *Error
-	if !errors.As(err, &oauthErr) || oauthErr.HTTPStatus != http.StatusBadRequest || oauthErr.Code != "invalid_grant" || oauthErr.Description != "authorization code expired" {
-		t.Fatalf("OAuth error = %T(%v)", err, err)
-	}
-}
-
-func TestExchangeErrorWithoutContentType(t *testing.T) {
-	// Some proxies and older endpoints omit the JSON content type; the
-	// error body must still surface as a structured *Error.
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusBadRequest)
-		_, _ = io.WriteString(w, `{"error":"invalid_grant","error_description":"authorization code expired"}`)
-	}))
-	defer server.Close()
-	_, err := Exchange(context.Background(), Config{ClientID: "id", ClientSecret: "secret", TokenURL: server.URL, HTTPClient: server.Client()}, "code", "redirect", "verifier")
-	var oauthErr *Error
-	if !errors.As(err, &oauthErr) || oauthErr.Code != "invalid_grant" {
-		t.Fatalf("OAuth error = %T(%v)", err, err)
-	}
-}
-
-func TestRevoke(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if err := r.ParseForm(); err != nil {
-			t.Fatal(err)
-		}
-		if r.Method != http.MethodPost || r.Form.Get("token") != "refresh-secret" {
-			t.Errorf("unexpected revoke request: %s %v", r.Method, r.Form)
-		}
-		w.WriteHeader(http.StatusOK)
-	}))
-	defer server.Close()
-	if err := Revoke(context.Background(), Config{RevokeURL: server.URL, HTTPClient: server.Client()}, "refresh-secret"); err != nil {
-		t.Fatal(err)
-	}
-}
-
-// getCallback issues the loopback callback request with the test's context so
-// a stalled listener cannot outlive the test.
-func getCallback(t *testing.T, callback string) {
-	t.Helper()
-	request, err := http.NewRequestWithContext(t.Context(), http.MethodGet, callback, nil)
-	if err != nil {
-		return
-	}
-	if resp, err := http.DefaultClient.Do(request); err == nil {
-		resp.Body.Close()
-	}
-}
-
-func TestLoginLoopbackSuccess(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if err := r.ParseForm(); err != nil {
-			t.Error(err)
-		}
-		if r.Form.Get("code") != "callback-code" || r.Form.Get("code_verifier") == "" {
-			t.Errorf("token form: %v", r.Form)
-		}
-		writeTokenJSON(w, `{"access_token":"access","refresh_token":"refresh","expires_in":3600,"scope":"scope","token_type":"Bearer"}`)
-	}))
-	defer server.Close()
-	var printed strings.Builder
-	cfg := Config{
-		ClientID: "id", ClientSecret: "secret", Scopes: []string{"scope"},
-		AuthorizationURL: "https://accounts.example/auth", TokenURL: server.URL,
-		HTTPClient: server.Client(), Out: &printed, Timeout: 3 * time.Second,
-	}
-	cfg.OpenBrowser = func(target string) error {
-		parsed, err := url.Parse(target)
-		if err != nil {
-			return err
-		}
-		if parsed.Query().Get("code_challenge") == "" || parsed.Query().Get("state") == "" {
-			t.Errorf("missing PKCE/state: %s", target)
-		}
-		callback := parsed.Query().Get("redirect_uri") + "?code=callback-code&state=" + url.QueryEscape(parsed.Query().Get("state"))
-		go getCallback(t, callback)
-		return nil
-	}
-	token, err := Login(context.Background(), cfg)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if token.AccessToken != "access" || !strings.Contains(printed.String(), "https://accounts.example/auth") {
-		t.Fatalf("token/output: %#v %q", token, printed.String())
-	}
-}
-
-func TestLoginLoopbackSurvivesStrayRequests(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if err := r.ParseForm(); err != nil {
-			t.Error(err)
-		}
-		writeTokenJSON(w, `{"access_token":"access","refresh_token":"refresh","expires_in":3600,"scope":"scope","token_type":"Bearer"}`)
-	}))
-	defer server.Close()
-	cfg := Config{
-		ClientID: "id", ClientSecret: "secret", Scopes: []string{"scope"},
-		AuthorizationURL: "https://accounts.example/auth", TokenURL: server.URL,
-		HTTPClient: server.Client(), Timeout: 3 * time.Second,
-	}
-	cfg.OpenBrowser = func(target string) error {
-		parsed, err := url.Parse(target)
-		if err != nil {
-			return err
-		}
-		redirect := parsed.Query().Get("redirect_uri")
-		go func() {
-			// A stray local request (no/incorrect state) must not abort the
-			// login before the real callback arrives.
-			getCallback(t, redirect+"/favicon.ico")
-			getCallback(t, redirect+"?code=evil&state=wrong")
-			getCallback(t, redirect+"?code=callback-code&state="+url.QueryEscape(parsed.Query().Get("state")))
-		}()
-		return nil
-	}
-	token, err := Login(context.Background(), cfg)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if token.AccessToken != "access" {
-		t.Fatalf("token = %#v", token)
-	}
-}
-
-func TestLoginLoopbackUserDenied(t *testing.T) {
-	cfg := Config{ClientID: "id", ClientSecret: "secret", AuthorizationURL: "https://accounts.example/auth", Timeout: 3 * time.Second}
-	cfg.OpenBrowser = func(target string) error {
-		parsed, _ := url.Parse(target)
-		callback := parsed.Query().Get("redirect_uri") + "?error=access_denied&error_description=nope&state=" + url.QueryEscape(parsed.Query().Get("state"))
-		go getCallback(t, callback)
-		return nil
-	}
-	_, err := Login(context.Background(), cfg)
-	var oauthErr *Error
-	if !errors.As(err, &oauthErr) || oauthErr.Code != "access_denied" {
-		t.Fatalf("expected access_denied, got %T: %v", err, err)
-	}
-}
-
-func TestTokenSourceRefreshAndOnUpdate(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		writeTokenJSON(w, `{"access_token":"new-access","expires_in":3600,"token_type":"Bearer"}`)
-	}))
-	defer server.Close()
-	now := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
-	var saved Token
-	source := &TokenSource{
-		Config: Config{ClientID: "id", ClientSecret: "secret", TokenURL: server.URL, HTTPClient: server.Client(), Now: func() time.Time { return now }},
-		Token:  Token{AccessToken: "old-access", RefreshToken: "refresh", Expiry: now.Add(-time.Minute), Scopes: []string{"scope"}},
-		OnUpdate: func(token Token) error {
-			saved = token
-			return nil
-		},
-	}
-	access, err := source.AccessToken(context.Background(), false)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if access != "new-access" || saved.AccessToken != "new-access" || saved.RefreshToken != "refresh" {
-		t.Fatalf("access/saved = %q %#v", access, saved)
-	}
-}
diff --git a/internal/output/output.go b/internal/output/output.go
deleted file mode 100644
index 12d303c..0000000
--- a/internal/output/output.go
+++ /dev/null
@@ -1,151 +0,0 @@
-// Package output renders API resources in stable human and machine formats.
-package output
-
-import (
-	"bufio"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"sort"
-	"strings"
-	"text/tabwriter"
-
-	"open-yt-cli/internal/youtube"
-)
-
-type Options struct {
-	Format   string
-	Columns  []string
-	NoHeader bool
-}
-
-var validFormats = map[string]bool{"table": true, "json": true, "jsonl": true, "tsv": true}
-
-func Render(w io.Writer, result youtube.ListResult, options Options) error {
-	if !validFormats[options.Format] {
-		return fmt.Errorf("unsupported format %q (use table, json, jsonl, or tsv)", options.Format)
-	}
-	switch options.Format {
-	case "json":
-		encoder := json.NewEncoder(w)
-		encoder.SetEscapeHTML(false)
-		encoder.SetIndent("", "  ")
-		return encoder.Encode(result)
-	case "jsonl":
-		encoder := json.NewEncoder(w)
-		encoder.SetEscapeHTML(false)
-		for _, item := range result.Items {
-			if err := encoder.Encode(item); err != nil {
-				return err
-			}
-		}
-		return nil
-	case "table", "tsv":
-		return renderRows(w, result.Items, options)
-	default:
-		return errors.New("unreachable output format")
-	}
-}
-
-func RenderObject(w io.Writer, object map[string]any, format string, columns []string, noHeader bool) error {
-	if format == "json" || format == "jsonl" {
-		encoder := json.NewEncoder(w)
-		encoder.SetEscapeHTML(false)
-		if format == "json" {
-			encoder.SetIndent("", "  ")
-		}
-		return encoder.Encode(object)
-	}
-	return renderRows(w, []map[string]any{object}, Options{Format: format, Columns: columns, NoHeader: noHeader})
-}
-
-func renderRows(w io.Writer, items []map[string]any, options Options) error {
-	columns := options.Columns
-	if len(columns) == 0 {
-		columns = []string{"id", "snippet.title"}
-	}
-	var target io.Writer = w
-	var table *tabwriter.Writer
-	if options.Format == "table" {
-		table = tabwriter.NewWriter(w, 0, 4, 2, ' ', 0)
-		target = table
-	} else {
-		target = bufio.NewWriter(w)
-	}
-	if !options.NoHeader {
-		for i, column := range columns {
-			if i > 0 {
-				fmt.Fprint(target, "\t")
-			}
-			fmt.Fprint(target, strings.ToUpper(column))
-		}
-		fmt.Fprintln(target)
-	}
-	for _, item := range items {
-		for i, column := range columns {
-			if i > 0 {
-				fmt.Fprint(target, "\t")
-			}
-			fmt.Fprint(target, cell(pathValue(item, column)))
-		}
-		fmt.Fprintln(target)
-	}
-	if table != nil {
-		return table.Flush()
-	}
-	if buffered, ok := target.(*bufio.Writer); ok {
-		return buffered.Flush()
-	}
-	return nil
-}
-
-func pathValue(item map[string]any, path string) any {
-	var value any = item
-	for _, segment := range strings.Split(path, ".") {
-		object, ok := value.(map[string]any)
-		if !ok {
-			return nil
-		}
-		value = object[segment]
-	}
-	return value
-}
-
-func cell(value any) string {
-	if value == nil {
-		return ""
-	}
-	switch typed := value.(type) {
-	case string:
-		return clean(typed)
-	case json.Number:
-		return typed.String()
-	case bool:
-		return fmt.Sprint(typed)
-	case []any:
-		values := make([]string, 0, len(typed))
-		for _, entry := range typed {
-			values = append(values, cell(entry))
-		}
-		return strings.Join(values, ",")
-	case map[string]any:
-		keys := make([]string, 0, len(typed))
-		for key := range typed {
-			keys = append(keys, key)
-		}
-		sort.Strings(keys)
-		values := make([]string, 0, len(keys))
-		for _, key := range keys {
-			values = append(values, key+"="+cell(typed[key]))
-		}
-		return strings.Join(values, ",")
-	default:
-		data, _ := json.Marshal(value)
-		return string(data)
-	}
-}
-
-func clean(value string) string {
-	return strings.NewReplacer("\t", " ", "\r", " ", "\n", " ").Replace(value)
-}
diff --git a/internal/output/output_test.go b/internal/output/output_test.go
deleted file mode 100644
index 71ea038..0000000
--- a/internal/output/output_test.go
+++ /dev/null
@@ -1,48 +0,0 @@
-package output
-
-import (
-	"bytes"
-	"encoding/json"
-	"strings"
-	"testing"
-
-	"open-yt-cli/internal/youtube"
-)
-
-func TestJSONPreservesLargeCounterString(t *testing.T) {
-	result := youtube.ListResult{Items: []map[string]any{{"id": "v", "statistics": map[string]any{"viewCount": "900719925474099312345"}}}, Requests: 1}
-	var buffer bytes.Buffer
-	if err := Render(&buffer, result, Options{Format: "json"}); err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(buffer.String(), `"viewCount": "900719925474099312345"`) {
-		t.Fatalf("counter was changed: %s", buffer.String())
-	}
-	var decoded youtube.ListResult
-	if err := json.Unmarshal(buffer.Bytes(), &decoded); err != nil {
-		t.Fatal(err)
-	}
-}
-
-func TestTSVColumnsAndSanitization(t *testing.T) {
-	result := youtube.ListResult{Items: []map[string]any{{"id": "v", "snippet": map[string]any{"title": "line one\nline two"}}}}
-	var buffer bytes.Buffer
-	if err := Render(&buffer, result, Options{Format: "tsv", Columns: []string{"id", "snippet.title"}}); err != nil {
-		t.Fatal(err)
-	}
-	want := "ID\tSNIPPET.TITLE\nv\tline one line two\n"
-	if buffer.String() != want {
-		t.Fatalf("TSV = %q, want %q", buffer.String(), want)
-	}
-}
-
-func TestJSONLEmitsOneItemPerLine(t *testing.T) {
-	result := youtube.ListResult{Items: []map[string]any{{"id": "a"}, {"id": "b"}}}
-	var buffer bytes.Buffer
-	if err := Render(&buffer, result, Options{Format: "jsonl"}); err != nil {
-		t.Fatal(err)
-	}
-	if lines := strings.Split(strings.TrimSpace(buffer.String()), "\n"); len(lines) != 2 {
-		t.Fatalf("JSONL lines = %d: %q", len(lines), buffer.String())
-	}
-}
diff --git a/internal/skill/install.go b/internal/skill/install.go
deleted file mode 100644
index 3e07eeb..0000000
--- a/internal/skill/install.go
+++ /dev/null
@@ -1,93 +0,0 @@
-// Package skill installs the bundled oytc agent skill.
-package skill
-
-import (
-	"fmt"
-	"io/fs"
-	"os"
-	"path/filepath"
-
-	skillbundle "open-yt-cli/skills/oytc"
-)
-
-var bundledFiles fs.FS = skillbundle.Files
-
-var files = []string{
-	"SKILL.md",
-	"references/commands.md",
-	"references/recipes.md",
-}
-
-// DefaultPath returns the conventional cross-agent skill destination.
-func DefaultPath() (string, error) {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return "", fmt.Errorf("find home directory: %w", err)
-	}
-	return filepath.Join(home, ".agents", "skills", "oytc"), nil
-}
-
-// Install atomically replaces target with the skill embedded in this binary.
-func Install(target string) error {
-	return installFS(bundledFiles, target)
-}
-
-func installFS(source fs.FS, target string) error {
-	parent := filepath.Dir(target)
-	if err := os.MkdirAll(parent, 0o755); err != nil {
-		return fmt.Errorf("create skills directory: %w", err)
-	}
-
-	stage, err := os.MkdirTemp(parent, ".oytc-install-*")
-	if err != nil {
-		return fmt.Errorf("stage skill installation: %w", err)
-	}
-	defer os.RemoveAll(stage)
-	if err := os.Chmod(stage, 0o755); err != nil {
-		return err
-	}
-
-	for _, name := range files {
-		content, err := fs.ReadFile(source, name)
-		if err != nil {
-			return fmt.Errorf("read bundled %s: %w", name, err)
-		}
-		destination := filepath.Join(stage, filepath.FromSlash(name))
-		if err := os.MkdirAll(filepath.Dir(destination), 0o755); err != nil {
-			return fmt.Errorf("create skill references directory: %w", err)
-		}
-		if err := os.WriteFile(destination, content, 0o644); err != nil {
-			return fmt.Errorf("write %s: %w", name, err)
-		}
-	}
-
-	backup := ""
-	if _, err := os.Lstat(target); err == nil {
-		backupDir, err := os.MkdirTemp(parent, ".oytc-backup-*")
-		if err != nil {
-			return fmt.Errorf("prepare existing skill backup: %w", err)
-		}
-		if err := os.Remove(backupDir); err != nil {
-			return err
-		}
-		backup = backupDir
-		if err := os.Rename(target, backup); err != nil {
-			return fmt.Errorf("move existing skill aside: %w", err)
-		}
-	} else if !os.IsNotExist(err) {
-		return fmt.Errorf("inspect existing skill: %w", err)
-	}
-
-	if err := os.Rename(stage, target); err != nil {
-		if backup != "" {
-			_ = os.Rename(backup, target)
-		}
-		return fmt.Errorf("install skill: %w", err)
-	}
-	if backup != "" {
-		if err := os.RemoveAll(backup); err != nil {
-			return fmt.Errorf("remove replaced skill: %w", err)
-		}
-	}
-	return nil
-}
diff --git a/internal/skill/install_test.go b/internal/skill/install_test.go
deleted file mode 100644
index 545e8e0..0000000
--- a/internal/skill/install_test.go
+++ /dev/null
@@ -1,68 +0,0 @@
-package skill
-
-import (
-	"io/fs"
-	"os"
-	"path/filepath"
-	"testing"
-	"testing/fstest"
-)
-
-func TestInstallFSWritesAndReplacesCompleteSkill(t *testing.T) {
-	target := filepath.Join(t.TempDir(), ".agents", "skills", "oytc")
-	source := fstest.MapFS{
-		"SKILL.md":               {Data: []byte("updated skill")},
-		"references/commands.md": {Data: []byte("commands")},
-		"references/recipes.md":  {Data: []byte("recipes")},
-	}
-
-	if err := os.MkdirAll(target, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(target, "stale.md"), []byte("stale"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	if err := installFS(source, target); err != nil {
-		t.Fatal(err)
-	}
-
-	for name, want := range map[string]string{
-		"SKILL.md":               "updated skill",
-		"references/commands.md": "commands",
-		"references/recipes.md":  "recipes",
-	} {
-		got, err := os.ReadFile(filepath.Join(target, filepath.FromSlash(name)))
-		if err != nil {
-			t.Fatalf("read %s: %v", name, err)
-		}
-		if string(got) != want {
-			t.Fatalf("%s = %q, want %q", name, got, want)
-		}
-	}
-	if _, err := os.Stat(filepath.Join(target, "stale.md")); !os.IsNotExist(err) {
-		t.Fatalf("stale file survived replacement: %v", err)
-	}
-	entries, err := filepath.Glob(filepath.Join(filepath.Dir(target), ".oytc-*-*"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(entries) != 0 {
-		t.Fatalf("temporary files left behind: %v", entries)
-	}
-}
-
-func TestBundledSkillIsComplete(t *testing.T) {
-	for _, name := range files {
-		info, err := fs.Stat(skillbundleFS(), name)
-		if err != nil {
-			t.Fatalf("bundled %s: %v", name, err)
-		}
-		if info.Size() == 0 {
-			t.Fatalf("bundled %s is empty", name)
-		}
-	}
-}
-
-func skillbundleFS() fs.FS {
-	return bundledFiles
-}
diff --git a/internal/update/update.go b/internal/update/update.go
deleted file mode 100644
index b1d783f..0000000
--- a/internal/update/update.go
+++ /dev/null
@@ -1,580 +0,0 @@
-// Package update implements secure self-updating from GitHub Releases.
-//
-// The updater resolves a release, downloads the platform archive and the
-// release's checksums.txt, verifies the archive's SHA-256, extracts the
-// binary with path-traversal protection, and atomically replaces the
-// current executable. It never reads, needs, or transmits the YouTube API
-// key: the only network traffic is unauthenticated GitHub release metadata
-// and asset downloads.
-package update
-
-import (
-	"archive/tar"
-	"archive/zip"
-	"compress/gzip"
-	"context"
-	"crypto/sha256"
-	"encoding/hex"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"net/http"
-	"os"
-	"path"
-	"path/filepath"
-	"runtime"
-	"strconv"
-	"strings"
-	"time"
-)
-
-var (
-	defaultGOOS   = runtime.GOOS
-	defaultGOARCH = runtime.GOARCH
-)
-
-// DefaultRepo is the canonical GitHub repository for oytc releases.
-const DefaultRepo = "davis7dotsh/open-yt-cli"
-
-// DefaultAPIBaseURL is the GitHub REST API endpoint.
-const DefaultAPIBaseURL = "https://api.github.com"
-
-const (
-	maxMetadataBytes = 4 << 20   // release JSON
-	maxChecksumBytes = 1 << 20   // checksums.txt
-	maxArchiveBytes  = 256 << 20 // release archive
-)
-
-// Updater performs a self-update. Every external dependency is injectable
-// so behavior is fully testable with httptest servers and temp dirs.
-type Updater struct {
-	Repo           string
-	APIBaseURL     string
-	HTTPClient     *http.Client
-	CurrentVersion string
-	GOOS           string
-	GOARCH         string
-	// ExecutablePath overrides os.Executable for tests.
-	ExecutablePath string
-}
-
-// Options control a single update run.
-type Options struct {
-	// TargetVersion is an explicit release tag such as "v1.2.0". Empty
-	// means the latest non-prerelease release. Explicitly requesting a
-	// tag permits installing that exact version even if it is older.
-	TargetVersion string
-	// CheckOnly reports the available version without changing anything.
-	CheckOnly bool
-}
-
-// Release is the subset of the GitHub release payload the updater needs.
-type Release struct {
-	TagName    string  `json:"tag_name"`
-	Prerelease bool    `json:"prerelease"`
-	Assets     []Asset `json:"assets"`
-}
-
-// Asset is a single downloadable release artifact.
-type Asset struct {
-	Name               string `json:"name"`
-	BrowserDownloadURL string `json:"browser_download_url"`
-}
-
-// Result describes what an update run concluded or performed.
-type Result struct {
-	CurrentVersion string `json:"currentVersion"`
-	TargetVersion  string `json:"targetVersion"`
-	Updated        bool   `json:"updated"`
-	UpToDate       bool   `json:"upToDate"`
-	AssetName      string `json:"assetName,omitempty"`
-	ExecutablePath string `json:"executablePath,omitempty"`
-}
-
-// AssetName returns the release asset filename for a tag and platform,
-// e.g. "oytc_v0.1.0_linux_amd64.tar.gz". This naming is shared verbatim by
-// the release workflow, the installer script, and the website.
-func AssetName(tag, goos, goarch string) string {
-	ext := "tar.gz"
-	if goos == "windows" {
-		ext = "zip"
-	}
-	return fmt.Sprintf("oytc_%s_%s_%s.%s", tag, goos, goarch, ext)
-}
-
-// ChecksumsName is the release checksum manifest filename.
-const ChecksumsName = "checksums.txt"
-
-// Run executes the update (or check) and returns what happened.
-func (u *Updater) Run(ctx context.Context, options Options) (Result, error) {
-	result := Result{CurrentVersion: u.CurrentVersion}
-	executable, err := u.executable()
-	if err != nil {
-		return result, err
-	}
-	result.ExecutablePath = executable
-	if err := guardManagedInstall(executable); err != nil {
-		return result, err
-	}
-
-	release, err := u.resolveRelease(ctx, options.TargetVersion)
-	if err != nil {
-		return result, err
-	}
-	result.TargetVersion = release.TagName
-	result.AssetName = AssetName(release.TagName, u.goos(), u.goarch())
-
-	comparison, comparable := CompareVersions(release.TagName, u.CurrentVersion)
-	if comparable && comparison == 0 {
-		result.UpToDate = true
-		return result, nil
-	}
-	if comparable && comparison < 0 && options.TargetVersion == "" {
-		return result, fmt.Errorf("latest release %s is older than the current version %s; refusing to downgrade (pass an explicit version to override)", release.TagName, u.CurrentVersion)
-	}
-	if options.CheckOnly {
-		return result, nil
-	}
-
-	if err := checkWritable(executable); err != nil {
-		return result, err
-	}
-
-	assetURL, checksumsURL, err := findAssets(release, result.AssetName)
-	if err != nil {
-		return result, err
-	}
-	expected, err := u.fetchChecksum(ctx, checksumsURL, result.AssetName)
-	if err != nil {
-		return result, err
-	}
-	archive, err := u.downloadVerified(ctx, assetURL, expected)
-	if err != nil {
-		return result, err
-	}
-	defer os.Remove(archive)
-
-	binary, err := extractBinary(archive, u.goos())
-	if err != nil {
-		return result, err
-	}
-	if err := replaceExecutable(binary, executable, u.goos()); err != nil {
-		return result, err
-	}
-	result.Updated = true
-	return result, nil
-}
-
-func (u *Updater) executable() (string, error) {
-	if u.ExecutablePath != "" {
-		return u.ExecutablePath, nil
-	}
-	executable, err := os.Executable()
-	if err != nil {
-		return "", fmt.Errorf("locate current executable: %w", err)
-	}
-	resolved, err := filepath.EvalSymlinks(executable)
-	if err != nil {
-		return executable, nil
-	}
-	return resolved, nil
-}
-
-func (u *Updater) goos() string {
-	if u.GOOS != "" {
-		return u.GOOS
-	}
-	return defaultGOOS
-}
-
-func (u *Updater) goarch() string {
-	if u.GOARCH != "" {
-		return u.GOARCH
-	}
-	return defaultGOARCH
-}
-
-func (u *Updater) httpClient() *http.Client {
-	if u.HTTPClient != nil {
-		return u.HTTPClient
-	}
-	return &http.Client{Timeout: 5 * time.Minute}
-}
-
-func (u *Updater) apiBaseURL() string {
-	if u.APIBaseURL != "" {
-		return strings.TrimRight(u.APIBaseURL, "/")
-	}
-	return DefaultAPIBaseURL
-}
-
-func (u *Updater) repo() string {
-	if u.Repo != "" {
-		return u.Repo
-	}
-	return DefaultRepo
-}
-
-func (u *Updater) resolveRelease(ctx context.Context, tag string) (Release, error) {
-	endpoint := u.apiBaseURL() + "/repos/" + u.repo() + "/releases/latest"
-	if tag != "" {
-		if !strings.HasPrefix(tag, "v") {
-			tag = "v" + tag
-		}
-		endpoint = u.apiBaseURL() + "/repos/" + u.repo() + "/releases/tags/" + tag
-	}
-	body, err := u.get(ctx, endpoint, maxMetadataBytes, "application/vnd.github+json")
-	if err != nil {
-		return Release{}, fmt.Errorf("resolve release: %w", err)
-	}
-	var release Release
-	if err := json.Unmarshal(body, &release); err != nil {
-		return Release{}, fmt.Errorf("parse release metadata: %w", err)
-	}
-	if release.TagName == "" {
-		return Release{}, errors.New("release metadata is missing a tag name")
-	}
-	return release, nil
-}
-
-func (u *Updater) get(ctx context.Context, url string, limit int64, accept string) ([]byte, error) {
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
-	if err != nil {
-		return nil, err
-	}
-	if accept != "" {
-		req.Header.Set("Accept", accept)
-	}
-	req.Header.Set("User-Agent", "oytc-updater/"+u.CurrentVersion)
-	resp, err := u.httpClient().Do(req)
-	if err != nil {
-		return nil, err
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode == http.StatusNotFound {
-		return nil, fmt.Errorf("GET %s: not found (has a release been published?)", url)
-	}
-	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("GET %s: unexpected status %d", url, resp.StatusCode)
-	}
-	body, err := io.ReadAll(io.LimitReader(resp.Body, limit+1))
-	if err != nil {
-		return nil, err
-	}
-	if int64(len(body)) > limit {
-		return nil, fmt.Errorf("GET %s: response exceeds %d bytes", url, limit)
-	}
-	return body, nil
-}
-
-func findAssets(release Release, assetName string) (assetURL, checksumsURL string, err error) {
-	for _, asset := range release.Assets {
-		switch asset.Name {
-		case assetName:
-			assetURL = asset.BrowserDownloadURL
-		case ChecksumsName:
-			checksumsURL = asset.BrowserDownloadURL
-		}
-	}
-	if assetURL == "" {
-		return "", "", fmt.Errorf("release %s has no asset %q for this platform", release.TagName, assetName)
-	}
-	if checksumsURL == "" {
-		return "", "", fmt.Errorf("release %s has no %s asset; refusing to install an unverifiable binary", release.TagName, ChecksumsName)
-	}
-	return assetURL, checksumsURL, nil
-}
-
-func (u *Updater) fetchChecksum(ctx context.Context, url, assetName string) (string, error) {
-	body, err := u.get(ctx, url, maxChecksumBytes, "")
-	if err != nil {
-		return "", fmt.Errorf("download %s: %w", ChecksumsName, err)
-	}
-	checksum, err := ParseChecksums(body, assetName)
-	if err != nil {
-		return "", err
-	}
-	return checksum, nil
-}
-
-// ParseChecksums extracts the SHA-256 hex digest for name from a
-// sha256sum-format manifest ("  " per line).
-func ParseChecksums(manifest []byte, name string) (string, error) {
-	for _, line := range strings.Split(string(manifest), "\n") {
-		fields := strings.Fields(strings.TrimSpace(line))
-		if len(fields) != 2 {
-			continue
-		}
-		if strings.TrimPrefix(fields[1], "*") == name {
-			digest := strings.ToLower(fields[0])
-			if len(digest) != sha256.Size*2 {
-				return "", fmt.Errorf("%s contains a malformed digest for %q", ChecksumsName, name)
-			}
-			if _, err := hex.DecodeString(digest); err != nil {
-				return "", fmt.Errorf("%s contains a malformed digest for %q", ChecksumsName, name)
-			}
-			return digest, nil
-		}
-	}
-	return "", fmt.Errorf("%s has no entry for %q", ChecksumsName, name)
-}
-
-func (u *Updater) downloadVerified(ctx context.Context, url, expected string) (string, error) {
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
-	if err != nil {
-		return "", err
-	}
-	req.Header.Set("User-Agent", "oytc-updater/"+u.CurrentVersion)
-	resp, err := u.httpClient().Do(req)
-	if err != nil {
-		return "", fmt.Errorf("download release archive: %w", err)
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("download release archive: unexpected status %d", resp.StatusCode)
-	}
-	tmp, err := os.CreateTemp("", "oytc-update-*.archive")
-	if err != nil {
-		return "", err
-	}
-	tmpName := tmp.Name()
-	hasher := sha256.New()
-	_, copyErr := io.Copy(io.MultiWriter(tmp, hasher), io.LimitReader(resp.Body, maxArchiveBytes))
-	closeErr := tmp.Close()
-	if copyErr != nil || closeErr != nil {
-		os.Remove(tmpName)
-		return "", fmt.Errorf("save release archive: %w", errors.Join(copyErr, closeErr))
-	}
-	actual := hex.EncodeToString(hasher.Sum(nil))
-	if actual != expected {
-		os.Remove(tmpName)
-		return "", fmt.Errorf("checksum mismatch for downloaded archive: expected %s, got %s; refusing to install", expected, actual)
-	}
-	return tmpName, nil
-}
-
-// extractBinary pulls the oytc binary out of a verified archive. Only an
-// entry whose cleaned path is exactly the expected binary name is accepted,
-// which also defeats path traversal (../, absolute paths, nested paths).
-func extractBinary(archivePath, goos string) (string, error) {
-	want := "oytc"
-	if goos == "windows" {
-		want = "oytc.exe"
-	}
-	if strings.HasSuffix(archivePath, ".zip") || goos == "windows" {
-		return extractFromZip(archivePath, want)
-	}
-	return extractFromTarGz(archivePath, want)
-}
-
-func safeEntryMatch(name, want string) bool {
-	cleaned := path.Clean(strings.ReplaceAll(name, `\`, "/"))
-	return cleaned == want
-}
-
-func extractFromTarGz(archivePath, want string) (string, error) {
-	file, err := os.Open(archivePath)
-	if err != nil {
-		return "", err
-	}
-	defer file.Close()
-	gz, err := gzip.NewReader(file)
-	if err != nil {
-		return "", fmt.Errorf("open release archive: %w", err)
-	}
-	defer gz.Close()
-	reader := tar.NewReader(gz)
-	for {
-		header, err := reader.Next()
-		if errors.Is(err, io.EOF) {
-			break
-		}
-		if err != nil {
-			return "", fmt.Errorf("read release archive: %w", err)
-		}
-		if header.Typeflag != tar.TypeReg || !safeEntryMatch(header.Name, want) {
-			continue
-		}
-		return writeBinaryTemp(reader, want)
-	}
-	return "", fmt.Errorf("release archive does not contain %q", want)
-}
-
-func extractFromZip(archivePath, want string) (string, error) {
-	reader, err := zip.OpenReader(archivePath)
-	if err != nil {
-		return "", fmt.Errorf("open release archive: %w", err)
-	}
-	defer reader.Close()
-	for _, entry := range reader.File {
-		if entry.FileInfo().IsDir() || !safeEntryMatch(entry.Name, want) {
-			continue
-		}
-		content, err := entry.Open()
-		if err != nil {
-			return "", err
-		}
-		defer content.Close()
-		return writeBinaryTemp(content, want)
-	}
-	return "", fmt.Errorf("release archive does not contain %q", want)
-}
-
-func writeBinaryTemp(content io.Reader, want string) (string, error) {
-	tmp, err := os.CreateTemp("", "oytc-binary-*")
-	if err != nil {
-		return "", err
-	}
-	tmpName := tmp.Name()
-	_, copyErr := io.Copy(tmp, io.LimitReader(content, maxArchiveBytes))
-	closeErr := tmp.Close()
-	if copyErr != nil || closeErr != nil {
-		os.Remove(tmpName)
-		return "", fmt.Errorf("extract %s: %w", want, errors.Join(copyErr, closeErr))
-	}
-	if err := os.Chmod(tmpName, 0o755); err != nil {
-		os.Remove(tmpName)
-		return "", err
-	}
-	return tmpName, nil
-}
-
-// replaceExecutable atomically swaps the new binary into place. The staged
-// copy lives in the same directory as the target so the final rename is
-// atomic on POSIX filesystems. On Windows a running executable cannot be
-// overwritten, but it can be renamed: the current binary is moved aside to
-// ".old" first.
-func replaceExecutable(newBinary, executable, goos string) error {
-	defer os.Remove(newBinary)
-	dir := filepath.Dir(executable)
-	staged, err := os.CreateTemp(dir, ".oytc-new-*")
-	if err != nil {
-		return installPermissionError(executable, err)
-	}
-	stagedName := staged.Name()
-	source, err := os.Open(newBinary)
-	if err != nil {
-		staged.Close()
-		os.Remove(stagedName)
-		return err
-	}
-	_, copyErr := io.Copy(staged, source)
-	source.Close()
-	closeErr := staged.Close()
-	if copyErr != nil || closeErr != nil {
-		os.Remove(stagedName)
-		return fmt.Errorf("stage new binary: %w", errors.Join(copyErr, closeErr))
-	}
-	if err := os.Chmod(stagedName, 0o755); err != nil {
-		os.Remove(stagedName)
-		return err
-	}
-	if goos == "windows" {
-		old := executable + ".old"
-		_ = os.Remove(old)
-		if err := os.Rename(executable, old); err != nil {
-			os.Remove(stagedName)
-			return fmt.Errorf("move the running executable aside (%w); on Windows, download the new release manually from https://github.com/%s/releases and replace %s", err, DefaultRepo, executable)
-		}
-		if err := os.Rename(stagedName, executable); err != nil {
-			_ = os.Rename(old, executable)
-			os.Remove(stagedName)
-			return installPermissionError(executable, err)
-		}
-		return nil
-	}
-	if err := os.Rename(stagedName, executable); err != nil {
-		os.Remove(stagedName)
-		return installPermissionError(executable, err)
-	}
-	return nil
-}
-
-func checkWritable(executable string) error {
-	dir := filepath.Dir(executable)
-	probe, err := os.CreateTemp(dir, ".oytc-write-probe-*")
-	if err != nil {
-		return installPermissionError(executable, err)
-	}
-	probe.Close()
-	os.Remove(probe.Name())
-	return nil
-}
-
-func installPermissionError(executable string, err error) error {
-	if errors.Is(err, os.ErrPermission) {
-		return fmt.Errorf("no permission to replace %s: %w\nRe-run the update with sufficient privileges, or reinstall to a user-writable location with the install script (https://davis7dotsh.github.io/open-yt-cli/install.sh)", executable, err)
-	}
-	return err
-}
-
-func guardManagedInstall(executable string) error {
-	normalized := filepath.ToSlash(executable)
-	for _, marker := range []string{"/Cellar/", "/homebrew/", "/linuxbrew/"} {
-		if strings.Contains(normalized, marker) {
-			return fmt.Errorf("%s looks like a Homebrew-managed install; update it with your package manager instead of the self-updater", executable)
-		}
-	}
-	return nil
-}
-
-// CompareVersions compares two semantic version tags such as "v1.2.3" or
-// "1.2.3-rc.1". It returns (-1|0|1, true) when both parse, and (0, false)
-// when either does not (for example a "dev" build).
-func CompareVersions(a, b string) (int, bool) {
-	av, aok := parseVersion(a)
-	bv, bok := parseVersion(b)
-	if !aok || !bok {
-		return 0, false
-	}
-	for i := range 3 {
-		if av.nums[i] != bv.nums[i] {
-			if av.nums[i] < bv.nums[i] {
-				return -1, true
-			}
-			return 1, true
-		}
-	}
-	// A release version is greater than any of its prereleases.
-	switch {
-	case av.pre == bv.pre:
-		return 0, true
-	case av.pre == "":
-		return 1, true
-	case bv.pre == "":
-		return -1, true
-	case av.pre < bv.pre:
-		return -1, true
-	default:
-		return 1, true
-	}
-}
-
-type parsedVersion struct {
-	nums [3]int
-	pre  string
-}
-
-func parseVersion(tag string) (parsedVersion, bool) {
-	tag = strings.TrimPrefix(strings.TrimSpace(tag), "v")
-	if tag == "" {
-		return parsedVersion{}, false
-	}
-	core, pre, _ := strings.Cut(tag, "-")
-	core, _, _ = strings.Cut(core, "+")
-	parts := strings.Split(core, ".")
-	if len(parts) != 3 {
-		return parsedVersion{}, false
-	}
-	var parsed parsedVersion
-	parsed.pre = pre
-	for i, part := range parts {
-		number, err := strconv.Atoi(part)
-		if err != nil || number < 0 {
-			return parsedVersion{}, false
-		}
-		parsed.nums[i] = number
-	}
-	return parsed, true
-}
diff --git a/internal/update/update_test.go b/internal/update/update_test.go
deleted file mode 100644
index d3a92a1..0000000
--- a/internal/update/update_test.go
+++ /dev/null
@@ -1,349 +0,0 @@
-package update
-
-import (
-	"archive/tar"
-	"archive/zip"
-	"bytes"
-	"compress/gzip"
-	"context"
-	"crypto/sha256"
-	"encoding/hex"
-	"encoding/json"
-	"fmt"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-)
-
-func tarGzWithEntry(t *testing.T, entryName string, content []byte) []byte {
-	t.Helper()
-	var buf bytes.Buffer
-	gz := gzip.NewWriter(&buf)
-	tw := tar.NewWriter(gz)
-	if err := tw.WriteHeader(&tar.Header{Name: entryName, Mode: 0o755, Size: int64(len(content)), Typeflag: tar.TypeReg}); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := tw.Write(content); err != nil {
-		t.Fatal(err)
-	}
-	if err := tw.Close(); err != nil {
-		t.Fatal(err)
-	}
-	if err := gz.Close(); err != nil {
-		t.Fatal(err)
-	}
-	return buf.Bytes()
-}
-
-func zipWithEntry(t *testing.T, entryName string, content []byte) []byte {
-	t.Helper()
-	var buf bytes.Buffer
-	zw := zip.NewWriter(&buf)
-	writer, err := zw.Create(entryName)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := writer.Write(content); err != nil {
-		t.Fatal(err)
-	}
-	if err := zw.Close(); err != nil {
-		t.Fatal(err)
-	}
-	return buf.Bytes()
-}
-
-type fixture struct {
-	updater    *Updater
-	executable string
-	archive    []byte
-	checksums  string
-	assetName  string
-}
-
-func newFixture(t *testing.T, tag, goos, goarch, currentVersion string, binaryContent []byte) *fixture {
-	t.Helper()
-	entry := "oytc"
-	if goos == "windows" {
-		entry = "oytc.exe"
-	}
-	var archive []byte
-	if goos == "windows" {
-		archive = zipWithEntry(t, entry, binaryContent)
-	} else {
-		archive = tarGzWithEntry(t, entry, binaryContent)
-	}
-	assetName := AssetName(tag, goos, goarch)
-	sum := sha256.Sum256(archive)
-	checksums := fmt.Sprintf("%s  %s\n", hex.EncodeToString(sum[:]), assetName)
-
-	dir := t.TempDir()
-	executable := filepath.Join(dir, "oytc")
-	if err := os.WriteFile(executable, []byte("old-binary"), 0o755); err != nil {
-		t.Fatal(err)
-	}
-
-	f := &fixture{executable: executable, archive: archive, checksums: checksums, assetName: assetName}
-	mux := http.NewServeMux()
-	var server *httptest.Server
-	release := func() Release {
-		return Release{
-			TagName: tag,
-			Assets: []Asset{
-				{Name: assetName, BrowserDownloadURL: server.URL + "/assets/" + assetName},
-				{Name: ChecksumsName, BrowserDownloadURL: server.URL + "/assets/" + ChecksumsName},
-			},
-		}
-	}
-	mux.HandleFunc("/repos/owner/repo/releases/latest", func(w http.ResponseWriter, _ *http.Request) {
-		_ = json.NewEncoder(w).Encode(release())
-	})
-	mux.HandleFunc("/repos/owner/repo/releases/tags/", func(w http.ResponseWriter, r *http.Request) {
-		requested := strings.TrimPrefix(r.URL.Path, "/repos/owner/repo/releases/tags/")
-		if requested != tag {
-			http.NotFound(w, r)
-			return
-		}
-		_ = json.NewEncoder(w).Encode(release())
-	})
-	mux.HandleFunc("/assets/", func(w http.ResponseWriter, r *http.Request) {
-		switch strings.TrimPrefix(r.URL.Path, "/assets/") {
-		case f.assetName:
-			_, _ = w.Write(f.archive)
-		case ChecksumsName:
-			_, _ = w.Write([]byte(f.checksums))
-		default:
-			http.NotFound(w, r)
-		}
-	})
-	server = httptest.NewServer(mux)
-	t.Cleanup(server.Close)
-
-	f.updater = &Updater{
-		Repo:           "owner/repo",
-		APIBaseURL:     server.URL,
-		HTTPClient:     server.Client(),
-		CurrentVersion: currentVersion,
-		GOOS:           goos,
-		GOARCH:         goarch,
-		ExecutablePath: executable,
-	}
-	return f
-}
-
-func TestUpdateDownloadsVerifiesAndReplaces(t *testing.T) {
-	binary := []byte("new-binary-content")
-	f := newFixture(t, "v0.2.0", "linux", "amd64", "v0.1.0", binary)
-	result, err := f.updater.Run(context.Background(), Options{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !result.Updated || result.TargetVersion != "v0.2.0" {
-		t.Fatalf("result = %#v", result)
-	}
-	installed, err := os.ReadFile(f.executable)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !bytes.Equal(installed, binary) {
-		t.Fatalf("installed binary = %q", installed)
-	}
-	info, err := os.Stat(f.executable)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if info.Mode().Perm()&0o111 == 0 {
-		t.Fatalf("installed binary is not executable: %v", info.Mode())
-	}
-}
-
-func TestUpdateRefusesChecksumMismatch(t *testing.T) {
-	f := newFixture(t, "v0.2.0", "linux", "amd64", "v0.1.0", []byte("payload"))
-	f.checksums = strings.Repeat("0", 64) + "  " + f.assetName + "\n"
-	_, err := f.updater.Run(context.Background(), Options{})
-	if err == nil || !strings.Contains(err.Error(), "checksum mismatch") {
-		t.Fatalf("err = %v", err)
-	}
-	original, _ := os.ReadFile(f.executable)
-	if string(original) != "old-binary" {
-		t.Fatalf("executable was modified on checksum failure")
-	}
-}
-
-func TestUpdateRefusesMissingChecksums(t *testing.T) {
-	f := newFixture(t, "v0.2.0", "linux", "amd64", "v0.1.0", []byte("payload"))
-	f.checksums = "deadbeef  something-else.tar.gz\n"
-	_, err := f.updater.Run(context.Background(), Options{})
-	if err == nil || !strings.Contains(err.Error(), "no entry") {
-		t.Fatalf("err = %v", err)
-	}
-}
-
-func TestUpdateAlreadyCurrent(t *testing.T) {
-	f := newFixture(t, "v0.2.0", "linux", "amd64", "v0.2.0", []byte("payload"))
-	result, err := f.updater.Run(context.Background(), Options{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !result.UpToDate || result.Updated {
-		t.Fatalf("result = %#v", result)
-	}
-	original, _ := os.ReadFile(f.executable)
-	if string(original) != "old-binary" {
-		t.Fatalf("executable modified for an up-to-date version")
-	}
-}
-
-func TestUpdateRefusesImplicitDowngrade(t *testing.T) {
-	f := newFixture(t, "v0.1.0", "linux", "amd64", "v0.2.0", []byte("payload"))
-	_, err := f.updater.Run(context.Background(), Options{})
-	if err == nil || !strings.Contains(err.Error(), "refusing to downgrade") {
-		t.Fatalf("err = %v", err)
-	}
-}
-
-func TestUpdateExplicitVersionAllowsPinnedInstall(t *testing.T) {
-	binary := []byte("pinned")
-	f := newFixture(t, "v0.1.5", "linux", "amd64", "v0.2.0", binary)
-	result, err := f.updater.Run(context.Background(), Options{TargetVersion: "v0.1.5"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !result.Updated {
-		t.Fatalf("result = %#v", result)
-	}
-	installed, _ := os.ReadFile(f.executable)
-	if !bytes.Equal(installed, binary) {
-		t.Fatalf("installed = %q", installed)
-	}
-}
-
-func TestUpdateCheckOnlyDoesNotModify(t *testing.T) {
-	f := newFixture(t, "v0.3.0", "linux", "amd64", "v0.1.0", []byte("payload"))
-	result, err := f.updater.Run(context.Background(), Options{CheckOnly: true})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if result.Updated || result.UpToDate || result.TargetVersion != "v0.3.0" {
-		t.Fatalf("result = %#v", result)
-	}
-	original, _ := os.ReadFile(f.executable)
-	if string(original) != "old-binary" {
-		t.Fatalf("check-only modified the executable")
-	}
-}
-
-func TestUpdateWindowsZipAndRenameAside(t *testing.T) {
-	binary := []byte("windows-binary")
-	f := newFixture(t, "v0.2.0", "windows", "amd64", "v0.1.0", binary)
-	result, err := f.updater.Run(context.Background(), Options{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !result.Updated {
-		t.Fatalf("result = %#v", result)
-	}
-	installed, _ := os.ReadFile(f.executable)
-	if !bytes.Equal(installed, binary) {
-		t.Fatalf("installed = %q", installed)
-	}
-	old, err := os.ReadFile(f.executable + ".old")
-	if err != nil || string(old) != "old-binary" {
-		t.Fatalf("previous binary not preserved aside: %v", err)
-	}
-}
-
-func TestExtractRejectsPathTraversal(t *testing.T) {
-	for _, entry := range []string{"../oytc", "/oytc", "nested/oytc", "..\\oytc"} {
-		archive := tarGzWithEntry(t, entry, []byte("evil"))
-		tmp := filepath.Join(t.TempDir(), "a.tar.gz")
-		if err := os.WriteFile(tmp, archive, 0o644); err != nil {
-			t.Fatal(err)
-		}
-		if _, err := extractFromTarGz(tmp, "oytc"); err == nil || !strings.Contains(err.Error(), "does not contain") {
-			t.Fatalf("entry %q: err = %v", entry, err)
-		}
-	}
-}
-
-func TestUpdateRefusesHomebrewInstall(t *testing.T) {
-	f := newFixture(t, "v0.2.0", "linux", "amd64", "v0.1.0", []byte("payload"))
-	f.updater.ExecutablePath = "/opt/homebrew/Cellar/oytc/0.1.0/bin/oytc"
-	_, err := f.updater.Run(context.Background(), Options{})
-	if err == nil || !strings.Contains(err.Error(), "Homebrew") {
-		t.Fatalf("err = %v", err)
-	}
-}
-
-func TestUpdateMissingAssetForPlatform(t *testing.T) {
-	f := newFixture(t, "v0.2.0", "linux", "amd64", "v0.1.0", []byte("payload"))
-	f.updater.GOARCH = "riscv64"
-	_, err := f.updater.Run(context.Background(), Options{})
-	if err == nil || !strings.Contains(err.Error(), "no asset") {
-		t.Fatalf("err = %v", err)
-	}
-}
-
-func TestParseChecksums(t *testing.T) {
-	digest := strings.Repeat("ab", 32)
-	manifest := []byte(fmt.Sprintf("%s  oytc_v1.0.0_linux_amd64.tar.gz\n%s *oytc_v1.0.0_darwin_arm64.tar.gz\n", digest, digest))
-	for _, name := range []string{"oytc_v1.0.0_linux_amd64.tar.gz", "oytc_v1.0.0_darwin_arm64.tar.gz"} {
-		got, err := ParseChecksums(manifest, name)
-		if err != nil || got != digest {
-			t.Fatalf("ParseChecksums(%q) = %q, %v", name, got, err)
-		}
-	}
-	if _, err := ParseChecksums(manifest, "missing.tar.gz"); err == nil {
-		t.Fatal("expected error for missing entry")
-	}
-	if _, err := ParseChecksums([]byte("nothex  oytc.tar.gz\n"), "oytc.tar.gz"); err == nil {
-		t.Fatal("expected error for malformed digest")
-	}
-}
-
-func TestCompareVersions(t *testing.T) {
-	tests := []struct {
-		a, b       string
-		want       int
-		comparable bool
-	}{
-		{"v1.2.3", "v1.2.3", 0, true},
-		{"v1.2.3", "1.2.3", 0, true},
-		{"v0.2.0", "v0.10.0", -1, true},
-		{"v2.0.0", "v1.9.9", 1, true},
-		{"v1.0.0-rc.1", "v1.0.0", -1, true},
-		{"v1.0.0", "v1.0.0-rc.1", 1, true},
-		{"v1.0.0-rc.1", "v1.0.0-rc.2", -1, true},
-		{"dev", "v1.0.0", 0, false},
-		{"v1.0.0", "unknown", 0, false},
-	}
-	for _, test := range tests {
-		got, ok := CompareVersions(test.a, test.b)
-		if got != test.want || ok != test.comparable {
-			t.Errorf("CompareVersions(%q, %q) = %d, %t; want %d, %t", test.a, test.b, got, ok, test.want, test.comparable)
-		}
-	}
-}
-
-func TestAssetName(t *testing.T) {
-	if got := AssetName("v0.1.0", "linux", "arm64"); got != "oytc_v0.1.0_linux_arm64.tar.gz" {
-		t.Fatalf("AssetName = %q", got)
-	}
-	if got := AssetName("v0.1.0", "windows", "amd64"); got != "oytc_v0.1.0_windows_amd64.zip" {
-		t.Fatalf("AssetName = %q", got)
-	}
-}
-
-func TestDevBuildStillUpdatesToLatest(t *testing.T) {
-	binary := []byte("release-binary")
-	f := newFixture(t, "v0.2.0", "linux", "amd64", "dev", binary)
-	result, err := f.updater.Run(context.Background(), Options{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !result.Updated {
-		t.Fatalf("result = %#v", result)
-	}
-}
diff --git a/internal/version/version.go b/internal/version/version.go
deleted file mode 100644
index abe0854..0000000
--- a/internal/version/version.go
+++ /dev/null
@@ -1,67 +0,0 @@
-// Package version exposes the build-time version metadata for oytc.
-//
-// Release builds inject these values with:
-//
-//	go build -ldflags "-X open-yt-cli/internal/version.Version=v1.2.3 \
-//	  -X open-yt-cli/internal/version.Commit=abc1234 \
-//	  -X open-yt-cli/internal/version.Date=2026-01-02T15:04:05Z"
-//
-// Builds without injection (go install, go run) fall back to Go module build
-// info where available and otherwise report "dev".
-package version
-
-import (
-	"runtime"
-	"runtime/debug"
-)
-
-var (
-	// Version is the semantic version of this build, with a leading "v"
-	// (for example "v0.1.0"), or "dev" for uninjected builds.
-	Version = "dev"
-	// Commit is the short or full git commit hash of this build.
-	Commit = "unknown"
-	// Date is the RFC 3339 UTC build timestamp.
-	Date = "unknown"
-)
-
-// Info is a stable, machine-readable description of the running binary.
-type Info struct {
-	Version   string `json:"version"`
-	Commit    string `json:"commit"`
-	Date      string `json:"date"`
-	GoVersion string `json:"goVersion"`
-	OS        string `json:"os"`
-	Arch      string `json:"arch"`
-}
-
-// Get resolves the effective build metadata, consulting module build info
-// when the linker did not inject values.
-func Get() Info {
-	info := Info{
-		Version:   Version,
-		Commit:    Commit,
-		Date:      Date,
-		GoVersion: runtime.Version(),
-		OS:        runtime.GOOS,
-		Arch:      runtime.GOARCH,
-	}
-	build, ok := debug.ReadBuildInfo()
-	if !ok {
-		return info
-	}
-	if info.Version == "dev" && build.Main.Version != "" && build.Main.Version != "(devel)" {
-		info.Version = build.Main.Version
-	}
-	if info.Commit == "unknown" {
-		for _, setting := range build.Settings {
-			if setting.Key == "vcs.revision" && setting.Value != "" {
-				info.Commit = setting.Value
-			}
-			if setting.Key == "vcs.time" && setting.Value != "" && info.Date == "unknown" {
-				info.Date = setting.Value
-			}
-		}
-	}
-	return info
-}
diff --git a/internal/version/version_test.go b/internal/version/version_test.go
deleted file mode 100644
index 8521cee..0000000
--- a/internal/version/version_test.go
+++ /dev/null
@@ -1,29 +0,0 @@
-package version
-
-import (
-	"runtime"
-	"testing"
-)
-
-func TestGetDefaults(t *testing.T) {
-	info := Get()
-	if info.Version == "" {
-		t.Fatal("version is empty")
-	}
-	if info.GoVersion != runtime.Version() {
-		t.Fatalf("goVersion = %q", info.GoVersion)
-	}
-	if info.OS != runtime.GOOS || info.Arch != runtime.GOARCH {
-		t.Fatalf("platform = %s/%s", info.OS, info.Arch)
-	}
-}
-
-func TestGetUsesInjectedValues(t *testing.T) {
-	oldVersion, oldCommit, oldDate := Version, Commit, Date
-	t.Cleanup(func() { Version, Commit, Date = oldVersion, oldCommit, oldDate })
-	Version, Commit, Date = "v9.9.9", "abcdef1", "2026-01-02T03:04:05Z"
-	info := Get()
-	if info.Version != "v9.9.9" || info.Commit != "abcdef1" || info.Date != "2026-01-02T03:04:05Z" {
-		t.Fatalf("info = %#v", info)
-	}
-}
diff --git a/internal/youtube/client.go b/internal/youtube/client.go
deleted file mode 100644
index b3946de..0000000
--- a/internal/youtube/client.go
+++ /dev/null
@@ -1,231 +0,0 @@
-// Package youtube provides a small read-only YouTube REST client.
-package youtube
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"math/rand/v2"
-	"net"
-	"net/http"
-	"net/url"
-	"strconv"
-	"strings"
-	"time"
-)
-
-const DefaultBaseURL = "https://www.googleapis.com/youtube/v3"
-
-type TokenSource func(context.Context, bool) (string, error)
-
-type Client struct {
-	BaseURL     string
-	APIKey      string
-	TokenSource TokenSource
-	HTTPClient  *http.Client
-	MaxRetries  int
-	Sleep       func(context.Context, time.Duration) error
-}
-
-type Response struct {
-	Items                 []map[string]any `json:"items"`
-	NextPageToken         string           `json:"nextPageToken,omitempty"`
-	PrevPageToken         string           `json:"prevPageToken,omitempty"`
-	PollingIntervalMillis int64            `json:"pollingIntervalMillis,omitempty"`
-	OfflineAt             string           `json:"offlineAt,omitempty"`
-	PageInfo              map[string]any   `json:"pageInfo,omitempty"`
-	Kind                  string           `json:"kind,omitempty"`
-	ETag                  string           `json:"etag,omitempty"`
-}
-
-type APIError struct {
-	HTTPStatus int
-	Code       int
-	Message    string
-	Reasons    []string
-}
-
-func (e *APIError) Error() string {
-	if len(e.Reasons) > 0 {
-		return fmt.Sprintf("YouTube API error (%d, %s): %s", e.Code, strings.Join(e.Reasons, ", "), e.Message)
-	}
-	return fmt.Sprintf("YouTube API error (%d): %s", e.Code, e.Message)
-}
-
-func NewClient(key string, timeout time.Duration) *Client {
-	return &Client{
-		BaseURL:    DefaultBaseURL,
-		APIKey:     key,
-		HTTPClient: &http.Client{Timeout: timeout},
-		MaxRetries: 3,
-		Sleep:      sleepContext,
-	}
-}
-
-func (c *Client) Get(ctx context.Context, resource string, params url.Values) (Response, error) {
-	var out Response
-	if err := c.GetJSON(ctx, resource, params, true, &out); err != nil {
-		return Response{}, err
-	}
-	return out, nil
-}
-
-func (c *Client) GetJSON(ctx context.Context, resource string, params url.Values, authenticate bool, out any) error {
-	base := strings.TrimRight(c.BaseURL, "/")
-	resource = strings.TrimLeft(resource, "/")
-	target := base + "/" + resource
-	if encoded := params.Encode(); encoded != "" {
-		target += "?" + encoded
-	}
-
-	transientAttempt := 0
-	authRetried := false
-	for {
-		req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil)
-		if err != nil {
-			return err
-		}
-		req.Header.Set("Accept", "application/json")
-		req.Header.Set("User-Agent", "oytc/0.1")
-		if authenticate {
-			switch {
-			case c.TokenSource != nil:
-				token, err := c.TokenSource(ctx, false)
-				if err != nil {
-					return err
-				}
-				if strings.TrimSpace(token) == "" {
-					return ErrMissingOAuth
-				}
-				req.Header.Set("Authorization", "Bearer "+token)
-			case strings.TrimSpace(c.APIKey) != "":
-				req.Header.Set("X-Goog-Api-Key", c.APIKey)
-			default:
-				return ErrMissingKey
-			}
-		}
-		resp, err := c.httpClient().Do(req)
-		if err != nil {
-			if !retryableTransport(err) || transientAttempt >= c.MaxRetries {
-				return fmt.Errorf("request YouTube API: %w", err)
-			}
-			if err := c.wait(ctx, backoff(transientAttempt, "")); err != nil {
-				return err
-			}
-			transientAttempt++
-			continue
-		}
-		body, readErr := io.ReadAll(io.LimitReader(resp.Body, 16<<20))
-		resp.Body.Close()
-		if readErr != nil {
-			return fmt.Errorf("read YouTube API response: %w", readErr)
-		}
-		if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-			if authenticate && c.TokenSource != nil && resp.StatusCode == http.StatusUnauthorized && !authRetried {
-				if _, err := c.TokenSource(ctx, true); err != nil {
-					return err
-				}
-				authRetried = true
-				continue
-			}
-			apiErr := parseAPIError(resp.StatusCode, body)
-			if isTransientStatus(resp.StatusCode) && transientAttempt < c.MaxRetries {
-				if err := c.wait(ctx, backoff(transientAttempt, resp.Header.Get("Retry-After"))); err != nil {
-					return err
-				}
-				transientAttempt++
-				continue
-			}
-			return apiErr
-		}
-		decoder := json.NewDecoder(strings.NewReader(string(body)))
-		decoder.UseNumber()
-		if err := decoder.Decode(out); err != nil {
-			return fmt.Errorf("decode YouTube API response: %w", err)
-		}
-		return nil
-	}
-}
-
-var (
-	ErrMissingKey   = errors.New("no API key configured; run 'oytc login' or set OYTC_API_KEY")
-	ErrMissingOAuth = errors.New("no OAuth credentials configured; run 'oytc login --oauth'")
-)
-
-func parseAPIError(status int, body []byte) *APIError {
-	var envelope struct {
-		Error struct {
-			Code    int    `json:"code"`
-			Message string `json:"message"`
-			Errors  []struct {
-				Reason string `json:"reason"`
-			} `json:"errors"`
-			Details []struct {
-				Reason string `json:"reason"`
-			} `json:"details"`
-		} `json:"error"`
-	}
-	_ = json.Unmarshal(body, &envelope)
-	e := &APIError{HTTPStatus: status, Code: envelope.Error.Code, Message: envelope.Error.Message}
-	if e.Code == 0 {
-		e.Code = status
-	}
-	if e.Message == "" {
-		e.Message = http.StatusText(status)
-	}
-	for _, item := range envelope.Error.Errors {
-		if item.Reason != "" {
-			e.Reasons = append(e.Reasons, item.Reason)
-		}
-	}
-	for _, item := range envelope.Error.Details {
-		if item.Reason != "" {
-			e.Reasons = append(e.Reasons, item.Reason)
-		}
-	}
-	return e
-}
-
-func (c *Client) httpClient() *http.Client {
-	if c.HTTPClient != nil {
-		return c.HTTPClient
-	}
-	return &http.Client{Timeout: 20 * time.Second}
-}
-
-func (c *Client) wait(ctx context.Context, d time.Duration) error {
-	if c.Sleep != nil {
-		return c.Sleep(ctx, d)
-	}
-	return sleepContext(ctx, d)
-}
-
-func sleepContext(ctx context.Context, d time.Duration) error {
-	timer := time.NewTimer(d)
-	defer timer.Stop()
-	select {
-	case <-ctx.Done():
-		return ctx.Err()
-	case <-timer.C:
-		return nil
-	}
-}
-
-func retryableTransport(err error) bool {
-	var netErr net.Error
-	return errors.As(err, &netErr) || errors.Is(err, io.EOF)
-}
-
-func isTransientStatus(status int) bool {
-	return status == http.StatusTooManyRequests || status == 500 || status == 502 || status == 503 || status == 504
-}
-
-func backoff(attempt int, retryAfter string) time.Duration {
-	if seconds, err := strconv.Atoi(retryAfter); err == nil && seconds >= 0 {
-		return time.Duration(seconds) * time.Second
-	}
-	base := time.Duration(1< 0 {
-		params.Set("maxResults", fmt.Sprint(options.PageSize))
-	}
-	if options.PageToken != "" {
-		params.Set("pageToken", options.PageToken)
-	}
-	result := ListResult{Items: make([]map[string]any, 0)}
-	for {
-		response, err := c.Get(ctx, resource, params)
-		if err != nil {
-			return result, err
-		}
-		result.Requests++
-		items := response.Items
-		if options.Filter != nil {
-			filtered := make([]map[string]any, 0, len(items))
-			for _, item := range items {
-				if options.Filter(item) {
-					filtered = append(filtered, item)
-				}
-			}
-			items = filtered
-		}
-		if options.Limit > 0 && len(result.Items)+len(items) > options.Limit {
-			items = items[:options.Limit-len(result.Items)]
-		}
-		result.Items = append(result.Items, items...)
-		result.NextPageToken = response.NextPageToken
-		if !options.All || response.NextPageToken == "" || (options.Limit > 0 && len(result.Items) >= options.Limit) {
-			break
-		}
-		params.Set("pageToken", response.NextPageToken)
-	}
-	return result, nil
-}
-
-var channelIDPattern = regexp.MustCompile(`^UC[A-Za-z0-9_-]{22}$`)
-
-func (c *Client) ResolveChannel(ctx context.Context, reference string) (string, int, error) {
-	reference = strings.TrimSpace(reference)
-	if reference == "" {
-		return "", 0, errors.New("channel reference cannot be empty")
-	}
-	if channelIDPattern.MatchString(reference) {
-		return reference, 0, nil
-	}
-
-	kind, value := parseChannelReference(reference)
-	params := url.Values{"part": {"id"}}
-	switch kind {
-	case "id":
-		if !channelIDPattern.MatchString(value) {
-			return "", 0, fmt.Errorf("invalid channel ID %q", value)
-		}
-		return value, 0, nil
-	case "handle":
-		params.Set("forHandle", strings.TrimPrefix(value, "@"))
-	case "username":
-		params.Set("forUsername", value)
-	default:
-		search := url.Values{"part": {"snippet"}, "type": {"channel"}, "q": {value}, "maxResults": {"1"}}
-		response, err := c.Get(ctx, "search", search)
-		if err != nil {
-			return "", 1, err
-		}
-		if len(response.Items) == 0 {
-			return "", 1, fmt.Errorf("channel %q not found", reference)
-		}
-		id, _ := nestedString(response.Items[0], "id", "channelId")
-		if id == "" {
-			return "", 1, fmt.Errorf("channel %q not found", reference)
-		}
-		return id, 1, nil
-	}
-	response, err := c.Get(ctx, "channels", params)
-	if err != nil {
-		return "", 1, err
-	}
-	if len(response.Items) == 0 {
-		return "", 1, fmt.Errorf("channel %q not found", reference)
-	}
-	id, _ := response.Items[0]["id"].(string)
-	if id == "" {
-		return "", 1, fmt.Errorf("channel %q not found", reference)
-	}
-	return id, 1, nil
-}
-
-func parseChannelReference(reference string) (string, string) {
-	if strings.HasPrefix(reference, "@") {
-		return "handle", reference
-	}
-	candidate := reference
-	if !strings.Contains(candidate, "://") && (strings.Contains(candidate, "youtube.com/") || strings.Contains(candidate, "youtu.be/")) {
-		candidate = "https://" + candidate
-	}
-	if parsed, err := url.Parse(candidate); err == nil && parsed.Host != "" {
-		host := strings.ToLower(strings.TrimPrefix(parsed.Hostname(), "www."))
-		if host == "youtube.com" || host == "m.youtube.com" {
-			parts := strings.Split(strings.Trim(parsed.Path, "/"), "/")
-			if len(parts) > 0 && strings.HasPrefix(parts[0], "@") {
-				return "handle", parts[0]
-			}
-			if len(parts) >= 2 {
-				switch parts[0] {
-				case "channel":
-					return "id", parts[1]
-				case "user":
-					return "username", parts[1]
-				case "c":
-					return "search", parts[1]
-				}
-			}
-		}
-	}
-	return "search", reference
-}
-
-func nestedString(value map[string]any, path ...string) (string, bool) {
-	var current any = value
-	for _, key := range path {
-		object, ok := current.(map[string]any)
-		if !ok {
-			return "", false
-		}
-		current, ok = object[key]
-		if !ok {
-			return "", false
-		}
-	}
-	result, ok := current.(string)
-	return result, ok
-}
diff --git a/skills/oytc/embed.go b/skills/oytc/embed.go
deleted file mode 100644
index 9995c6f..0000000
--- a/skills/oytc/embed.go
+++ /dev/null
@@ -1,8 +0,0 @@
-package skillbundle
-
-import "embed"
-
-// Files contains the complete oytc agent skill shipped with each release.
-//
-//go:embed SKILL.md references/*.md
-var Files embed.FS
diff --git a/src/impl/youtubeApi.test.ts b/src/impl/youtubeApi.test.ts
index 5952ba9..60aff71 100644
--- a/src/impl/youtubeApi.test.ts
+++ b/src/impl/youtubeApi.test.ts
@@ -25,7 +25,7 @@ import {
   type Params
 } from "../services/index.ts"
 import { makeHttpCore } from "./httpCore.ts"
-import { makeYouTubeApi } from "./youtubeApi.ts"
+import { MAX_PAGES, makeYouTubeApi } from "./youtubeApi.ts"
 
 // ---------------------------------------------------------------------------
 // Harness
@@ -489,3 +489,90 @@ test("composes with the real HttpCore over a stub fetch", async () => {
   )
   expect(urls.every((u) => !u.includes("k="))).toBe(true)
 })
+
+// ---------------------------------------------------------------------------
+// DEVIATIONS.md D3 — `--all` must terminate against a non-terminating server
+// ---------------------------------------------------------------------------
+
+describe("DEVIATIONS.md D3: --all termination guards", () => {
+  // Go trusted `nextPageToken` unconditionally, so a server repeating one token
+  // looped forever, accumulating every page in memory. A harness doing exactly
+  // this consumed ~59 GB of RSS before it was killed.
+  test("a repeated nextPageToken stops the loop instead of running forever", async () => {
+    const { exit, seen } = await runList(
+      [`{"items":[{"id":"a"}],"nextPageToken":"SAME"}`],
+      { all: true }
+    )
+    const result = okOf(exit)
+    // Page 1 is followed once ("SAME" is new), page 2 returns "SAME" again and
+    // is recognised as already-followed.
+    expect(seen.length).toBe(2)
+    expect(ids(result.items)).toEqual(["a", "a"])
+    // "" is the honest answer: there is no valid resume point.
+    expect(result.nextPageToken).toBe("")
+  })
+
+  test("a token repeated after several distinct pages also stops", async () => {
+    const { exit, seen } = await runList(
+      [
+        `{"items":[{"id":"a"}],"nextPageToken":"t1"}`,
+        `{"items":[{"id":"b"}],"nextPageToken":"t2"}`,
+        `{"items":[{"id":"c"}],"nextPageToken":"t1"}`
+      ],
+      { all: true }
+    )
+    const result = okOf(exit)
+    expect(seen.length).toBe(3)
+    expect(ids(result.items)).toEqual(["a", "b", "c"])
+    expect(result.nextPageToken).toBe("")
+  })
+
+  test("distinct tokens forever hit the request ceiling and fail loudly", async () => {
+    // The loop guard cannot catch a server that never repeats itself, so the
+    // MAX_PAGES backstop must. Each response carries a fresh token.
+    let n = 0
+    const layer = Layer.succeed(HttpCore, {
+      getJson: () => {
+        n++
+        return Effect.succeed(jsonBody(`{"items":[{"id":"i${n}"}],"nextPageToken":"t${n}"}`))
+      }
+    })
+    const program = Effect.gen(function* () {
+      const api = yield* makeYouTubeApi()
+      return yield* api.list("playlistItems", [], { ...defaultPageOptions, all: true })
+    })
+    const exit = await Effect.runPromise(program.pipe(Effect.provide(layer), Effect.exit))
+    const error = errOf(exit)
+    expect(error._tag).toBe("OperationalError")
+    expect(error.message).toContain("pagination did not terminate")
+    expect(error.message).toContain("--limit")
+    expect(n).toBe(MAX_PAGES)
+  })
+
+  test("the guards never fire on a well-behaved server", async () => {
+    const { exit, seen } = await runList(
+      [
+        `{"items":[{"id":"a"}],"nextPageToken":"t1"}`,
+        `{"items":[{"id":"b"}],"nextPageToken":"t2"}`,
+        `{"items":[{"id":"c"}]}`
+      ],
+      { all: true }
+    )
+    const result = okOf(exit)
+    expect(seen.length).toBe(3)
+    expect(ids(result.items)).toEqual(["a", "b", "c"])
+    expect(result.nextPageToken).toBe("")
+  })
+
+  test("--limit still wins over the guards", async () => {
+    // A repeating server plus a limit: the limit terminates first, so the
+    // guards are never consulted.
+    const { exit, seen } = await runList(
+      [`{"items":[{"id":"a"}],"nextPageToken":"SAME"}`],
+      { all: true, limit: 1 }
+    )
+    const result = okOf(exit)
+    expect(seen.length).toBe(1)
+    expect(ids(result.items)).toEqual(["a"])
+  })
+})
diff --git a/src/impl/youtubeApi.ts b/src/impl/youtubeApi.ts
index f3129b9..cf6283d 100644
--- a/src/impl/youtubeApi.ts
+++ b/src/impl/youtubeApi.ts
@@ -30,6 +30,16 @@ export interface YouTubeApiConfig {
 
 const decodeResponse = Schema.decodeUnknownResult(DataApiResponse)
 
+/**
+ * The `--all` request ceiling (DEVIATIONS.md D3).
+ *
+ * Deliberately far above any real result set: at the largest page size any
+ * endpoint accepts (2000, live chat) this allows 20,000,000 items, and every
+ * other endpoint caps at 50 or 100 per page. A legitimate `--all` cannot reach
+ * it, so hitting it means the server is not terminating.
+ */
+export const MAX_PAGES = 10_000
+
 /**
  * `params.Set(key, value)` — replaces every existing entry for `key` and, when
  * the key is new, appends. Position of an existing key is preserved, which is
@@ -76,6 +86,14 @@ export const makeYouTubeApi = (
      * that skipped the discarded items. Here a page from which items were
      * DISCARDED reports `""` instead. Evaluated per page, so a page trimmed to
      * exactly its own length is not truncated and keeps its token.
+     *
+     * DEVIATIONS.md D3: `--all` terminates only when the server returns an
+     * empty `nextPageToken`. Go trusted that unconditionally, so a server that
+     * repeats a token — a bug, a buggy proxy, or a hostile endpoint — makes the
+     * loop run forever, accumulating every page in memory with no ceiling. That
+     * is not theoretical: a test harness returning a constant token consumed
+     * ~59 GB of RSS before it was killed. Two bounds now apply, and neither can
+     * fire on a correct server.
      */
     const list = (
       resource: string,
@@ -92,6 +110,7 @@ export const makeYouTubeApi = (
         const kept: Array = []
         let requests = 0
         let nextPageToken = ""
+        const seenTokens = new Set()
 
         for (;;) {
           const response = yield* get(resource, current)
@@ -119,6 +138,33 @@ export const makeYouTubeApi = (
           ) {
             break
           }
+
+          // DEVIATIONS.md D3, guard 1: a token we have already followed can
+          // only ever return the same page again. Stop and report `""`, which
+          // correctly says "no valid resume point" rather than handing back a
+          // token that loops.
+          if (seenTokens.has(nextPageToken)) {
+            nextPageToken = ""
+            break
+          }
+          seenTokens.add(nextPageToken)
+
+          // DEVIATIONS.md D3, guard 2: a backstop for a server that emits
+          // distinct tokens forever, which the loop check cannot catch. At the
+          // largest page size any endpoint accepts (2000, live chat) this is
+          // 20M items; the real ceilings are far lower, so a legitimate `--all`
+          // cannot reach it.
+          if (requests >= MAX_PAGES) {
+            return yield* Effect.fail(
+              new OperationalError({
+                message:
+                  `pagination did not terminate after ${MAX_PAGES} requests ` +
+                  `(the server kept returning a nextPageToken); ` +
+                  `re-run with --limit to bound the result`
+              })
+            )
+          }
+
           current = setParam(current, "pageToken", nextPageToken)
         }