pi-free-catalog 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,10 +1,28 @@
 # Changelog
 
+## 0.1.3 — prepared for release
+
+- Removed the legacy non-English publishing guide and its package manifest entry. Replaced synthetic non-English test strings with English text plus emoji, preserving Unicode coverage. Added a source/fixture language regression check.
+- Rewrote the public English README for clarity and natural phrasing. Removed local documentation links that resolve incorrectly on npm/Pi catalog pages; added link and version-example regression tests.
+- Removed the Persian README and its live link/package inclusion; all non-English documentation has now been removed.
+- Hide only the free-provider prefix in the TUI footer using Pi's public custom-footer API and exported renderer; preserve provider identities, picker, statistics and warnings. Add `/free-footer compact|default` for footer-extension coexistence.
+- Two-way native/Pi thinking synchronization through `setThinkingLevel` and `thinking_level_select`. A later Pi change releases stale per-model overrides; exact toggle/effort equivalence only. Model switching preserves saved native preferences without feedback loops.
+- Fix Pi `off` serialization: omitted SDK `reasoning` now selects an advertised disabled mode instead of unintentionally preserving the provider default.
+- Explicit status for provider-default/unmapped future modes; no invented native settings or hidden models.
+- Serialize preference writes and drain them on session shutdown.
+- Regression tests include the real Pi AgentSession/event runner/SDK with mocked HTTP, plus the actual stock footer renderer. Live tests are reported separately.
+
+## 0.1.2 — 2026-10-17
+
+- Storage: the saved catalog state is now gzipped and compact instead of pretty-printed. On a real catalog this is ~27 MB → ~1.3 MB (about 95% smaller), cutting startup load time and the bytes rewritten on every refresh. `load()` accepts gzipped state and plain JSON, so pre-0.1.2 catalogs still load unchanged.
+- Fixed: `atomicJSON` wrote machine-read state with 2-space indentation, roughly doubling the file for no benefit. Indentation remains off for the catalog; user-facing exports (`/free-export`, `scripts/catalog.mjs`) stay readable plain JSON.
+- Tests: added a regression test asserting the saved state is gzip-magic, far smaller than pretty JSON, round-trips through `load()`, and that a legacy plain-JSON cache still loads.
+
 ## 0.1.1 — 2026-10-17
 
 - Public npm release of the unscoped package `pi-free-catalog` (MIT), superseding 0.1.0.
 - Fixed: `test/package.test.mjs` assumed `npm pack --json` returns an array. npm 12 returns an object keyed by package name, so the assertion threw. It now accepts both shapes, which means `prepublishOnly` verification passes on npm 11 and npm 12.
-- Docs: removed the false "has not been published / provisional name" statements from README.md, README-fa.md and PUBLISHING-fa.md; install instructions now reference the real published name and version.
+- Docs: removed the false "has not been published / provisional name" statements from the release documentation; install instructions now reference the real published name and version.
 - package.json: added `author`; host-provided peer packages now use the `"*"` range prescribed by Pi's `docs/packages.md`.
 
 ## 0.1.0 — 2026-10-17 — first published release

package/README.md

@@ -1,115 +1,181 @@
 # pi-free-catalog
 
-Live, auditable **anonymous Kilo + OpenCode Zen** model discovery for **Pi 1.3.x / Node >=22.19**. One Pi package, two separate providers: `free-kilo` and `free-zen`. This package is an independent integration, not an official service client. It is published on npm as [`pi-free-catalog`](https://www.npmjs.com/package/pi-free-catalog) under the MIT license, maintained by `aminmza`.
+Find free models from **Kilo** and **OpenCode Zen** in Pi, without keeping a model list up to date yourself.
 
-[فارسی](README-fa.md) · [Publishing instructions](PUBLISHING-fa.md)
+The package adds two providers, `free-kilo` and `free-zen`. It checks live catalogs and pricing information whenever Pi loads the extension, then makes the confirmed-free models available in the model picker. Models with missing or conflicting prices stay visible in the catalog report, but cannot be called as free.
 
-## Install locally
+No personal API key, account setup, or running OpenCode CLI is needed for the public endpoints used here. This is an independent community integration, not an official Kilo or OpenCode client. Upstream availability, quotas, and access policies still apply.
 
-Extract the source ZIP, keep its folder permanently, then:
+**Requirements:** Pi 1.3.x and Node.js 22.19 or later. Licensed under MIT; maintained by `aminmza`.
+
+## Get started
 
 ```bash
-pi install ./pi-free-catalog
+pi install npm:pi-free-catalog
 pi
 ```
 
-There is no build step and no third-party runtime dependency beyond Pi's peer packages. Do not `npm install -g` this as a standalone agent. Choose `free-kilo` or `free-zen` in Pi's model picker. You do not need a personal API key, login or OpenCode CLI process. Disable other extensions modifying these requests when diagnosing conflicts.
+Open Pi's model picker and choose a model from `free-kilo` or `free-zen`.
+
+For a reproducible install, specify the version:
+
+```bash
+pi install npm:pi-free-catalog@0.1.3
+```
 
-## Install from npm
+To try the published package for one run without saving it to your settings:
 
 ```bash
-pi install npm:pi-free-catalog@0.1.1
+pi -e npm:pi-free-catalog
 ```
 
-Pin the exact version for reproducibility. `pi -e npm:pi-free-catalog` loads the package for a single invocation without changing your settings.
+This is a Pi extension, not a standalone agent. Install it with `pi install`, rather than `npm install -g`.
+
+### Use a local copy
+
+For development, extract the release source ZIP and keep the extracted folder somewhere permanent:
+
+```bash
+pi install ./pi-free-catalog-0.1.3
+pi
+```
+
+Pi loads local packages from their original folder, so do not move or delete it while the package is installed. If you are replacing an npm installation, remove that installation first:
+
+```bash
+pi remove npm:pi-free-catalog
+```
+
+Avoid loading both copies at once. From the source folder, `pi -e .` is another way to test a local copy without saving a new package entry.
+
+## What appears in the catalog?
 
-## Non-negotiable: no silent omissions
+The goal is to keep the full picture visible, not just the models that happened to work in a test.
 
-- Fetches **all five sources on EVERY extension load**, before Pi startup model selection, even for noninteractive startup. No warm-up session or TTL shortcut skips startup retrieval.
-- Classifies **every live ID**, not just a static allowlist and never by a `free` name/suffix.
-- Kilo: explicit `isFree:true` is authoritative. Explicit positive monetary charges conflict with that flag and are reported/blocked. Zero cost with `isFree:false` is reported as conflict, not assumed free. Missing/dynamic costs with an explicit true flag are preserved as explicit-free evidence.
-- Zen: exact-ID join of the live catalog with live official OpenCode, models.dev and Pi model/price metadata. Checks input/output, cache and tiered charges. Missing prices are UNKNOWN, never silently zero. Conflicting fresh free/paid prices are visibly quarantined.
-- Metadata-free models absent from the live service, formerly-free models, uncertain IDs, deprecated IDs and retired IDs stay visible in `/free-catalog` and `/free-export`.
-- All currently live confirmed-free **chat** models are registered, including ones that lack tools, have unknown limits or previously failed inference. Failures are not reasons to hide them.
-- Native classifiers are registered separately (currently Zen `jev-1.13-free`, using Pi's TypeSafe System One classifier implementation). They are not disguised as chat models.
-- An unknown future operation/protocol is retained with an explicit transport-not-implemented notice. This is not a promise to support future, unknowable wire protocols or metadata schemas automatically.
+- Every live model ID is checked. The words `free` or `paid` in a model's name do not determine its classification.
+- All currently listed, confirmed-free chat models are registered, including models with unknown limits, limited tool support, or previous inference errors.
+- Models with uncertain or conflicting prices remain in `/free-catalog` and `/free-export`, with calls blocked until they can be verified.
+- Previously free, missing, deprecated, and retired models remain in the report and history. They do not quietly disappear from the evidence.
+- Native classifiers, such as Zen's `jev-1.13-free`, are registered separately rather than presented as chat models.
+- An unfamiliar operation or transport stays in the report with a clear unsupported notice. Being listed is not a promise that every future protocol is implemented.
 
-**No honest client can prove an unpriced model is free or discover a model the upstream never exposes.** Such cases remain visible as UNKNOWN, not automatically callable as free. An anonymous request cannot spend a personal key this extension never sends.
+### How free pricing is checked
 
-## Refresh, history and retirement
+For **Kilo**, the catalog's explicit `isFree: true` flag is the starting point. A positive charge conflicts with that flag and blocks the model. Zero prices alongside `isFree: false` are also treated as a conflict. Missing or dynamic prices are retained as evidence when the explicit free flag is present.
 
-Startup awaits bounded parallel source requests (12-second timeout per source, 16 MiB per body). Full raw JSON, exact IDs, metadata, source timestamps, classification and lifecycle history are saved under `<Pi agent directory>/free-catalog/catalog.json`. Normal location: `~/.pi/agent/free-catalog/`.
+For **Zen**, the live model list is joined by exact ID with official OpenCode metadata, models.dev, and Pi's model metadata. The check includes input, output, cache, and tiered charges. Missing prices are unknown, not assumed to be zero; conflicting prices are reported and blocked.
 
-After five minutes, the next agent turn/request revalidates. `/free-refresh` explicitly fetches everything immediately. No permanent background timer. History retains every seen ID; the recent transition event log is bounded to 2,000 events, not the ID inventory.
+The extension cannot verify information that an upstream service does not publish. It keeps that uncertainty visible instead of guessing.
 
-- Explicit upstream retirement / elapsed explicit retirement date: retired, removed from callable models, retained in history.
-- Missing from a successful catalog: **not-listed**, NOT proven retired; removed from callable models, retained in history. Reappearance restores it automatically.
-- Deprecated but still listed/free: still available, labelled deprecated.
-- Free-to-paid change: removed from callable free models, retained in report/history.
-- HTTP 404/429, capacity failures, timeouts: never taken as retirement proof.
-- Catalog network/JSON/schema/empty-list failures: keep cached entries visible, prominently mark freshness failure, block unverified calls. Do not mass-retire cached models.
-- A cancelled Pi background refresh never invalidates a completed good startup snapshot.
+## Refreshes and model history
 
-A refresh is an attempt to retrieve current upstream information, not a guarantee that the upstream/CDN has perfect, instantly synchronized metadata. During network failure, fresh information cannot be fabricated.
+All five sources are fetched on every extension load, before initial model selection, including noninteractive runs. An existing cache does not skip that startup check. After five minutes, the next agent turn or request triggers revalidation. Use `/free-refresh` to request an immediate refresh; there is no background polling timer.
+
+A failed refresh does not erase the last known catalog. Cached entries stay visible, are marked as unverified, and cannot be called without the required fresh evidence.
+
+Changes are handled according to what the sources actually say:
+
+| Change | What happens |
+|---|---|
+| Explicit retirement | The model is removed from callable models and kept in history. |
+| Missing from a successful catalog response | It is marked `not-listed`, not assumed retired. It can return if listed again. |
+| Deprecated, but still listed and free | It remains available with a deprecation label. |
+| Free model becomes paid | Free access is blocked; the model remains in the report. |
+| Timeout, 404, 429, or capacity error | The error is recorded, not treated as proof of retirement. |
+
+The cache is stored in `free-catalog/catalog.json` inside Pi's agent directory, normally `~/.pi/agent/free-catalog/`. Despite the filename, the cache is compact, gzip-compressed JSON. Older plain-JSON caches still load. It retains raw source responses, timestamps, classifications, and lifecycle history; the recent change log is limited to 2,000 events, but the model inventory is not.
+
+`/free-export` writes readable, uncompressed JSON for inspection. Refreshes are bounded by a 12-second timeout and a 16 MiB response limit per source. A successful fetch reflects the upstream data at that moment, not a guarantee that every source agrees instantly.
 
 ## Commands
 
-| Command | Function |
+| Command | What it does |
 |---|---|
-| `/free-catalog` | Show all free + uncertain/conflicting + former/absent/retired entries, source health and last HTTP statuses |
-| `/free-refresh` | Re-fetch all catalogs/prices/capabilities; replace lists and report transitions |
-| `/free-thinking` | Inspect native thinking choices and the selected mode for current free model |
-| `/free-thinking MODE` | Select a provider-advertised native mode, saved per provider/model |
-| `/free-export [PATH]` | Export complete evidence, all live IDs including paid ones, source JSON and history |
+| `/free-catalog` | Show free, uncertain, conflicting, missing, and historical models, plus source health and recent HTTP results. |
+| `/free-refresh` | Fetch the sources again and reconcile the model lists. |
+| `/free-thinking` | Show the current model's native thinking options and selection. |
+| `/free-thinking MODE` | Choose `auto`, `default`, or an advertised native mode. |
+| `/free-footer compact` | Hide the free-provider label beside the model in the footer. |
+| `/free-footer default` | Restore Pi's built-in footer. |
+| `/free-export [PATH]` | Export the complete catalog, including source data and all live IDs, even paid ones. |
+
+## Thinking that matches the model
+
+Use Pi's normal thinking selector or shortcut as usual. In `auto` mode, the extension translates the selected level into a setting the provider actually advertises. It does not invent effort levels for models that only have an on/off switch.
+
+You can also choose a native mode directly. For example, after selecting an appropriate model:
+
+```text
+/free-thinking low
+/free-thinking instant
+/free-thinking thinking
+/free-thinking auto
+/free-thinking default
+```
+
+These are examples for different models, not options supported by every model. Kilo Beam advertises effort levels such as `low`, `medium`, `high`, `xhigh`, and `max`. Toggle models use modes such as `instant` and `thinking`. Zen effort settings are sent as `reasoning_effort`; Kilo settings use the provider's native parameters. The available choices come from live metadata, so check `/free-thinking` rather than relying on a fixed list.
 
-## Thinking — actual provider semantics
+### Pi and native choices stay in sync
 
-`auto` maps Pi's current thinking level to advertised native values. Standard Pi `--thinking low` was wire-tested on Kilo and Zen Beam. `default` removes adapter-generated thinking fields and leaves the provider default. Neither mode invents unsupported effort values.
+When a native mode has an exact Pi equivalent, `/free-thinking` updates Pi's actual level too. For example, an effort model's `low` maps to Pi `low`. On a supported toggle model, `instant` maps to `off`, and `thinking` maps to `medium` as the on/off equivalent—not as an extra provider effort level.
 
-Examples (first select the indicated model):
+Changing the level in Pi then releases the previous native override for that model and returns it to `auto`. This prevents an old native setting from silently overriding what the Pi footer shows. Pi's omitted `reasoning` option for `off` is handled explicitly, so an advertised disabled mode is sent when available.
 
-- Kilo Laguna / Super VL toggle: `/free-thinking instant` or `/free-thinking thinking`.
-- Kilo Beam: `/free-thinking low`, `medium`, `high`, `xhigh`, `max`.
-- Zen Beam: corresponding advertised effort values, sent as `reasoning_effort`.
-- Reset: `/free-thinking auto` or `/free-thinking default`.
+There are a few limits worth knowing:
 
-Kilo variant names/parameters come from live `opencode.variants`; Zen uses live `reasoning_options` and exact-ID Pi capability hints. New native names are not limited to Pi's fixed level vocabulary. Unsupported modes fail explicitly. Where the provider publishes no adjustable values, only its default is advertised; we do not claim that choosing a Pi level secretly changed it. A native mode overrides Pi's level only for that individual model. Thinking preferences live in `thinking.json` beside the catalog.
+- `default` leaves thinking to the provider; it is not another spelling of `off`.
+- A native mode without an exact Pi equivalent remains selectable through `/free-thinking`. The status bar labels that override rather than pretending Pi's fixed level names cover it.
+- Choosing the same Pi level again does not emit a change event in Pi 1.3. Use `/free-thinking auto`, or change the level, to release an override.
+- Saved native preferences return when you start a session or switch back to a model. They can take precedence over Pi's initial level. Choose `auto` if you want Pi to control it instead.
+- If a provider advertises no adjustable controls, its default is preserved. Unsupported effort or disable settings are never guessed.
 
-Full capabilities remain in the exported raw metadata. Pi currently accepts only text/image inputs through this chat integration; other advertised modalities are not falsely presented as implemented. Required missing limits use labelled local safety defaults (8192 context / 2048 output), NOT claimed provider limits. Models are not hidden for that reason.
+Preferences are saved per provider and model in `thinking.json` beside the cache.
 
-## Transport and security
+## A quieter footer
 
-Uses Pi's own OpenAI Completions, Responses, Anthropic Messages and native classifier implementations; no home-grown SSE parser. Tool schemas/results, Unicode, cancellation, usage and finish reasons remain SDK-owned. No global fetch/http patches. Scoped fetch validates the exact model, URL, current free classification and freshness before each HTTP call; disallows redirects and paid fallback; strips personal Authorization/API-key headers.
+By default, the extension hides only the `(free-kilo)` or `(free-zen)` prefix beside the model name. Provider IDs and model-picker entries are unchanged. The footer keeps the working directory, branch, token and cache statistics, cost, context usage, thinking level, and extension statuses. Catalog counts and freshness warnings remain visible.
 
-Kilo sends no Authorization. Zen uses literal `Bearer public` and OpenCode-compatible CLI protocol headers with a stable per-session ID. Its User-Agent explicitly includes `pi-free-catalog` and the tested compatibility version 1.19.3. This protocol adapter is not an installed OpenCode binary. Future access policy/client-version requirements can break anonymous access; this extension does not create accounts, rotate quota identities, bypass paid authentication or promise permanent free access.
+Pi has one custom-footer slot. If another extension controls yours, run `/free-footer default` and let that extension handle the display. This restores the built-in footer; it cannot recover another extension's previous custom footer automatically. `/free-footer compact` enables this package's footer again. The preference is saved in `ui.json`.
 
-No automatic model blacklist, no hiding models after errors, no automatic disabling of tools to produce a green test. SDK retry/cancellation behavior is retained. Actual capacity, quotas, latency, tool support and reasoning quality belong to the upstream.
+The custom footer is used only in the terminal UI and only for the two free providers. Other models use Pi's built-in footer; print, JSON, and RPC modes are unaffected. The implementation uses Pi's exported renderer and was tested with Pi 1.3.0.
 
-## Tests
+## Requests, tools, and safety
+
+Requests use Pi's own OpenAI Completions, Responses, Anthropic Messages, and native classifier implementations. Pi's SDK handles streaming, tool calls and results, Unicode, cancellation, usage, and finish reasons. The extension does not replace the global HTTP client or add its own SSE parser.
+
+Before each HTTP request, a scoped guard checks the model ID, approved endpoint, free classification, and freshness. It blocks redirects and paid fallback, and strips personal authorization and API-key headers. Kilo requests carry no Authorization header. Zen uses the literal public placeholder `Bearer public`, compatible CLI headers, and a stable per-session ID. The User-Agent identifies this integration; no OpenCode binary is launched and no quota identities are rotated.
+
+Anonymous access can break if a service changes its policy or protocol requirements. This package does not promise permanent access, unlimited quota, universal tool support, or a particular response speed. An inference error does not blacklist a model or turn off tools to make a test pass.
+
+Full capability metadata is retained in exports. This chat integration supports text and image inputs; other advertised modalities are not presented as implemented. When required limits are unknown, the model is labelled accordingly and uses local safety defaults of 8,192 context tokens and 2,048 output tokens. Those are not claimed provider limits.
+
+## Development and testing
+
+From the release source ZIP or a complete source checkout:
 
 ```bash
-npm install
+npm ci
 npm run verify
 ```
 
-Verification runs syntax checks, offline automated tests against compressed real catalog fixtures (2026-10-17), mocked lifecycle/transport/security tests, real Pi SDK stream/classifier normalization tests, and npm package-content inspection. These are **not live inference claims**. Peer SDK 1.3.0 was used; fixture expectations do not pin the production catalog. The packaging test accepts both `npm pack --json` output shapes (an array on npm 11, a name-keyed object on npm 12 and later).
+Verification checks syntax, runs the offline tests, and inspects the npm package contents. The tests cover catalog classification, lifecycle changes, free-only guards, compressed caches, thinking synchronization, the actual Pi session and SDK, and Pi's footer renderer. Network responses in the offline tests are mocked. Passing them is not a claim that every upstream model works.
 
-Opt-in live catalog inspection (network, no inference):
+For an optional live catalog check without inference:
 
 ```bash
-node scripts/catalog.mjs /tmp/free-catalog-live.json
+node scripts/catalog.mjs ./catalog-inspection.json
 ```
 
-Opt-in real Pi CLI tests are in `scripts/live_pi.py` and `scripts/observe_live.py` (Python 3 + Node + installed Pi peer packages). Set absolute `PI_NODE`, `PI_CLI`, `PI_TEST_DISPATCHER`, and `FREE_TEST_DIR`; generate `FREE_TEST_DIR/live-catalog.json` with `catalog.mjs` first. `PI_TEST_DISPATCHER` is Pi's installed `dist/core/http-dispatcher.js`. `PI_CLI` is its `dist/cli.js`. The separate test-only `wire.mjs` enforces a confirmed-free allowlist and 120 POST attempts/service, records request payloads/HTTP statuses, and is never loaded in production. The suite uses isolated HOME/settings, random fixtures, default tools ON and strict named read/write/edit/bash verification. It exits processes on deadlines. Inspect `inference-results.json`; process exit 0 alone does not mean all upstream models passed. Re-running reuses completed case IDs; use a new evidence directory for a fresh complete run.
+For live inference checks, use `scripts/verify-ui-thinking-live.mjs` in an isolated HOME with `PI_CODING_AGENT_DIR` set to a fresh directory. It runs Pi's actual agent session with the default read, write, edit, and bash tools, checks thinking parameters, and verifies real file changes. It makes about 14 inference requests across the two Beam models. `--toggle-only` runs the separate toggle checks. Model errors stop the run; inspect the result JSON and wire log rather than relying on a confident final answer.
 
-Releases are published from the `aminmza` npm account with 2FA enabled. See [PUBLISHING-fa.md](PUBLISHING-fa.md). Never share npm tokens or commit `.npmrc`, credentials, caches or live test files.
+The broader opt-in CLI harnesses, `scripts/live_pi.py` and `scripts/observe_live.py`, are also included. They require Python 3 and the `PI_NODE`, `PI_CLI`, `PI_TEST_DISPATCHER`, and `FREE_TEST_DIR` environment variables. Their test-only wire recorder is never loaded by the extension.
 
-## Sources
+Do not commit or publish credentials, `.npmrc`, caches, or live test outputs. Review the source and the upstream services' terms before use; the code's MIT license does not grant service access.
+
+## Catalog sources
 
 - https://api.kilo.ai/api/gateway/models
 - https://opencode.ai/zen/v1/models
 - https://models.opencode.ai/api.json
 - https://models.dev/api.json
 - https://pi.dev/api/models/providers/opencode?types=chat,image,classifier
-
-Independent MIT-licensed implementation. No upstream plugin source is vendored. Fixture catalogs are factual snapshots used for regression testing, not a model-weight license or service-access grant.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-free-catalog",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Live, auditable anonymous Kilo and OpenCode free model catalogs for Pi. No name-based free filtering.",
   "type": "module",
   "license": "MIT",
@@ -37,8 +37,6 @@
     "scripts/*.js",
     "scripts/*.py",
     "README.md",
-    "README-fa.md",
-    "PUBLISHING-fa.md",
     "CHANGELOG.md",
     "LICENSE"
   ],

package/scripts/verify-ui-thinking-live.mjs

@@ -0,0 +1,55 @@
+/** Opt-in live proof: fresh catalogs, actual Pi AgentSession, no mocks or personal auth.
+ * Run in a clean HOME with PI_CODING_AGENT_DIR isolated, after npm install.
+ * node scripts/verify-ui-thinking-live.mjs /absolute/evidence-directory
+ * Makes up to ~14 short free-model requests. This is not run by npm test.
+ */
+import {mkdir,writeFile,readFile,unlink} from 'node:fs/promises';
+import {resolve,join} from 'node:path';import {randomBytes,createHash} from 'node:crypto';import dc from 'node:diagnostics_channel';import fs from 'node:fs';
+import {createAgentSession,DefaultResourceLoader,SessionManager,SettingsManager} from '@earendil-works/pi-coding-agent';
+import extension from '../src/index.js';
+const root=resolve(process.argv[2]||'live-proof');await mkdir(root,{recursive:true});
+const wireFile=join(root,'wire.jsonl'),requests=new WeakMap();let requestCount=0;
+const log=x=>fs.appendFileSync(wireFile,JSON.stringify({at:new Date().toISOString(),...x})+'\n');
+dc.subscribe('undici:request:create',({request})=>{if(request.method==='POST'&&/api\.kilo\.ai|opencode\.ai/.test(String(request.origin)))requests.set(request,{id:++requestCount,parts:[]});});
+dc.subscribe('undici:request:bodyChunkSent',({request,chunk})=>{const x=requests.get(request);if(x)x.parts.push(Buffer.from(chunk));});
+dc.subscribe('undici:request:bodySent',({request})=>{const x=requests.get(request);if(x)log({kind:'request',id:x.id,url:String(request.origin)+request.path,headers:request.headers,body:JSON.parse(Buffer.concat(x.parts).toString())});});
+dc.subscribe('undici:request:headers',({request,response})=>{const x=requests.get(request);if(x)log({kind:'response',id:x.id,http:response.statusCode});});
+const statuses=new Map(),notes=[],errors=[],result={at:new Date().toISOString(),cases:[],errors};let session;
+const save=()=>writeFile(join(root,'results.json'),JSON.stringify(result,null,2));
+async function prompt(text,timeout=120000){let timer;try{await Promise.race([session.prompt(text),new Promise((_,reject)=>{timer=setTimeout(async()=>{await session.abort();reject(new Error('Live prompt deadline'));},timeout);})]);}finally{clearTimeout(timer);}}
+async function chat(label,provider,id,setup){await session.setModel(session.modelRuntime.getModel(provider,id));await setup();const before=requestCount,start=performance.now();await prompt('What is 17 multiplied by 19? Answer only the number.');const last=session.messages.filter(m=>m.role==='assistant').at(-1);const text=(last?.content||[]).filter(x=>x.type==='text').map(x=>x.text).join('');const c={label,provider,id,piThinking:session.thinkingLevel,seconds:(performance.now()-start)/1000,answer:text,stopReason:last?.stopReason,errorMessage:last?.errorMessage,pass:/\b323\b/.test(text)&&last?.stopReason!=='error',apiRequests:requestCount-before};result.cases.push(c);await save();console.log(label,c.pass,c.seconds.toFixed(2),session.thinkingLevel);if(last?.stopReason==='error'||last?.stopReason==='aborted')throw new Error('Live model error; stopped without retries/fallback: '+(last.errorMessage||last.stopReason));}
+async function tools(provider,id){
+ await session.setModel(session.modelRuntime.getModel(provider,id));session.setThinkingLevel('low');
+ const dir=join(root,provider+'-tools');await mkdir(dir,{recursive:true});const token=randomBytes(12).toString('hex'),fixture='TOKEN='+token+'\n',expected='stage=done\nTOKEN='+token+'\n';
+ const verifier=`import pathlib,hashlib,json\np=pathlib.Path(__file__).parent/'result.txt'\nb=p.read_bytes()\nassert b.decode()==${JSON.stringify(expected)}\nprint(json.dumps({'verified':True,'sha256':hashlib.sha256(b).hexdigest()}))\n`;
+ await writeFile(join(dir,'fixture.txt'),fixture);await writeFile(join(dir,'verify.py'),verifier);await unlink(join(dir,'result.txt')).catch(()=>{});
+ const events=[],start=performance.now(),before=requestCount;const unsub=session.subscribe(e=>{if(e.type.startsWith('tool_execution_'))events.push(e);});
+ try{await prompt(`Use the actual read, write, edit, bash tools, in that order. Work only inside ${dir}. Do not access network, credentials or environment variables. Read ${dir}/fixture.txt with read. Write ${dir}/result.txt with write, exactly two lines: stage=raw and TOKEN=<the token from fixture.txt>, ending with a newline. Use edit to replace stage=raw with stage=done. Use bash to run python3 ${dir}/verify.py. Do not alter fixture.txt or verify.py. Do not substitute bash for read/write/edit. After verification answer exactly DONE <TOKEN> <sha256 printed by verifier>.`,180000);}finally{unsub();}
+ const data=await readFile(join(dir,'result.txt'),'utf8').catch(()=>''),sha=createHash('sha256').update(data).digest('hex');
+ const ends=events.filter(e=>e.type==='tool_execution_end'),starts=events.filter(e=>e.type==='tool_execution_start');
+ const checks=Object.fromEntries(['read','write','edit','bash'].map(name=>[name,starts.some(s=>s.toolName===name&&ends.some(e=>e.toolCallId===s.toolCallId&&!e.isError)&&(name==='bash'?s.args.command.includes('verify.py'):resolve(s.args.path)===join(dir,name==='read'?'fixture.txt':'result.txt')))]));
+ const last=session.messages.filter(m=>m.role==='assistant').at(-1),answer=(last?.content||[]).filter(x=>x.type==='text').map(x=>x.text).join('');
+ const c={label:provider+'-four-tools',provider,id,piThinking:session.thinkingLevel,seconds:(performance.now()-start)/1000,checks,sha,token,answer,apiRequests:requestCount-before,events,pass:Object.values(checks).every(Boolean)&&data===expected&&answer.includes(token)&&answer.includes(sha)&&await readFile(join(dir,'fixture.txt'),'utf8')===fixture&&await readFile(join(dir,'verify.py'),'utf8')===verifier&&ends.some(e=>JSON.stringify(e.result).includes(sha))};result.cases.push(c);await save();console.log(c.label,c.pass,c.seconds.toFixed(2));
+}
+try{
+ const settingsManager=SettingsManager.inMemory({retry:{enabled:false,maxRetries:0},compaction:{enabled:false}}),agentDir=process.env.PI_CODING_AGENT_DIR;if(!agentDir)throw new Error('Set isolated PI_CODING_AGENT_DIR');
+ const loader=new DefaultResourceLoader({cwd:root,agentDir,settingsManager,noExtensions:true,noSkills:true,noPromptTemplates:true,noThemes:true,extensionFactories:[extension]});await loader.reload();
+ ({session}=await createAgentSession({cwd:root,agentDir,resourceLoader:loader,settingsManager,sessionManager:SessionManager.inMemory(root)}));
+ await session.bindExtensions({mode:'print',uiContext:{setStatus:(k,v)=>v===undefined?statuses.delete(k):statuses.set(k,v),notify:(...x)=>notes.push(x)},onError:e=>errors.push(e)});
+ result.defaultTools=session.getActiveToolNames();if(!['read','write','edit','bash'].every(x=>result.defaultTools.includes(x)))throw new Error('Default tools missing');
+ result.models=session.modelRuntime.getAllModels().filter(m=>m.provider==='free-kilo'||m.provider==='free-zen').map(m=>({id:m.id,provider:m.provider,thinkingLevelMap:m.thinkingLevelMap}));await save();
+ if(!process.argv.includes('--toggle-only'))for(const [provider,id] of [['free-kilo','reflection/beam-free'],['free-zen','beam-free']]){
+  await chat(provider+'-slash-low',provider,id,()=>session.prompt('/free-thinking low'));
+  await session.prompt('/free-thinking high');if(session.thinkingLevel!=='high')throw new Error('Slash did not change Pi');
+  await chat(provider+'-pi-low-after-high',provider,id,async()=>session.setThinkingLevel('low'));
+  await tools(provider,id);
+ }
+ if(process.argv.includes('--toggle-only')) {
+  const provider='free-kilo',id='poolside/laguna-s-2.1:free';
+  await chat('toggle-native-thinking',provider,id,()=>session.prompt('/free-thinking thinking'));
+  await chat('toggle-native-instant',provider,id,()=>session.prompt('/free-thinking instant'));
+  await chat('toggle-Pi-off',provider,id,async()=>{session.setThinkingLevel('medium');session.setThinkingLevel('off');});
+ }
+ result.pass=result.cases.length===(process.argv.includes('--toggle-only')?3:6)&&result.cases.every(x=>x.pass)&&errors.length===0;result.notes=notes;result.done=true;
+}catch(error){result.fatal=String(error.stack||error);result.pass=false;console.error(result.fatal);}finally{if(session){await session.extensionRunner.emit({type:'session_shutdown'});session.dispose();}await save();}
+if(!result.pass)process.exitCode=1;

package/src/catalog.js

@@ -1,4 +1,5 @@
 import { readFile, mkdir, writeFile, rename } from 'node:fs/promises';
+import { gzipSync, gunzipSync } from 'node:zlib';
 import { dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
@@ -145,11 +146,14 @@ export function summary(state) {
   }
   return result;
 }
-export async function atomicJSON(file, data) {
+export async function atomicJSON(file, data, {gzip=false}={}) {
   await mkdir(dirname(file),{recursive:true,mode:0o700});
   const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
-  await writeFile(temp,JSON.stringify(data,null,2),{mode:0o600}); await rename(temp,file);
+  // Compact when gzipping: indentation is pure waste for machine-read state.
+  const body = gzip ? gzipSync(JSON.stringify(data)) : JSON.stringify(data,null,2);
+  await writeFile(temp,body,{mode:0o600}); await rename(temp,file);
 }
+export const isGzip = (buf) => buf.length >= 2 && buf[0] === 0x1f && buf[1] === 0x8b;
 export class Catalog {
   constructor({file,fetch:fetcher=globalThis.fetch,timeout=12000,now=()=>Date.now(),maxAge=300000}={}) {
     this.file=file;this.fetcher=fetcher;this.timeout=timeout;this.now=now;this.maxAge=maxAge;this.state={schemaVersion:1,sources:{},entries:{},history:[]};this.lastAttempt=0;
@@ -157,7 +161,10 @@ export class Catalog {
   async load() {
     if (!this.file) return;
     try {
-      const state=JSON.parse(await readFile(this.file,'utf8'));
+      // Accepts gzipped state (current) and plain JSON (pre-0.1.2 catalogs).
+      const buf=await readFile(this.file);
+      const text=isGzip(buf)?gunzipSync(buf).toString('utf8'):buf.toString('utf8');
+      const state=JSON.parse(text);
       if (state.schemaVersion===1 && state.entries && state.sources) this.state=state;
     } catch(error) { if(error.code!=='ENOENT') this.cacheWarning=String(error); }
   }
@@ -184,7 +191,7 @@ export class Catalog {
     // Never let Pi's startup refresh cancellation invalidate a successful startup snapshot.
     if(signal?.aborted){this.lastAttempt=previousAttempt;throw signal.reason || new Error('Catalog refresh cancelled');}
     this.state=reconcile(sources,old,new Date(this.now()).toISOString());
-    if(this.file) try{await atomicJSON(this.file,this.state);}catch(e){this.cacheWarning=String(e);}
+    if(this.file) try{await atomicJSON(this.file,this.state,{gzip:true});}catch(e){this.cacheWarning=String(e);}
     return this.state;
   }
   async ensureFresh() { if(this.now()-this.lastAttempt>=this.maxAge) await this.refresh(); }

package/src/footer.js

@@ -0,0 +1,42 @@
+import { FooterComponent } from '@earendil-works/pi-coding-agent';
+import { freeModelKey } from './thinking-sync.js';
+
+/** Reuse Pi 1.3's exported renderer, with a local read-only view (never mutate core/provider IDs). */
+export function freeFooter(pi,ctx,tui,footerData) {
+  const session={
+    get state(){return {model:ctx.model,thinkingLevel:pi.getThinkingLevel()};},
+    get model(){return ctx.model;},
+    get sessionManager(){return ctx.sessionManager;},
+    getContextUsage:()=>ctx.getContextUsage(),
+    // This footer is installed only for our two anonymous, non-subscription providers.
+    modelRuntime:{isUsingSubscription:()=>false},
+  };
+  const data={
+    getGitBranch:()=>footerData.getGitBranch(),
+    getExtensionStatuses:()=>footerData.getExtensionStatuses(),
+    getAvailableProviderCount:()=>1,
+    onBranchChange:fn=>footerData.onBranchChange(fn),
+  };
+  const component=new FooterComponent(session,data);
+  const unsubscribe=footerData.onBranchChange(()=>tui.requestRender());
+  return {
+    invalidate:()=>component.invalidate(),
+    dispose:()=>{unsubscribe();component.dispose();},
+    render(width){
+      component.setAutoCompactEnabled(pi.getSettings().compaction?.enabled!==false);
+      return component.render(width);
+    },
+  };
+}
+/** Pi exposes one footer slot. Other footer extensions can opt out with /free-footer default. */
+export function footerController({pi,getMode}) {
+  let installed=false;
+  return ctx=>{
+    if(ctx.mode!=='tui')return;
+    if(getMode()==='compact' && freeModelKey(ctx.model)) {
+      if(!installed) {
+        ctx.ui.setFooter((tui,_theme,data)=>freeFooter(pi,ctx,tui,data));installed=true;
+      }
+    } else if(installed) {ctx.ui.setFooter(undefined);installed=false;}
+  };
+}

package/src/index.js

@@ -4,6 +4,8 @@ import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { completions, responses, anthropic, classify } from './sdk.js';
 import { Catalog, PROVIDERS, recordKey, summary, atomicJSON } from './catalog.js';
 import { registrations, report, thinkingProfile, selectThinking } from './models.js';
+import { thinkingSync } from './thinking-sync.js';
+import { footerController } from './footer.js';
 import { scopedFetch, requestPayload, sessionId } from './transport.js';
 
 const STREAMS={'openai-completions':completions,'openai-responses':responses,'anthropic-messages':anthropic};
@@ -13,6 +15,10 @@ export default async function freeCatalog(pi) {
   const catalog=new Catalog({file:join(directory,'catalog.json')});
   const selectionFile=join(directory,'thinking.json');let selections={};
   try { const d=JSON.parse(await readFile(selectionFile,'utf8'));if(d&&typeof d==='object'&&!Array.isArray(d))selections=d; } catch {}
+  const uiFile=join(directory,'ui.json');let uiPreferences={footer:'compact'};
+  try {const d=JSON.parse(await readFile(uiFile,'utf8'));if(['compact','default'].includes(d.footer))uiPreferences=d;}catch {}
+  let saveQueue=Promise.resolve();
+  const saveSelections=()=>{const snapshot=structuredClone(selections);saveQueue=saveQueue.catch(()=>{}).then(()=>atomicJSON(selectionFile,snapshot));return saveQueue;};
   let session=sessionId();
   const getSelection=(service,id)=>selections[recordKey(service,id)] || 'auto';
   const health={};
@@ -30,7 +36,7 @@ export default async function freeCatalog(pi) {
         const fetch=scopedFetch({catalog,service,model,session,onResponse:r=>noteResponse(service,model.id,r)});
         return stream(model,context,{
           ...options,apiKey:'public',fetch,
-          onPayload:requestPayload({catalog,service,id:model.id,getSelection,piLevel:options.reasoning,original:options.onPayload}),
+          onPayload:requestPayload({catalog,service,id:model.id,getSelection,piLevel:options.reasoning??'off',original:options.onPayload}),
         });
       },
       classifiers:{'typesafe-system-one':{classify:async(model,context,options={})=>{
@@ -46,21 +52,31 @@ export default async function freeCatalog(pi) {
     const s=summary(catalog.state),bad=Object.entries(catalog.state.sources).filter(([,x])=>!x.fresh).map(([k])=>k);
     ctx.ui.setStatus('free-catalog',`Free: Kilo ${s.kilo.free} · Zen ${s.zen.free}${bad.length?' · STALE '+bad.join(','):''}`);
   };
+  const sync=thinkingSync({pi,catalog,getSelection,setSelection:(key,mode)=>{selections[key]=mode;},save:saveSelections,output});
+  const updateFooter=footerController({pi,getMode:()=>uiPreferences.footer});
+  pi.on('session_shutdown',async()=>{await saveQueue;});
+  pi.on('thinking_level_select',(event,ctx)=>sync.selected(event,ctx));
+  pi.on('model_select',(_event,ctx)=>{sync.restore(ctx);updateFooter(ctx);});
+  pi.on('session_before_switch',()=>{sync.unbind();});
   pi.on('session_start',async(_event,ctx)=>{
-    status(ctx);
+    status(ctx);sync.restore(ctx);updateFooter(ctx);
     const bad=Object.entries(catalog.state.sources).filter(([,s])=>!s.fresh);
     if(bad.length)output('Free catalog refresh incomplete: '+bad.map(([k,s])=>`${k}: ${s.error}`).join('; ')+'. Cached entries remain visible; unverified requests are blocked.',ctx);
     if(catalog.cacheWarning)output('Free catalog cache warning: '+catalog.cacheWarning,ctx);
   });
-  pi.on('session_switch',()=>{session=sessionId();});
+  pi.on('session_switch',(_event,ctx)=>{session=sessionId();sync.restore(ctx);updateFooter(ctx);});
   pi.on('before_agent_start',async(_event,ctx)=>{
-    if(Date.now()-catalog.lastAttempt>=catalog.maxAge){await catalog.refresh();install();status(ctx);}
+    if(Date.now()-catalog.lastAttempt>=catalog.maxAge){await catalog.refresh();install();status(ctx);sync.restore(ctx);}
   });
   pi.registerCommand('free-catalog',{description:'Show ALL free, uncertain, deprecated, absent and retired models; no hidden name filters',handler:async(_args,ctx)=>{output(report(catalog.state)+'\n\nLast HTTP results (not retirement proof):\n'+JSON.stringify(health,null,2),ctx);}});
   pi.registerCommand('free-refresh',{description:'Fetch all catalogs, prices and capabilities again; reconcile lifecycle and replace model lists',handler:async(_args,ctx)=>{
-    await catalog.refresh();install();status(ctx);output(JSON.stringify(summary(catalog.state),null,2)+'\n'+catalog.state.changes.map(c=>`${c.service}/${c.id}: ${JSON.stringify(c.from)} → ${JSON.stringify(c.to)}`).join('\n'),ctx);
+    await catalog.refresh();install();status(ctx);sync.restore(ctx);output(JSON.stringify(summary(catalog.state),null,2)+'\n'+catalog.state.changes.map(c=>`${c.service}/${c.id}: ${JSON.stringify(c.from)} → ${JSON.stringify(c.to)}`).join('\n'),ctx);
   }});
-  pi.registerCommand('free-thinking',{description:'Show native thinking modes, or choose auto/default/a native mode for the selected free model',handler:async(args,ctx)=>{
+  pi.registerCommand('free-footer',{description:'compact hides only the free provider label in the footer; default restores Pi footer',handler:async(args,ctx)=>{
+    const mode=args.trim();if(!['compact','default'].includes(mode)){output(`Footer: ${uiPreferences.footer}. Use /free-footer compact or /free-footer default.`,ctx);return;}
+    uiPreferences.footer=mode;await atomicJSON(uiFile,uiPreferences);updateFooter(ctx);output(`Free model footer: ${mode}. Provider IDs and model picker are unchanged.`,ctx);
+  }});
+  pi.registerCommand('free-thinking',{description:'Inspect native thinking or select a mode; exact Pi equivalents sync both ways',handler:async(args,ctx)=>{
     const service=Object.entries(PROVIDERS).find(([,p])=>p===ctx.model?.provider)?.[0];
     if(!service){output('Select a free-kilo or free-zen chat model first.',ctx);return;}
     await catalog.ensureFresh();const entry=catalog.state.entries[recordKey(service,ctx.model.id)];
@@ -68,8 +84,8 @@ export default async function freeCatalog(pi) {
     if(!mode){output(JSON.stringify({model:entry.id,selected:getSelection(service,entry.id),piThinking:pi.getThinkingLevel(),source:profile.source,nativeChoices:profile.choices,note:profile.note},null,2),ctx);return;}
     try {
       if(!['auto','default'].includes(mode))selectThinking(entry,catalog.state,mode);
-      selections[recordKey(service,entry.id)]=mode;await atomicJSON(selectionFile,selections);
-      output(`Thinking for ${service}/${entry.id}: ${mode}. Native settings override Pi level only for this model.`,ctx);
+      selections[recordKey(service,entry.id)]=mode;sync.applyNative(mode,ctx);await saveSelections();
+      output(`Thinking for ${service}/${entry.id}: ${mode}; Pi: ${pi.getThinkingLevel()}. Exact equivalents are synchronized; a subsequent Pi thinking change returns this model to auto. Default/unmapped modes are explicitly labelled in the status bar.`,ctx);
     }catch(error){output(String(error),ctx);}
   }});
   pi.registerCommand('free-export',{description:'Export complete live evidence, every classified ID and lifecycle history to a JSON file',handler:async(args,ctx)=>{

package/src/thinking-sync.js

@@ -0,0 +1,80 @@
+import { isDeepStrictEqual } from 'node:util';
+import { PROVIDERS, recordKey } from './catalog.js';
+import { LEVELS, selectThinking } from './models.js';
+
+export function freeModelKey(model) {
+  const service=Object.entries(PROVIDERS).find(([,provider])=>provider===model?.provider)?.[0];
+  return service ? {service,id:model.id,key:recordKey(service,model.id)} : null;
+}
+/** Only claim a Pi equivalent when it produces exactly the same native parameters. */
+export function piLevelForNative(entry,state,mode) {
+  if(['auto','default'].includes(mode))return null;
+  const target=selectThinking(entry,state,mode);
+  const levels=LEVELS.includes(mode)?[mode,...LEVELS.filter(x=>x!==mode)]:LEVELS;
+  for(const level of levels) {
+    try { if(isDeepStrictEqual(selectThinking(entry,state,'auto',level),target))return level; } catch {}
+  }
+  return null;
+}
+/** No core patches: Pi's public setter and thinking_level_select event are the bridge. */
+export function thinkingSync({pi,catalog,getSelection,setSelection,save,output}) {
+  let boundKey=null;
+  const pending=[];
+  function mirror(level,key) {
+    const previous=pi.getThinkingLevel();
+    if(previous===level)return;
+    const token={key,level,previous};pending.push(token);
+    try { pi.setThinkingLevel(level); }
+    catch(error) { const i=pending.indexOf(token);if(i>=0)pending.splice(i,1);throw error; }
+    // A clamped/no-change setter may not emit an event. Never suppress a later user action.
+    if(pi.getThinkingLevel()!==level) { const i=pending.indexOf(token);if(i>=0)pending.splice(i,1); }
+  }
+  function status(ctx) {
+    const model=freeModelKey(ctx.model),mode=model?getSelection(model.service,model.id):'auto';
+    let text;
+    if(mode==='default')text='Thinking: provider default (Pi level not applied)';
+    else if(mode!=='auto') {
+      const entry=catalog.state.entries[model.key];
+      try { if(!entry || piLevelForNative(entry,catalog.state,mode)===null)text=`Native thinking: ${mode} (no exact Pi level)`; }
+      catch {text=`Native thinking: ${mode} unavailable — select a current mode`;}
+    } else if(model) {
+      const entry=catalog.state.entries[model.key];
+      if(entry && !Object.keys(entry.metadata.opencode?.variants||{}).length) {
+        // selectThinking preserves the provider default for models without advertised choices.
+        try { if(Object.keys(selectThinking(entry,catalog.state,'auto',pi.getThinkingLevel())).length===0)text='Thinking: provider default (no advertised controls)'; } catch {}
+      }
+    }
+    ctx.ui.setStatus('free-thinking',text);
+  }
+  function restore(ctx) {
+    const model=freeModelKey(ctx.model);boundKey=model?.key??null;
+    if(model) {
+      const entry=catalog.state.entries[model.key],mode=getSelection(model.service,model.id);
+      if(entry && !['auto','default'].includes(mode)) {
+        try { const level=piLevelForNative(entry,catalog.state,mode);if(level!==null)mirror(level,model.key); }
+        catch(error) { output(`Saved thinking is no longer supported: ${error}`,ctx); }
+      }
+    }
+    status(ctx);
+  }
+  async function selected(event,ctx) {
+    const model=freeModelKey(ctx.model);
+    const i=pending.findIndex(x=>x.key===model?.key&&x.level===event.level&&x.previous===event.previousLevel);
+    if(i>=0){pending.splice(i,1);return;}
+    // Pi applies a model's default before emitting model_select. Do not erase the target's preference.
+    if(!model || model.key!==boundKey)return;
+    setSelection(model.key,'auto');
+    status(ctx);
+    await save();
+  }
+  function applyNative(mode,ctx) {
+    const model=freeModelKey(ctx.model),entry=model&&catalog.state.entries[model.key];
+    if(!entry)return;
+    if(!['auto','default'].includes(mode)) {
+      const level=piLevelForNative(entry,catalog.state,mode);
+      if(level!==null)mirror(level,model.key);
+    }
+    status(ctx);
+  }
+  return {restore,selected,applyNative,status,unbind:()=>{boundKey=null;pending.length=0;}};
+}

package/test/catalog.test.mjs

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
+import { gunzipSync } from 'node:zlib';
 import { join } from 'node:path';
 import { Catalog, reconcile, recordKey, summary, priceClass, validateSource } from '../src/catalog.js';
 import { registrations, report } from '../src/models.js';
@@ -93,7 +94,23 @@ test('startup load is followed by new network calls, updates saved cache, concur
  const fetch=async(...a)=>{calls++;return fetcher()(...a);};
  const a=new Catalog({file,fetch});await a.refresh();assert.equal(calls,5);
  const b=new Catalog({file,fetch});await b.load();await Promise.all([b.refresh(),b.refresh()]);assert.equal(calls,10);
- assert.equal(JSON.parse(await readFile(file,'utf8')).schemaVersion,1);assert.equal(summary(b.state).kilo.free,17);
+ assert.equal(JSON.parse(gunzipSync(await readFile(file)).toString('utf8')).schemaVersion,1);assert.equal(summary(b.state).kilo.free,17);
+ }finally{await rm(dir,{recursive:true,force:true});}
+});
+test('saved state is gzipped and compact, round-trips, and legacy plain caches still load',async()=>{
+ const dir=await mkdtemp(join(tmpdir(),'pi-free-gz-'));try{
+ const file=join(dir,'catalog.json');
+ const a=new Catalog({file,fetch:fetcher()});await a.refresh();
+ const raw=await readFile(file);
+ assert.equal(raw[0],0x1f);assert.equal(raw[1],0x8b);
+ const parsed=JSON.parse(gunzipSync(raw).toString('utf8'));assert.equal(parsed.schemaVersion,1);
+ const pretty=Buffer.byteLength(JSON.stringify(parsed,null,2));
+ assert.ok(raw.length*3<pretty,`gzipped ${raw.length} should be far below pretty ${pretty}`);
+ const b=new Catalog({file,fetch:fetcher()});await b.load();
+ assert.equal(summary(b.state).kilo.free,17);
+ assert.equal(Object.keys(b.state.entries).length,Object.keys(parsed.entries).length);
+ const legacy=join(dir,'legacy.json');await writeFile(legacy,JSON.stringify(parsed,null,2));
+ const c=new Catalog({file:legacy,fetch:fetcher()});await c.load();assert.equal(summary(c.state).kilo.free,17);
  }finally{await rm(dir,{recursive:true,force:true});}
 });
 test('fresh paid price beats stale free source and blocks dispatch',async()=>{
@@ -119,7 +136,7 @@ test('failed empty snapshot preserves listed free IDs instead of retiring them',
  const c=new Catalog({fetch:fetcher()});await c.refresh();const d=structuredClone(fixtures);d.kilo={data:[]};c.fetcher=fetcher(d);await c.refresh();assert.equal(summary(c.state).kilo.free,17);assert.equal(c.state.sources.kilo.fresh,false);assert.equal(c.state.entries[key('kilo','reflection/beam-free')].lifecycle,'active');
 });
 test('bulk future catalog growth without free naming never loses a free LLM',()=>{
- const d=structuredClone(fixtures);const ids=Array.from({length:100},(_,i)=>`مدل-${i}/new.route`);
+ const d=structuredClone(fixtures);const ids=Array.from({length:100},(_,i)=>`model-🧪-${i}/new.route`);
  for(const id of ids){d.kilo.data.push({id,isFree:true,context_length:4096,max_completion_tokens:512});d.zen.data.push({id});d.official.opencode.models[id]={id,cost:{input:0,output:0},limit:{context:4096,output:512}};}
  const s=reconcile(sources(d));for(const service of ['kilo','zen']){const found=new Set(registrations(s,service).map(m=>m.id));for(const id of ids)assert.ok(found.has(id),`${service}/${id}`);}
 });

package/test/english-only.test.mjs

@@ -0,0 +1,35 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {readdir,readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {gunzipSync} from 'node:zlib';
+import {fileURLToPath} from 'node:url';
+
+// Explicit Unicode ranges keep the rule readable without embedding the script it rejects.
+const prohibited=/[\u0600-\u06ff\u0750-\u077f\u08a0-\u08ff\ufb50-\ufdff\ufe70-\ufeff]/u;
+function checkText(text,label){
+ assert.ok(!prohibited.test(text),`Non-English release text in ${label}`);
+ // Catch escaped JSON/code strings as well as literal characters.
+ const unescaped=text.replace(/\\u([0-9a-f]{4})/gi,(_,hex)=>String.fromCharCode(parseInt(hex,16)));
+ // The test's regex declaration is policy, not a string containing release text.
+ if(!label.endsWith('english-only.test.mjs'))assert.ok(!prohibited.test(unescaped),`Escaped non-English text in ${label}`);
+}
+test('release source, documentation and decompressed catalog fixtures contain no Persian/Arabic-script text',async()=>{
+ const root=fileURLToPath(new URL('../',import.meta.url));let checked=0;
+ async function walk(dir){
+  for(const item of await readdir(dir,{withFileTypes:true})){
+   if(['node_modules','.git','artifacts','verification'].includes(item.name))continue;
+   const p=join(dir,item.name);
+   if(item.isDirectory()){await walk(p);continue;}
+   if(!item.isFile())continue;
+   let data=await readFile(p);if(item.name.endsWith('.gz'))data=gunzipSync(data);
+   checkText(data.toString('utf8'),p);checked++;
+  }
+ }
+ await walk(root);assert.ok(checked>=30);
+});
+test('English-only guard rejects literal and escaped script characters without dropping Unicode coverage',()=>{
+ assert.throws(()=>checkText(String.fromCharCode(0x0633),'sample.txt')); 
+ assert.throws(()=>checkText('\\u0633','sample.json')); 
+ assert.doesNotThrow(()=>checkText('Hello 🧠 — model-🧪-1','sample.txt'));
+});

package/test/extension.test.mjs

@@ -6,7 +6,8 @@ async function setup(fn){
  const dir=await mkdtemp(join(tmpdir(),'pi-free-extension-')),prior=process.env.PI_CODING_AGENT_DIR,original=globalThis.fetch;
  const configs=new Map(),commands=new Map(),events=new Map(),output=[];
  process.env.PI_CODING_AGENT_DIR=dir;let delegate=fetcher();globalThis.fetch=(...args)=>delegate(...args);const setFetch=fn=>{delegate=fn;};
- const pi={registerProvider:(id,c)=>configs.set(id,c),registerCommand:(id,c)=>commands.set(id,c),on:(id,fn)=>events.set(id,fn),sendMessage:m=>output.push(m.content),getThinkingLevel:()=> 'medium'};
+ let thinking='medium';
+ const pi={registerProvider:(id,c)=>configs.set(id,c),registerCommand:(id,c)=>commands.set(id,c),on:(id,fn)=>events.set(id,fn),sendMessage:m=>output.push(m.content),getThinkingLevel:()=>thinking,setThinkingLevel:level=>{const previousLevel=thinking;thinking=level;if(level!==previousLevel)void events.get('thinking_level_select')?.({level,previousLevel},ctx);}};
  const ctx={hasUI:false,model:{provider:'free-kilo',id:'poolside/laguna-s-2.1:free'},ui:{setStatus:()=>{}}};
  try{await extension(pi);await fn({dir,configs,commands,events,ctx,output,setFetch});}
  finally{globalThis.fetch=original;if(prior===undefined)delete process.env.PI_CODING_AGENT_DIR;else process.env.PI_CODING_AGENT_DIR=prior;await rm(dir,{recursive:true,force:true});}

package/test/footer.test.mjs

@@ -0,0 +1,33 @@
+import test from 'node:test';import assert from 'node:assert/strict';
+import {FooterComponent,initTheme} from '@earendil-works/pi-coding-agent';
+import {freeFooter,footerController} from '../src/footer.js';
+initTheme('dark');
+function setup(){
+ let renders=0,disposed=0,compact=false;
+ const model={id:'beam-free',provider:'free-zen',reasoning:true,contextWindow:1048576};
+ const entries=[{type:'message',message:{role:'assistant',usage:{input:1234,output:543,cacheRead:1000,cacheWrite:200,cost:{total:0.12}}}}];
+ const manager={getCwd:()=>'/home/dev/demo',getSessionName:()=> 'review',getEntries:()=>entries,getEntryCount:()=>entries.length,getSessionId:()=> 'id',getLeafId:()=> 'leaf'};
+ const ctx={mode:'tui',model,sessionManager:manager,getContextUsage:()=>({contextWindow:1048576,percent:42,tokens:440401}),ui:{}};
+ const data={getGitBranch:()=> 'main',getExtensionStatuses:()=>new Map([['free-catalog','Free: Kilo 17 · Zen 9'],['warning','STALE source warning']]),getAvailableProviderCount:()=>3,onBranchChange:fn=>{return()=>disposed++;}};
+ const pi={getThinkingLevel:()=> 'low',getSettings:()=>({compaction:{enabled:compact}})};
+ const original=new FooterComponent({state:{model,thinkingLevel:'low'},sessionManager:manager,getContextUsage:ctx.getContextUsage,modelRuntime:{isUsingSubscription:()=>false}},data);original.setAutoCompactEnabled(false);
+ const footer=freeFooter(pi,ctx,{requestRender:()=>renders++},data);
+ return {ctx,pi,data,footer,original,get disposed(){return disposed;},set compact(x){compact=x;}};
+}
+test('actual Pi footer renderer preserves every statistic/status but omits free provider prefix',()=>{
+ const x=setup(),clean=s=>s.replace(/\x1b\[[0-9;]*m/g,'');const before=x.original.render(200).map(clean),after=x.footer.render(200).map(clean);
+ assert.match(before[1],/\(free-zen\)/);assert.doesNotMatch(after[1],/free-zen/);assert.equal(after[0],before[0]);assert.equal(after[2],before[2]);
+ for(const text of ['↑1.2k','↓543','R1.0k','W200','CH','42.0%','beam-free','low','$0.120'])assert.ok(after[1].includes(text),text);
+ assert.equal(after[1].replaceAll(' ',''),before[1].replace('(free-zen)','').replaceAll(' ',''));
+});
+test('both free labels hidden, identity untouched, narrow width and compaction setting honored',()=>{
+ const x=setup();x.ctx.model.provider='free-kilo';assert.doesNotMatch(x.footer.render(200).join('\n'),/free-kilo/);assert.equal(x.ctx.model.provider,'free-kilo');
+ for(const width of [1,8,24,60,120])assert.ok(x.footer.render(width).every(line=>typeof line==='string'));
+ x.compact=true;assert.match(x.footer.render(200).join('\n'),/auto/);x.footer.dispose();assert.equal(x.disposed,1);
+});
+test('controller installs only in TUI on free models, restores default away, and supports opt-out',()=>{
+ const calls=[],x=setup();let mode='compact';x.ctx.ui.setFooter=f=>calls.push(f);const update=footerController({pi:x.pi,getMode:()=>mode});
+ x.ctx.mode='rpc';update(x.ctx);assert.equal(calls.length,0);x.ctx.mode='tui';update(x.ctx);assert.equal(typeof calls[0],'function');update(x.ctx);assert.equal(calls.length,1);
+ x.ctx.model={provider:'openai',id:'test'};update(x.ctx);assert.equal(calls[1],undefined);update(x.ctx);assert.equal(calls.length,2);
+ x.ctx.model={provider:'free-zen',id:'beam-free'};update(x.ctx);mode='default';update(x.ctx);assert.equal(calls.at(-1),undefined);
+});

package/test/package.test.mjs

@@ -3,5 +3,13 @@ test('actual npm pack excludes Python bytecode, caches, credentials and node_mod
  const result=spawnSync('npm',['pack','--dry-run','--ignore-scripts','--json'],{cwd:fileURLToPath(new URL('../',import.meta.url)),encoding:'utf8'});assert.equal(result.status,0,result.stderr);
  const parsed=JSON.parse(result.stdout);const packed=Array.isArray(parsed)?parsed[0]:Object.values(parsed)[0];assert.ok(packed&&Array.isArray(packed.files),'npm pack --json shape not recognised');const files=packed.files.map(f=>f.path);assert.ok(files.length>20);
  for(const path of files)assert.ok(!/(?:^|\/)(?:node_modules|__pycache__|\.npmrc|\.env)(?:\/|$)|\.pyc$/.test(path),path);
- for(const path of ['src/index.js','src/sdk.js','src/catalog.js','src/models.js','src/transport.js','PUBLISHING-fa.md','test/fixtures/kilo.json.gz'])assert.ok(files.includes(path),path);
+ for(const path of ['src/index.js','src/sdk.js','src/catalog.js','src/models.js','src/transport.js','test/fixtures/kilo.json.gz'])assert.ok(files.includes(path),path);
+});
+test('Persian README is removed from source, English README and the published tarball',async()=>{
+ const {readFile,access}=await import('node:fs/promises');
+ await assert.rejects(access(new URL('../README-fa.md',import.meta.url)));
+ const pkg=JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8'));assert.ok(!pkg.files.includes('README-fa.md'));
+ const readme=await readFile(new URL('../README.md',import.meta.url),'utf8');assert.ok(!readme.includes('README-fa.md'));
+ const r=spawnSync('npm',['pack','--dry-run','--ignore-scripts','--json'],{cwd:fileURLToPath(new URL('../',import.meta.url)),encoding:'utf8'});assert.equal(r.status,0);
+ const d=JSON.parse(r.stdout),pack=Array.isArray(d)?d[0]:Object.values(d)[0];assert.ok(!pack.files.some(f=>f.path==='README-fa.md'));assert.ok(pack.files.some(f=>f.path==='src/footer.js'));assert.ok(pack.files.some(f=>f.path==='src/thinking-sync.js'));
 });

package/test/pi-session.test.mjs

@@ -0,0 +1,41 @@
+import test from 'node:test';import assert from 'node:assert/strict';
+import {mkdtemp,readFile,rm} from 'node:fs/promises';import {tmpdir} from 'node:os';import {join} from 'node:path';
+import {createAgentSession,DefaultResourceLoader,SessionManager,SettingsManager,initTheme} from '@earendil-works/pi-coding-agent';
+import extension from '../src/index.js';import {fetcher} from './helpers.mjs';
+
+// Actual Pi AgentSession, event runner, thinking clamp and SDK serialization.
+// Catalog and inference HTTP are mocked deliberately: separate live runs verify the network.
+test('real Pi session: slash <-> native selector, switches, footer and off wire payload',async()=>{
+ const dir=await mkdtemp(join(tmpdir(),'free-pi-session-'));const beforeFetch=globalThis.fetch,beforeDir=process.env.PI_CODING_AGENT_DIR;
+ process.env.PI_CODING_AGENT_DIR=dir;const catalogFetch=fetcher(),wires=[],errors=[],statuses=new Map();let session,footerFactory;
+ globalThis.fetch=async(input,init)=>{
+  if(String(input).endsWith('/chat/completions')){
+   wires.push(JSON.parse(init.body));return new Response('data: {"id":"x","choices":[{"index":0,"delta":{"content":"323"},"finish_reason":"stop"}]}\n\ndata: [DONE]\n\n',{headers:{'content-type':'text/event-stream'}});
+  }
+  return catalogFetch(input,init);
+ };
+ try{
+  initTheme('dark');const settingsManager=SettingsManager.inMemory({retry:{enabled:false},compaction:{enabled:false}});
+  const loader=new DefaultResourceLoader({cwd:dir,agentDir:dir,settingsManager,noExtensions:true,noSkills:true,noPromptTemplates:true,noThemes:true,extensionFactories:[extension]});await loader.reload();
+  ({session}=await createAgentSession({cwd:dir,agentDir:dir,resourceLoader:loader,settingsManager,sessionManager:SessionManager.inMemory(dir)}));
+  await session.bindExtensions({mode:'tui',uiContext:{setStatus:(k,v)=>v===undefined?statuses.delete(k):statuses.set(k,v),setFooter:factory=>{footerFactory=factory;},notify:()=>{}},onError:e=>errors.push(e)});
+  const model=(s,id)=>session.modelRuntime.getModel(s,id);
+  const beam=model('free-zen','beam-free'),laguna=model('free-kilo','poolside/laguna-s-2.1:free');assert.ok(beam&&laguna);
+  await session.setModel(beam);await session.prompt('/free-thinking max');assert.equal(session.thinkingLevel,'max');
+  await session.prompt('17*19?');assert.equal(wires.at(-1).reasoning_effort,'max');
+  session.setThinkingLevel('low');await session.prompt('17*19?');assert.equal(wires.at(-1).reasoning_effort,'low');
+  await session.prompt('/free-thinking default');await session.prompt('17*19?');assert.equal(wires.at(-1).reasoning_effort,undefined);assert.match(statuses.get('free-thinking'),/provider default/);
+  session.setThinkingLevel('high');await session.prompt('17*19?');assert.equal(wires.at(-1).reasoning_effort,'high');assert.equal(statuses.get('free-thinking'),undefined);
+  await session.prompt('/free-thinking max');await session.setModel(laguna);await session.prompt('/free-thinking instant');assert.equal(session.thinkingLevel,'off');await session.prompt('17*19?');assert.deepEqual(wires.at(-1).reasoning,{enabled:false,effort:'none'});
+  session.setThinkingLevel('medium');await session.prompt('17*19?');assert.deepEqual(wires.at(-1).reasoning,{enabled:true,effort:'high'});
+  session.setThinkingLevel('off');await session.prompt('17*19?');assert.deepEqual(wires.at(-1).reasoning,{enabled:false,effort:'none'});
+  await session.setModel(beam);assert.equal(session.thinkingLevel,'max'); // restored, not erased by Pi's preliminary level event
+  await session.prompt('17*19?');assert.equal(wires.at(-1).reasoning_effort,'max');
+  assert.equal(typeof footerFactory,'function');
+  const data={getGitBranch:()=>null,getExtensionStatuses:()=>statuses,getAvailableProviderCount:()=>4,onBranchChange:()=>()=>{}};
+  const component=footerFactory({requestRender:()=>{}},null,data);assert.doesNotMatch(component.render(180)[1],/free-zen/);assert.match(component.render(180)[1],/beam-free/);component.dispose();
+  await session.prompt('/free-footer default');assert.equal(footerFactory,undefined);await session.prompt('/free-footer compact');assert.equal(typeof footerFactory,'function');
+  const saved=JSON.parse(await readFile(join(dir,'free-catalog/thinking.json'),'utf8'));assert.equal(saved[JSON.stringify(['zen','beam-free'])],'max');assert.equal(saved[JSON.stringify(['kilo',laguna.id])],'auto');
+  assert.deepEqual(errors,[]);assert.equal(wires.length,8);
+ }finally{if(session){await session.extensionRunner.emit({type:'session_shutdown'});session.dispose();}globalThis.fetch=beforeFetch;if(beforeDir===undefined)delete process.env.PI_CODING_AGENT_DIR;else process.env.PI_CODING_AGENT_DIR=beforeDir;await rm(dir,{recursive:true,force:true,maxRetries:5,retryDelay:50});}
+});

package/test/readme.test.mjs

@@ -0,0 +1,33 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {readFile} from 'node:fs/promises';
+
+function linkTargets(markdown) {
+ const inline=[...markdown.matchAll(/!?\[[^\]]*\]\(\s*<?([^\s)>]+)>?(?:\s+[^)]*)?\)/g)].map(m=>m[1]);
+ const references=[...markdown.matchAll(/^\s*\[[^\]]+\]:\s*<?([^\s>]+)>?/gm)].map(m=>m[1]);
+ const html=[...markdown.matchAll(/\b(?:href|src)\s*=\s*["']([^"']+)["']/gi)].map(m=>m[1]);
+ return [...inline,...references,...html];
+}
+function isPortablePublicLink(target) {
+ if(!/^https?:\/\//i.test(target))return false;
+ const url=new URL(target);
+ // Do not reintroduce a README download/self-link, even through a CDN.
+ return !/(?:^|\/)readme(?:[-_.][^/]*)?$/i.test(decodeURIComponent(url.pathname));
+}
+test('public README has no relative documentation links, README-file links or local HTML resources',async()=>{
+ const readme=await readFile(new URL('../README.md',import.meta.url),'utf8');
+ for(const target of linkTargets(readme))assert.ok(isPortablePublicLink(target),`Non-portable public README link: ${target}`);
+ assert.ok(!readme.includes('README-fa.md'));
+});
+test('public README guard detects inline, reference and HTML link regressions',()=>{
+ const sample='[Guide](PUBLISHING-fa.md)\n[English](./README.md)\n[doc]: ../README.md\n<a href="README-fa.md">FA</a>\n<img src="./preview.png">\n[CDN](https://cdn.example.com/README.md)';
+ const targets=linkTargets(sample);assert.equal(targets.length,6);
+ assert.ok(targets.every(t=>!isPortablePublicLink(t)));
+ assert.equal(isPortablePublicLink('https://pi.dev/docs/latest/packages'),true);
+});
+test('versioned README installation example matches the release manifest and has no stale candidate banner',async()=>{
+ const pkg=JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8'));
+ const readme=await readFile(new URL('../README.md',import.meta.url),'utf8');
+ assert.ok(readme.includes(`pi install npm:${pkg.name}@${pkg.version}`));
+ assert.doesNotMatch(readme,/unreleased candidate|0\.1\.3 candidate|pi install npm:pi-free-catalog@0\.1\.2/i);
+});

package/test/sdk.test.mjs

@@ -14,8 +14,8 @@ async function run(response,extra={}){
  const events=[];for await(const e of stream)events.push(e);const result=await stream.result();return {calls,events,result};
 }
 test('real Pi SDK parses Unicode stream, terminal event, tools declaration and zero-cost usage',async()=>{
- const response=sse([chunk({role:'assistant',content:'سلام 🧠'}),{...chunk({},'stop'),usage:{prompt_tokens:7,completion_tokens:3,total_tokens:10}}]);
- const {events,result,calls}=await run(response);assert.equal(result.stopReason,'stop');assert.equal(result.content[0].text,'سلام 🧠');assert.equal(result.usage.totalTokens,10);assert.equal(result.usage.cost.total,0);assert.equal(events.filter(e=>e.type==='done'||e.type==='error').length,1);
+ const response=sse([chunk({role:'assistant',content:'Hello 🧠'}),{...chunk({},'stop'),usage:{prompt_tokens:7,completion_tokens:3,total_tokens:10}}]);
+ const {events,result,calls}=await run(response);assert.equal(result.stopReason,'stop');assert.equal(result.content[0].text,'Hello 🧠');assert.equal(result.usage.totalTokens,10);assert.equal(result.usage.cost.total,0);assert.equal(events.filter(e=>e.type==='done'||e.type==='error').length,1);
  const body=JSON.parse(calls[0][1].body);assert.equal(body.reasoning.effort,'low');assert.equal(body.tools[0].function.name,'read');
 });
 test('real Pi SDK assembles split tool JSON into valid arguments',async()=>{

package/test/thinking-sync.test.mjs

@@ -0,0 +1,39 @@
+import test from 'node:test';import assert from 'node:assert/strict';
+import {thinkingSync,piLevelForNative} from '../src/thinking-sync.js';
+import {recordKey} from '../src/catalog.js';import {state} from './helpers.mjs';
+const st=state(),get=(s,id)=>st.entries[recordKey(s,id)];
+test('exact reverse mapping covers Kilo and Zen effort including max',()=>{
+ for(const [s,id] of [['kilo','reflection/beam-free'],['zen','beam-free']])for(const level of ['low','medium','high','xhigh','max'])assert.equal(piLevelForNative(get(s,id),st,level),level);
+});
+test('toggle reverse mapping is instant -> off and thinking -> medium, never fictional low/high',()=>{
+ const e=get('kilo','poolside/laguna-s-2.1:free');assert.equal(piLevelForNative(e,st,'instant'),'off');assert.equal(piLevelForNative(e,st,'thinking'),'medium');
+});
+test('provider default and unknown future variants never claim an exact Pi level',()=>{
+ assert.equal(piLevelForNative(get('zen','beam-free'),st,'default'),null);
+ const s=structuredClone(st),e=s.entries[recordKey('kilo','reflection/beam-free')];e.metadata.opencode.variants['new-ultra']={reasoning:{enabled:true,effort:'future-effort'}};
+ assert.equal(piLevelForNative(e,s,'new-ultra'),null);
+});
+function setup(){
+ let level='medium',saved=0;const prefs={},statuses=new Map();const ctx={model:{provider:'free-zen',id:'beam-free'},ui:{setStatus:(k,v)=>statuses.set(k,v)}};
+ const key=()=>recordKey(ctx.model.provider==='free-zen'?'zen':'kilo',ctx.model.id);
+ let sync;const pi={getThinkingLevel:()=>level,setThinkingLevel:n=>{const previousLevel=level;level=n;if(n!==previousLevel)void sync.selected({level:n,previousLevel},ctx);}};
+ sync=thinkingSync({pi,catalog:{state:st},getSelection:(s,id)=>prefs[recordKey(s,id)]||'auto',setSelection:(k,m)=>prefs[k]=m,save:async()=>{saved++;},output:()=>{}});
+ return {pi,sync,ctx,prefs,statuses,key,get saves(){return saved;}};
+}
+test('native -> Pi updates actual level, internal event does not erase preference or recurse',()=>{
+ const x=setup();x.sync.restore(x.ctx);x.prefs[x.key()]='max';x.sync.applyNative('max',x.ctx);assert.equal(x.pi.getThinkingLevel(),'max');assert.equal(x.prefs[x.key()],'max');assert.equal(x.saves,0);
+});
+test('Pi -> native removes stale override immediately and affects only current free model',async()=>{
+ const x=setup();x.prefs[x.key()]='max';const other=recordKey('kilo','reflection/beam-free');x.prefs[other]='high';x.sync.restore(x.ctx);x.pi.setThinkingLevel('low');assert.equal(x.prefs[x.key()],'auto');assert.equal(x.prefs[other],'high');assert.equal(x.saves,1);
+});
+test('model-switch preliminary thinking event cannot erase target preference',async()=>{
+ const x=setup();x.sync.restore(x.ctx);x.ctx.model={provider:'free-kilo',id:'reflection/beam-free'};x.prefs[x.key()]='max';await x.sync.selected({level:'low',previousLevel:'medium'},x.ctx);assert.equal(x.prefs[x.key()],'max');x.sync.restore(x.ctx);assert.equal(x.pi.getThinkingLevel(),'max');
+});
+test('non-free models are unaffected; default override and default-only controls are visibly labelled',async()=>{
+ const x=setup();x.prefs[x.key()]='default';x.sync.restore(x.ctx);assert.match(x.statuses.get('free-thinking'),/provider default/);x.pi.setThinkingLevel('low');assert.equal(x.prefs[x.key()],'auto');assert.equal(x.statuses.get('free-thinking'),undefined);
+ x.ctx.model={provider:'anthropic',id:'anything'};await x.sync.selected({level:'high',previousLevel:'low'},x.ctx);x.sync.restore(x.ctx);assert.equal(x.statuses.get('free-thinking'),undefined);assert.equal(x.saves,1);
+});
+test('unmapped future native mode remains usable and explicitly labelled',()=>{
+ const x=setup();const e=st.entries[x.key()];e.metadata.reasoning_options.push({type:'effort',values:['future-effort']});
+ try{x.prefs[x.key()]='future-effort';x.sync.restore(x.ctx);assert.equal(x.pi.getThinkingLevel(),'medium');assert.match(x.statuses.get('free-thinking'),/no exact Pi level/);}finally{e.metadata.reasoning_options.pop();}
+});

package/test/transport.test.mjs

@@ -24,7 +24,7 @@ test('HTTP 404/429 are passed through and NOT reclassified as retirement',async(
  for(const status of [404,429]){const response=new Response('upstream error',{status});const {f}=setup('kilo',input.model,response);assert.equal((await f(url,{method:'POST',body:JSON.stringify(input)})).status,status);assert.equal(catalog.state.entries[recordKey('kilo',input.model)].lifecycle,'active');}
 });
 test('Unicode SSE, empty text, tool chunks and partial bytes pass through exactly, no lossy SSE fixer',async()=>{
- const bytes=new TextEncoder().encode('data: {"choices":[{"delta":{"content":"سلام 🧠"}}]}\n\ndata: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":"{\\"path\\":\\"a\\"}"}}]}}]}\n\ndata: [DONE]\n\n');
+ const bytes=new TextEncoder().encode('data: {"choices":[{"delta":{"content":"Hello 🧠"}}]}\n\ndata: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":"{\\"path\\":\\"a\\"}"}}]}}]}\n\ndata: [DONE]\n\n');
  const response=new Response(new ReadableStream({start(c){for(let i=0;i<bytes.length;i+=3)c.enqueue(bytes.slice(i,i+3));c.close();}}));
  const {f}=setup('kilo',input.model,response);const actual=await f(url,{method:'POST',body:JSON.stringify(input)});assert.equal(actual,response);assert.deepEqual(new Uint8Array(await actual.arrayBuffer()),bytes);
 });

package/PUBLISHING-fa.md

@@ -1,115 +0,0 @@
-# انتشار در npm و نصب تک‌دستوری در Pi
-
-این بسته روی npm منتشر شده است: `pi-free-catalog` (بدون scope، نسخهٔ 0.1.1، نگهدارنده: `aminmza`). این راهنما برای انتشار نسخه‌های بعدی و بازتولید همین فرایند است. یک بسته هر دو provider را منتشر می‌کند؛ نیازی به انتشار دو بسته نیست.
-
-## ۱. پیش‌نیاز
-
-- حساب npm متعلق به خودتان؛ دسترسی به نام یا scope مورد نظر.
-- Node >=22.19 و نسخهٔ سازگار Pi. این نسخه روی Pi 1.3.0 آزمایش شده است.
-- فعال‌کردن احراز هویت دومرحله‌ای حساب npm برای انتشار تعاملی.
-- بررسی کد و مجوز MIT. برای استفاده از سرویس‌های مدل، شرایط خود سرویس‌ها هم مستقل از مجوز کد است.
-
-طبق مستندات فعلی npm، انتشار بسته به 2FA یا روش مجاز token نیاز دارد. پیشنهاد این راهنما **login و انتشار تعاملی با 2FA** است. رمز، OTP، توکن یا فایل `.npmrc` را در چت/سورس نگذارید. برای CI در آینده trusted publishing را بررسی کنید، نه قراردادن توکن در کد.
-
-## ۲. نام و scope بسته
-
-داخل پوشهٔ استخراج‌شده:
-
-```bash
-cd pi-free-catalog
-node --version
-pi --version
-npm login
-npm whoami
-```
-
-این بسته بدون scope منتشر شده است و نیازی به تغییر نام ندارد. فقط اگر می‌خواهید نسخهٔ خودتان را با scope منتشر کنید، نام را عوض کنید:
-
-```bash
-NPM_USER="$(npm whoami)"
-npm pkg set "name=@${NPM_USER}/pi-free-catalog"
-```
-
-این متغیر صرفاً نام حساب است، نه token. روی Windows PowerShell معادل آن:
-
-```powershell
-$NpmUser = npm whoami
-npm pkg set "name=@$NpmUser/pi-free-catalog"
-```
-
-اگر قبلاً همین نام/نسخه را منتشر کرده‌اید، نسخه را افزایش دهید؛ یک ترکیب name/version را نمی‌توان دوباره استفاده کرد. نام صاحب مجوز/اطلاعات نویسنده را فقط مطابق مالکیت واقعی خودتان اضافه کنید. repository را فقط وقتی آدرس واقعی دارید وارد کنید؛ در این بسته آدرس جعلی وجود ندارد.
-
-## ۳. بررسی و ساخت بسته
-
-```bash
-npm install
-npm run verify
-npm pack --dry-run
-```
-
-`verify` شامل بررسی syntax، تمام تست‌های خودکار و dry-run بسته است. به‌طور پیش‌فرض inference واقعی اجرا نمی‌کند. قبل از انتشار نهایی، تست‌های زندهٔ اختیاری را هم متناسب با بودجه/سهمیهٔ عمومی بررسی کنید.
-
-لیست فایل‌های pack را بخوانید. سورس، تست‌ها، fixtureها، مستندات و LICENSE باید باشند؛ credential، `.npmrc`، کش، HOME آزمایشی، node_modules و شواهد inference نباید باشند. بسته `files` محدود دارد و symlink توسعهٔ محلی node_modules وارد tarball نمی‌شود.
-
-## ۴. انتشار واقعی — این فرمان را خودتان اجرا می‌کنید
-
-```bash
-npm publish --access public
-```
-
-درخواست احراز هویت/2FA را در ابزار رسمی npm کامل کنید. `prepublishOnly` دوباره verify را اجرا می‌کند. اگر تست شکست بخورد، انتشار نباید ادامه یابد.
-
-برای بررسی پس از انتشار:
-
-```bash
-npm view "pi-free-catalog@0.1.1" version dist.integrity dist.shasum
-```
-
-## ۵. نصب در Pi با یک دستور
-
-برای همان حساب ناشر و در همان shell:
-
-```bash
-pi install "npm:pi-free-catalog@0.1.1"
-```
-
-برای دیگران، همان نام منتشرشده را بدهید:
-
-```bash
-pi install npm:pi-free-catalog@0.1.1
-```
-
-این نام واقعاً روی npm منتشر شده است. پس از نصب، Pi را دوباره اجرا کنید و providerهای `free-kilo` و `free-zen` را انتخاب کنید. npm بسته را نصب می‌کند؛ کاتالوگ مدل‌ها در هر اجرای خود افزونه از سرویس‌ها به‌روز می‌شود، نه از fixtureهای npm.
-
-## ۶. نسخهٔ بعدی
-
-کاتالوگ معمولاً بدون انتشار نسخهٔ جدید تازه می‌شود. اما اصلاح کد، تغییر schema/API، تغییر سیاست ناشناس یا پروتکل تازه، انتشار نسخهٔ جدید می‌خواهد.
-
-پس از تغییر و تست:
-
-```bash
-npm version patch --no-git-tag-version
-npm publish --access public
-```
-
-تغییرات و سازگاری را در CHANGELOG ثبت کنید. اگر نسخهٔ جدید User-Agent/README نسخهٔ محصول را تغییر می‌دهد، آن برچسب‌ها را هم هماهنگ کنید. از افزایش جعلی نسخهٔ پروتکل سازگاری برای پنهان‌کردن خطای API استفاده نکنید؛ سازگاری را واقعاً تست کنید.
-
-## ۷. نکتهٔ عملی: 2FA و انتشار مرحله‌ای در npm 12
-
-npm 12 انتشار را با «staged publishing» انجام می‌دهد و اثبات حضور (2FA) را به مرحله‌ای بعد موکول می‌کند؛ خانوادهٔ دستورهای `npm stage publish|list|view|approve|reject` برای همین کار است.
-
-نکتهٔ مهم در محیط بدون TTY (Termux یا CI): کتابخانهٔ npm فقط زمانی جریان احراز هویت مرورگری را اجرا می‌کند که هر دو ورودی و خروجی TTY باشند؛ در غیر این صورت بی‌درنگ خطای `EOTP` می‌دهد. روی Termux از pty استفاده کنید:
-
-```bash
-printf '\n' | script -qec 'npm publish ./pi-free-catalog-0.1.1.tgz --tag latest --access public' /dev/null
-```
-
-سپس URL چاپ‌شده را در مرورگر تأیید کنید. ممکن است npm یک نسخهٔ جایگزین `0.0.0-stage` (stub) هم در registry بسازد؛ این نسخهٔ خالی است و برچسب `latest` را تغییر نمی‌دهد.
-
-## مستندات رسمی بررسی‌شده
-
-- https://docs.npmjs.com/cli/v11/commands/npm-publish
-- https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification
-- https://docs.npmjs.com/trusted-publishers
-
-نسخهٔ فعلی منتشرشده `pi-free-catalog@0.1.1` است؛ نسخه‌های بعدی با همان حساب npm و 2FA منتشر می‌شوند. بررسی کد و مجوز MIT پیش از انتشار همچنان لازم است.

package/README-fa.md

@@ -1,127 +0,0 @@
-# افزونهٔ زندهٔ مدل‌های رایگان Pi — نسخهٔ 0.1.1
-
-یک بسته با دو provider مستقل: **`free-kilo`** و **`free-zen`**. پیاده‌سازی مستقل است؛ افزونهٔ رسمی Kilo/OpenCode نیست. روی **Pi 1.3.0 و Node 22.23.3** آزمایش شده؛ حداقل Node اعلام‌شده **22.19** است. نسخه‌های قدیمی Pi تضمین نمی‌شوند.
-
-**روی npm منتشر شده است:** بستهٔ بدون scope با نام `pi-free-catalog` (نسخهٔ 0.1.1، مجوز MIT، نگهدارنده: `aminmza`). برای نصب از registry: `pi install npm:pi-free-catalog@0.1.1`
-
-## نصب محلی
-
-ZIP را استخراج کنید و پوشه را در جای دائمی نگه دارید. از پوشهٔ والد:
-
-```bash
-pi install ./pi-free-catalog
-pi
-```
-
-سپس در انتخاب‌گر مدل، `free-kilo` یا `free-zen` را انتخاب کنید. کلید شخصی، حساب سرویس یا اجرای جداگانهٔ OpenCode CLI لازم نیست. برای عیب‌یابی، افزونه‌های دیگری را که درخواست‌های همین سرویس‌ها را تغییر می‌دهند موقتاً غیرفعال کنید. افزونه namespace مستقل دارد و مدل‌های provider اصلی شما را جایگزین نمی‌کند.
-
-## قانون اصلی: هیچ مدل رایگانی بی‌صدا ناپدید نشود
-
-- **در هر بار بارگذاری افزونه**، پیش از انتخاب مدل در شروع Pi، پنج منبع زنده دریافت می‌شوند؛ حتی در اجرای غیرتعاملی. شروع برنامه از کش به‌جای تلاش تازهٔ شبکه استفاده نمی‌کند.
-- کل شناسه‌های کاتالوگ طبقه‌بندی می‌شوند؛ نه یک allowlist ثابت و نه صرفاً نام‌هایی که `free` دارند. مدل تازهٔ بدون چنین اسمی هم کشف می‌شود.
-- Kilo با پرچم صریح `isFree:true` شناسایی می‌شود؛ وجود مبلغ مثبت در قیمت‌ها با این پرچم «تعارض» است. قیمت صفر با `isFree:false` هم خودکار رایگان فرض نمی‌شود. اگر پرچم صریح true باشد ولی قیمت عددی ناقص/پویا باشد، خود پرچم به‌عنوان مدرک حفظ می‌شود.
-- فهرست Zen قیمت ندارد؛ شناسهٔ دقیق آن با registry رسمی OpenCode، models.dev و کاتالوگ زندهٔ Pi تطبیق داده می‌شود. قیمت ورودی، خروجی، cache و tierهای اعلام‌شده بررسی می‌شود. قیمت ناموجود هرگز صفر نیست.
-- مدل‌های مشکوک، متعارض، قبلاً رایگان و مدل‌های رایگانِ متادیتا که در فهرست زنده نیستند، در گزارش و خروجی JSON باقی می‌مانند. تناقض قیمت رایگان/پولی در منابع تازه بی‌صدا نادیده گرفته نمی‌شود.
-- همهٔ مدل‌های چتِ رایگانِ تأییدشده و فهرست‌شده ثبت می‌شوند؛ حتی بدون ابزار، دارای سقف نامعلوم، یا با سابقهٔ timeout/خطای سرویس. شکست پاسخ باعث مخفی‌شدن مدل نمی‌شود.
-- classifier بومی مثل `jev-1.13-free` نیز ثبت می‌شود، ولی **به‌عنوان classifier**؛ نه مدل چت تقلبی. مصرفش از API classifier در Pi است و در انتخاب‌گر چت قرار نمی‌گیرد.
-- نوع عملیات یا پروتکل آینده‌ای که adapter آن هنوز پیاده نشده هم در کاتالوگ با توضیح روشن باقی می‌ماند، نه اینکه حذف شود.
-
-**محدودیت صادقانه:** هیچ برنامه‌ای نمی‌تواند مدل پنهان‌شده در خود سرویس یا مدل بدون هیچ مدرک قیمت را قطعاً رایگان تشخیص بدهد. این‌ها در بخش نامشخص دیده می‌شوند؛ اما برای رعایت «فقط رایگان»، خودکار قابل فراخوانی نمی‌شوند. پشتیبانی خودکار از هر schema یا پروتکل ناشناختهٔ آینده هم قابل تضمین نیست.
-
-## همهٔ اطلاعات چه زمانی تازه می‌شود؟
-
-در شروع، درخواست‌ها موازی و با timeout دوازده‌ثانیه‌ای برای هر منبع ارسال می‌شوند. بدنه‌ها حداکثر ۱۶ MiB هستند. بدنهٔ خام منابع، مشخصات، قیمت، قابلیت‌ها، وضعیت و زمان دریافت در فایل زیر ذخیره می‌شود:
-
-```text
-~/.pi/agent/free-catalog/catalog.json
-```
-
-اگر محل agent directory را تغییر داده‌اید، فایل در همان محل قرار می‌گیرد. بعد از پنج دقیقه، در نوبت بعدی عامل/درخواست دوباره اعتبارسنجی می‌شود. برای دریافت فوری از `/free-refresh` استفاده کنید. timer دائمی پس‌زمینه ندارد.
-
-اگر اینترنت یا یکی از منابع قطع باشد، **اطلاعات تازه جعل نمی‌شود**: وضعیت منبع خطادار روشن می‌شود، دادهٔ قبلی قابل مشاهده می‌ماند و درخواستِ فاقد تأیید تازه مسدود می‌شود. اگر منبع جایگزینِ معتبر و تازه برای همان شناسه وجود داشته باشد، می‌تواند مدرک قیمت فراهم کند. لغو refresh پس‌زمینه توسط خود Pi، snapshot سالمِ تازه را خراب نمی‌کند.
-
-سقف context و خروجی از متادیتای همان مدل می‌آید، نه مقدار عمومی حدسی. اگر فیلد ضروری Pi واقعاً موجود نباشد، مدل حذف نمی‌شود و نامش برچسب «limits unverified» می‌گیرد؛ مقدار ایمنی محلی 8192/2048 استفاده می‌شود، **نه ادعای سقف واقعی provider**. تمام modalityها و سایر فیلدهای خام در export حفظ می‌شوند؛ مسیر چت این افزونه فعلاً فقط ورودی text/image قابل‌نمایش در Pi را پیاده می‌کند.
-
-## تشخیص بازنشستگی و تغییر قیمت
-
-| رویداد | رفتار |
-|---|---|
-| اعلام صریح `retired` یا رسیدن تاریخ صریح retirement | از مدل‌های قابل فراخوانی خارج می‌شود؛ در تاریخچه باقی می‌ماند |
-| ناپدیدشدن از پاسخ سالم کاتالوگ | `not-listed`؛ نه ادعای بازنشستگی قطعی |
-| برگشتن به کاتالوگ | خودکار دوباره فعال می‌شود، در صورت رایگان‌بودن |
-| `deprecated` ولی هنوز موجود و رایگان | قابل استفاده با برچسب deprecated |
-| تغییر رایگان به پولی | از فهرست قابل فراخوانی رایگان خارج می‌شود؛ سابقه پنهان نمی‌شود |
-| timeout، ظرفیت، 404 یا 429 هنگام inference | دلیل بازنشستگی نیست |
-| خطای شبکه، JSON خراب یا فهرست خالی مشکوک | دادهٔ قبلی حفظ می‌شود؛ بازنشستگی دسته‌جمعی اعلام نمی‌شود |
-
-موجودی شناسه‌های دیده‌شده حذف/کوتاه نمی‌شود. فقط فهرست رویدادهای اخیر به ۲۰۰۰ تغییر محدود است؛ وضعیت فعلی و سابقهٔ حضور هر شناسه حفظ می‌شود.
-
-## فرمان‌ها
-
-```text
-/free-catalog
-/free-refresh
-/free-thinking
-/free-thinking MODE
-/free-export
-/free-export /path/to/catalog.json
-```
-
-`/free-catalog` همهٔ مدل‌های رایگان، نامشخص، متعارض و تاریخی را نشان می‌دهد. `/free-export` جزئیات کامل تمام شناسه‌های زنده، حتی پولی‌ها، و شواهد خام را ذخیره می‌کند.
-
-## تنظیم thinking بر اساس خود provider
-
-ابتدا مدل مورد نظر را انتخاب کنید و بزنید:
-
-```text
-/free-thinking
-```
-
-نام حالت‌های بومی و پارامترهایشان را می‌بینید. نمونه‌ها:
-
-- Kilo Laguna یا Super VL: `instant` و `thinking`.
-- Kilo Beam: `low`، `medium`، `high`، `xhigh`، `max`.
-- Zen Beam: effortهای اعلام‌شدهٔ خودش؛ در درخواست به شکل `reasoning_effort`.
-
-```text
-/free-thinking instant
-/free-thinking low
-/free-thinking max
-/free-thinking auto
-/free-thinking default
-```
-
-هر نمونه فقط وقتی معتبر است که مدل انتخاب‌شده همان حالت را اعلام کرده باشد. انتخاب نامعتبر خطای روشن می‌دهد. `auto` سطح thinking خود Pi را به مقدار بومی مدل نگاشت می‌کند. گزینهٔ استاندارد `--thinking low` روی Beam هر دو سرویس در درخواست واقعی بررسی شده است. `default` تنظیم thinking ساخته‌شده توسط adapter را حذف می‌کند تا پیش‌فرض provider اعمال شود.
-
-حالت انتخاب‌شده برای **همان provider/مدل** در `thinking.json` ذخیره می‌شود. Kilo از `opencode.variants` و Zen از `reasoning_options` و قابلیت‌های exact-ID کاتالوگ زندهٔ Pi استفاده می‌کند. اگر provider هیچ سطح قابل تنظیمی منتشر نکند، پیش‌فرض خودش عرضه می‌شود؛ ادعا نمی‌کنیم که انتخاب یک سطح خیالی واقعاً تغییری ایجاد کرده است.
-
-## امنیت و ابزارها
-
-- برای streaming و tool calling از پیاده‌سازی خود Pi استفاده می‌شود؛ parser دست‌ساز SSE نداریم.
-- fetch یا HTTP کل برنامه patch نمی‌شود؛ فقط درخواست providerهای خودمان کنترل می‌شود.
-- شناسهٔ مدل، endpoint، رایگان‌بودن و تازگی مدرک پیش از درخواست HTTP بررسی می‌شود. redirect و fallback پولی مجاز نیست.
-- کلید شخصی ارسال نمی‌شود: Kilo بدون Authorization؛ Zen با مقدار عمومی `Bearer public`.
-- Zen به هدرهای پروتکل سازگار OpenCode نیاز دارد. User-Agent نام این افزونه و نسخهٔ سازگاری آزمایش‌شدهٔ 1.19.3 را آشکار می‌کند؛ افزونه خودِ باینری OpenCode نیست. شناسهٔ نشست ثابت است و برای دورزدن سهمیه چرخانده نمی‌شود.
-- کلید شخصی از محیط/فایل auth توسط خود افزونه خوانده نمی‌شود و هدرهای کلید شخصی در مرز ارسال حذف می‌شوند.
-- هیچ مدلی بعد از خطا blacklist نمی‌شود و برای سبزکردن تست، ابزارها خودکار خاموش نمی‌شوند.
-
-سهمیه، ظرفیت، کیفیت ابزارزنی و تأخیر تحت اختیار سرویس است. تغییر سیاست دسترسی یا پروتکل upstream ممکن است نیازمند نسخهٔ جدید افزونه باشد. رایگان‌بودن همیشگی یا موفقیت همهٔ مدل‌ها تضمین نمی‌شود.
-
-## اجرای تست‌ها
-
-```bash
-npm install
-npm run verify
-```
-
-این فرمان syntax، تست‌های آفلاین/شبیه‌سازی، parser و classifier واقعی SDK Pi و محتوای بستهٔ npm را بررسی می‌کند. تست‌های آفلاین را نباید inference واقعی نامید. fixtureهای فشرده، snapshot واقعی ۲۰۲۶-۱۰-۱۷ هستند و فهرست production را ثابت نمی‌کنند.
-
-بررسی زندهٔ کاتالوگ بدون inference:
-
-```bash
-node scripts/catalog.mjs /tmp/free-catalog-live.json
-```
-
-اسکریپت‌های `scripts/live_pi.py`، `scripts/observe_live.py` و recorder محافظ `scripts/wire.mjs` نیز همراه سورس هستند. اجرای آن‌ها اختیاری و نیازمند Python 3، Pi نصب‌شده و مسیرهای `PI_NODE`، `PI_CLI`، `PI_TEST_DISPATCHER` و `FREE_TEST_DIR` است. ابتدا snapshot را با `catalog.mjs` در `FREE_TEST_DIR/live-catalog.json` بنویسید. توضیح دقیق‌تر در README انگلیسی آمده است. داده‌های این آزمون‌ها فقط fixture محلی‌اند؛ آن‌ها را روی پوشهٔ پروژه/اطلاعات محرمانهٔ خود اجرا نکنید. نتیجهٔ هر مدل را از JSON بخوانید؛ خروج موفق اسکریپت به معنی موفقیت همهٔ مدل‌های upstream نیست.
-
-گزارش اجرای واقعی این نسخه و فایل شواهد، جدا از بستهٔ قابل انتشار تحویل شده‌اند. روند انتشار نسخه‌های بعدی در **PUBLISHING-fa.md** آمده است؛ انتشار از حساب npm نگهدارنده با 2FA انجام می‌شود.