@vitronai/themis 0.1.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## Unreleased
+
+### Changed
+
+- Moved the package line from alpha to beta and defined beta compatibility expectations for CLI, artifacts, and the JS/TS package surface.
+- Tightened npm/package positioning around Themis as an intent-first unit test framework for AI agents in Node.js and TypeScript.
+- Updated publish-facing docs to consistently frame Themis as an AI verdict engine for human and agent review loops.
+- Added `npm run pack:check` for npm publish payload validation.
+- Expanded the HTML report with quick actions, failure-first triage, richer file cards, and test-level drilldown.
+- Added embedded brand/report asset visuals to the README.
+- Added project-aware JS/TS runtime support for TSX, ESM `.js`, `tsconfig` path aliases, `setupFiles`, and `jsdom` environments.
+- Added first-party snapshots, mocks, run-diff artifacts, and watch mode for tighter agent rerun loops.
+- Added an in-repo VS Code extension scaffold for artifact-driven result viewing, reruns, and HTML report opening.
+- Refreshed README, AGENTS, and supporting docs to match the current package scope, JS/TS feature set, artifact contracts, and extension surface.
+
+## 0.1.0-alpha.1 - 2026-02-13
+
+### Added
+
+- Intent integration test suite with deterministic fixture coverage.
+- Async phase, ordering, cleanup, and failure-priority intent tests.
+- TypeScript definitions for package API, globals, and intent DSL.
+- Typecheck lane (`npm run typecheck`).
+- Benchmark gate command (`npm run benchmark:gate`) and config (`benchmark-gate.json`).
+- Branded CLI banner for human-readable reporters.
+- Snapshot-based CLI output tests with normalization for timing/path/version variance.
+- Agent test-authoring contract (`AGENTS.md`).
+- Community positioning doc (`docs/why-themis.md`).
+- Full API reference (`docs/api.md`) and release policy (`docs/release-policy.md`).
+- Formal JSON schema docs for agent and failures payloads.
+
+### Changed
+
+- Preferred intent phases are now `context/run/verify/cleanup`.
+- Legacy phase aliases remain supported for compatibility.
+- Added optional meme aliases (`cook/yeet/vibecheck/wipe`) and strict disable flag (`--no-memes`).
+- Hardened npm package metadata, exports, files whitelist, and publish config.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vitron.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# Themis
+
+<p align="center">
+  <img src="src/assets/themisLogo.png" alt="Themis logo mark" width="42" valign="middle">
+  <a href="https://github.com/vitron-ai/themis/actions/workflows/ci.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/vitron-ai/themis/ci.yml?branch=main&style=for-the-badge&label=THEMIS%20VERDICT%20PIPELINE&labelColor=111827&color=16a34a" alt="Themis verdict pipeline status" valign="middle">
+  </a>
+</p>
+
+Themis is an intent-first unit test framework for AI agents in Node.js and TypeScript.
+
+It is built to be the best test loop for agent workflows: deterministic reruns, machine-readable outputs, strict phase semantics, and a branded AI verdict engine for humans.
+
+<p align="center">
+  <img src="src/assets/themisReport.png" alt="Themis HTML verdict report" width="960">
+</p>
+
+## Contents
+
+- [Quickstart](#quickstart)
+- [Positioning](#positioning)
+- [Modern JS/TS Support](#modern-jsts-support)
+- [Commands](#commands)
+- [Agent Guide](#agent-guide)
+- [VS Code](#vs-code)
+- [Snapshots And Mocks](#snapshots-and-mocks)
+- [Intent Syntax](#intent-syntax)
+- [Config](#config)
+- [TypeScript](#typescript)
+- [Benchmark](#benchmark)
+- [Publish Readiness](#publish-readiness)
+- [Why Themis](docs/why-themis.md)
+- [API Reference](docs/api.md)
+- [Release Policy](docs/release-policy.md)
+- [Publish Guide](docs/publish.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+
+## Positioning
+
+- Best-in-class unit testing for AI agents in Node.js and TypeScript
+- Deterministic execution with fast rerun loops
+- Agent-native JSON and HTML reporting
+- AI verdict engine for human triage and machine automation
+
+## Modern JS/TS Support
+
+Themis is built for modern Node.js and TypeScript projects:
+
+- `.js`, `.jsx`, `.ts`, and `.tsx` support
+- ESM `.js` loading in `type: "module"` projects
+- `tsconfig` path alias resolution
+- `node` and `jsdom` environments
+- `setupFiles` for harness bootstrapping
+- first-party snapshots, mocks, and spies
+- `--watch` and `--rerun-failed` for tight local and agent rerun loops
+
+## Visuals
+
+- Real Themis brand mark: [`src/assets/themisLogo.png`](src/assets/themisLogo.png)
+- HTML verdict report art: [`src/assets/themisReport.png`](src/assets/themisReport.png)
+- Background art used by the report: [`src/assets/themisBg.png`](src/assets/themisBg.png)
+
+## Quickstart
+
+```bash
+npm install -D @vitronai/themis
+npx themis init
+npx themis test
+```
+
+Generate the next-gen HTML report:
+
+```bash
+npx themis test --reporter html
+```
+
+Use the AI-agent payload:
+
+```bash
+npx themis test --agent
+```
+
+Stay in a local rerun loop while editing:
+
+```bash
+npx themis test --watch --reporter next
+```
+
+## Why Themis
+
+See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators, and community messaging.
+
+## Reference Docs
+
+- API reference: [`docs/api.md`](docs/api.md)
+- Release policy: [`docs/release-policy.md`](docs/release-policy.md)
+- Publish guide: [`docs/publish.md`](docs/publish.md)
+- VS Code extension notes: [`docs/vscode-extension.md`](docs/vscode-extension.md)
+- Agent result schema: [`docs/schemas/agent-result.v1.json`](docs/schemas/agent-result.v1.json)
+- Failures artifact schema: [`docs/schemas/failures.v1.json`](docs/schemas/failures.v1.json)
+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)
+- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Security: [`SECURITY.md`](SECURITY.md)
+
+## Commands
+
+- `npx themis init`: creates `themis.config.json` and a sample test.
+- `npx themis test`: discovers and runs tests.
+- `npx themis test --next`: next-gen console output mode.
+- `npx themis test --json`: emits JSON result payload.
+- `npx themis test --agent`: emits AI-agent-oriented JSON schema.
+- `npx themis test --reporter html`: generates a next-gen HTML report file.
+- `npx themis test --reporter html --html-output reports/themis.html`: writes HTML report to a custom path.
+- `npx themis test --watch`: reruns the suite when watched project files change.
+- `npx themis test --workers 8`: overrides worker count (positive integer).
+- `npx themis test --environment jsdom`: runs tests in a browser-like DOM environment.
+- `npx themis test -u`: updates stored snapshots.
+- `npx themis test --stability 3`: runs the suite three times and classifies each test as `stable_pass`, `stable_fail`, or `unstable`.
+- `npx themis test --match "intent DSL"`: runs only tests whose full name matches regex.
+- `npx themis test --rerun-failed`: reruns failing tests from `.themis/failed-tests.json`.
+- `npx themis test --no-memes`: disables meme phase aliases (`cook`, `yeet`, `vibecheck`, `wipe`).
+- `npx themis test --lexicon classic|themis`: rebrands human-readable status labels in `next/spec` reporters.
+- `npm run validate`: runs test, typecheck, and benchmark gate in one command.
+- `npm run typecheck`: validates TypeScript types for Themis globals and DSL contracts.
+- `npm run benchmark:gate`: fails when benchmark performance exceeds the configured threshold.
+- `npm run pack:check`: previews the npm publish payload.
+
+## Agent Guide
+
+See [`AGENTS.md`](AGENTS.md) for the AI-agent test authoring contract used in this repository.
+
+Each run writes artifacts to `.themis/`:
+
+- `last-run.json`: full machine-readable run payload.
+- `failed-tests.json`: compact failure list for retry loops.
+- `run-diff.json`: diff against the previous run, including new and resolved failures.
+- `run-history.json`: rolling recent-run history for agent comparison loops.
+- `report.html`: interactive HTML verdict report.
+
+`--agent` output includes deterministic failure fingerprints, grouped `analysis.failureClusters`, stability classifications, and previous-run comparison data to help AI agents deduplicate and prioritize failures.
+
+Machine-facing reporters intentionally emit compact JSON. Agents and tooling should parse the payloads rather than depend on whitespace formatting.
+
+The HTML reporter is designed for agent-adjacent review workflows too: it combines verdict status, slow-test surfacing, artifact navigation, and interactive file filtering in one report.
+
+## VS Code
+
+The repo now includes a thin VS Code extension scaffold at [`packages/themis-vscode`](packages/themis-vscode).
+
+The extension is intentionally artifact-driven:
+
+- reads `.themis/last-run.json`, `.themis/failed-tests.json`, `.themis/run-diff.json`, and `.themis/report.html`
+- shows the latest verdict and failures in a sidebar
+- reruns Themis from VS Code commands
+- opens the HTML report inside a webview
+
+It does not replace the CLI. The CLI and `.themis/*` artifacts remain the source of truth.
+
+## Snapshots And Mocks
+
+Themis now ships first-party test utilities for agent-generated tests:
+
+```js
+mock('../src/api', () => ({
+  fetchUser: fn(() => ({ id: 'u_1', name: 'Ada' }))
+}));
+
+const { fetchUser } = require('../src/api');
+
+test('captures a stable UI contract', () => {
+  const user = fetchUser();
+  expect(fetchUser).toHaveBeenCalledTimes(1);
+  expect(user).toMatchSnapshot();
+});
+```
+
+Available globals:
+
+- `fn(...)`
+- `spyOn(object, methodName)`
+- `mock(moduleId, factoryOrExports)`
+- `unmock(moduleId)`
+- `clearAllMocks()`
+- `resetAllMocks()`
+- `restoreAllMocks()`
+- `expect(value).toMatchSnapshot()`
+
+## Intent Syntax
+
+Themis supports a strict code-native intent DSL:
+
+```js
+intent('user can sign in', ({ context, run, verify, cleanup }) => {
+  context('a valid user', (ctx) => {
+    ctx.user = { email: 'a@b.com', password: 'pw' };
+  });
+
+  run('the user submits credentials', (ctx) => {
+    ctx.result = { ok: true };
+  });
+
+  verify('authentication succeeds', (ctx) => {
+    expect(ctx.result.ok).toBe(true);
+  });
+
+  cleanup('remove test state', (ctx) => {
+    delete ctx.user;
+  });
+});
+```
+
+Preferred phase names are `context`, `run`, `verify`, `cleanup`.
+Legacy aliases are still supported (`arrange/act/assert`, `given/when/then`, `setup/infer/teardown`).
+Easter egg aliases are also available: `cook`, `yeet`, `vibecheck`, `wipe`.
+
+## Config
+
+`themis.config.json`
+
+```json
+{
+  "testDir": "tests",
+  "testRegex": "\\.(test|spec)\\.(js|jsx|ts|tsx)$",
+  "maxWorkers": 7,
+  "reporter": "next",
+  "environment": "node",
+  "setupFiles": ["tests/setup.ts"],
+  "tsconfigPath": "tsconfig.json"
+}
+```
+
+Modern JS/TS projects can opt into `environment: "jsdom"` for DOM-driven tests and `setupFiles` for hooks, polyfills, or harness bootstrapping.
+
+## TypeScript
+
+The package ships first-party typings for:
+
+- programmatic APIs (`collectAndRun`, `runTests`, config helpers)
+- global test APIs (`describe`, `test`, `intent`, hooks, `expect`)
+- typed intent context (`intent<MyCtx>(...)`)
+- project-aware module loading for `ts`, `tsx`, ESM `js`, `jsx`, `tsconfig` path aliases, and setup files
+
+Themis is designed to feel native in modern TypeScript projects without requiring a separate Babel or ts-node setup just to run tests.
+
+Use the global types in your project with:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@vitronai/themis/globals"]
+  }
+}
+```
+
+## Benchmark
+
+```bash
+npm run benchmark
+npm run benchmark:gate
+```
+
+Optional env vars:
+
+- `BENCH_FILES` (default `40`)
+- `BENCH_TESTS_PER_FILE` (default `25`)
+- `BENCH_REPEATS` (default `3`)
+- `BENCH_WORKERS` (default `4`)
+- `BENCH_INCLUDE_EXTERNAL=1` to include Jest/Vitest/Bun comparisons
+- `BENCH_MAX_AVG_MS` to override the gate threshold
+- `BENCH_GATE_CONFIG` to point `benchmark:gate` at a custom config file
+
+The benchmark always runs Themis and will include Jest/Vitest/Bun only when they are available locally.
+The default gate profile and threshold live in `benchmark-gate.json`.
+
+## Publish Readiness
+
+Before publishing a release:
+
+```bash
+npm run validate
+npm run pack:check
+```
+
+The npm package should ship a clean CLI, first-party typings, schemas, docs, and report assets.

package/benchmark-gate.json

@@ -0,0 +1,10 @@
+{
+  "profile": {
+    "files": 40,
+    "testsPerFile": 25,
+    "repeats": 3,
+    "workers": 4,
+    "includeExternal": false
+  },
+  "maxThemisAvgMs": 1500
+}

package/bin/themis.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { main } = require('../src/cli');
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error?.stack || String(error));
+  process.exit(1);
+});

package/docs/api.md

@@ -0,0 +1,210 @@
+# Themis API Reference
+
+This document defines the public API surface for Themis `0.1.0-beta.0`.
+
+## CLI
+
+## Command
+
+```bash
+themis test [options]
+themis init
+```
+
+## `themis init`
+
+Creates:
+
+- `themis.config.json` with default settings
+- `tests/example.test.js` sample test (if missing)
+
+## `themis test` options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `--json` | flag | Print full run payload JSON (`RunResult`). |
+| `--agent` | flag | Print AI-agent-oriented JSON payload (`themis.agent.result.v1`) with failure fingerprints and cluster analysis. |
+| `--next` | flag | Use next-gen human reporter. |
+| `--reporter spec\|next\|json\|agent\|html` | string | Explicit reporter override. |
+| `--workers <N>` | positive integer | Override worker count. Invalid values fail fast. |
+| `--environment node\|jsdom` | string | Override the configured test environment. |
+| `-w`, `--watch` | flag | Rerun the selected suite when watched project files change. |
+| `-u`, `--update-snapshots` | flag | Update snapshot files when `toMatchSnapshot()` values change. |
+| `--stability <N>` | positive integer | Run selected tests `N` times and classify stability (`stable_pass`, `stable_fail`, `unstable`). |
+| `--html-output <path>` | string | Output path for `--reporter html` (default: `.themis/report.html`). |
+| `--match "<regex>"` | string | Run only tests whose full name matches regex. |
+| `--rerun-failed` | flag | Rerun failures from `.themis/failed-tests.json`. |
+| `--no-memes` | flag | Disable meme intent aliases (`cook`, `yeet`, `vibecheck`, `wipe`). |
+| `--lexicon classic\|themis` | string | Human reporter terminology mode for `next/spec`. |
+
+## Exit behavior
+
+- Exit code `0`: all selected tests passed or were skipped.
+- Exit code `1`: any selected test failed, invalid usage, or runtime error.
+
+`--lexicon` does not affect machine payload contracts (`--json`, `--agent`, or artifacts).
+
+## Artifacts
+
+Each run writes to `.themis/`:
+
+- `last-run.json`: full run payload (`RunResult`)
+- `failed-tests.json`: failed subset (`themis.failures.v1`)
+- `run-diff.json`: diff against the previous run
+- `run-history.json`: rolling recent-run history
+
+Formal schemas:
+
+- `docs/schemas/agent-result.v1.json`
+- `docs/schemas/failures.v1.json`
+
+Human-facing artifact:
+
+- `.themis/report.html`: interactive HTML verdict report
+
+Agent payload details:
+
+- each `failures[]` entry includes a deterministic `fingerprint`
+- `analysis.failureClusters` groups failures by shared fingerprint
+- `analysis.stability` captures multi-run classifications and per-test status sequences
+- `analysis.comparison` reports delta stats plus new and resolved failures against the previous run
+
+## Config File (`themis.config.json`)
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `testDir` | string | `"tests"` | Root directory for discovery. |
+| `testRegex` | string | `"\\.(test\|spec)\\.(js\|jsx\|ts\|tsx)$"` | Regex for filenames. |
+| `maxWorkers` | integer | `max(1, cpuCount - 1)` | Parallel worker limit. |
+| `reporter` | `spec\|next\|json\|agent\|html` | `"next"` | Default reporter when no CLI override is set. |
+| `environment` | `node\|jsdom` | `"node"` | Test runtime environment. |
+| `setupFiles` | `string[]` | `[]` | Files loaded before each test file. |
+| `tsconfigPath` | `string \| null` | `"tsconfig.json"` | Project tsconfig used for TSX and alias-aware transpilation. |
+
+## Programmatic API
+
+Import:
+
+```js
+const themis = require('@vitronai/themis');
+```
+
+## `main(argv: string[]): Promise<void>`
+
+Programmatic entrypoint for CLI behavior.
+
+## `collectAndRun(filePath, options?): Promise<FileResult>`
+
+Runs tests in one file in-process with global API installation.
+
+Options:
+
+- `match?: string | null`
+- `allowedFullNames?: string[] | null`
+- `noMemes?: boolean`
+- `cwd?: string`
+- `environment?: "node" | "jsdom"`
+- `setupFiles?: string[]`
+- `tsconfigPath?: string | null`
+- `updateSnapshots?: boolean`
+
+## `runTests(files, options?): Promise<RunResult>`
+
+Runs multiple files in worker threads.
+
+Options:
+
+- `maxWorkers?: number`
+- `match?: string | null`
+- `allowedFullNames?: string[] | null`
+- `noMemes?: boolean`
+- `cwd?: string`
+- `environment?: "node" | "jsdom"`
+- `setupFiles?: string[]`
+- `tsconfigPath?: string | null`
+- `updateSnapshots?: boolean`
+
+## `discoverTests(cwd, config): string[]`
+
+Discovers test files from config.
+
+## `loadConfig(cwd): ThemisConfig`
+
+Loads `themis.config.json` and merges with defaults.
+
+## `initConfig(cwd): void`
+
+Creates `themis.config.json` if missing.
+
+## `DEFAULT_CONFIG: ThemisConfig`
+
+Default configuration object used by `loadConfig` and `initConfig`.
+
+## `expect(received)`
+
+Built-in matcher API:
+
+- `toBe(expected)`
+- `toEqual(expected)`
+- `toMatchObject(expected)`
+- `toBeTruthy()`
+- `toBeFalsy()`
+- `toBeDefined()`
+- `toBeUndefined()`
+- `toBeNull()`
+- `toHaveLength(expected)`
+- `toContain(item)`
+- `toThrow(match?)`
+- `toHaveBeenCalled()`
+- `toHaveBeenCalledTimes(expected)`
+- `toHaveBeenCalledWith(...args)`
+- `toMatchSnapshot(name?)`
+
+Machine-facing note:
+
+- `--json` and `--agent` emit compact JSON by design. Tooling should parse the payload rather than rely on pretty-printed formatting.
+
+## Global Test API
+
+When test files run under Themis, these globals are available:
+
+- `describe(name, fn)`
+- `test(name, fn)` and `it(name, fn)`
+- `beforeAll(fn)`, `beforeEach(fn)`, `afterEach(fn)`, `afterAll(fn)`
+- `expect(...)`
+- `fn(implementation?)`
+- `spyOn(object, methodName)`
+- `mock(moduleId, factoryOrExports?)`
+- `unmock(moduleId)`
+- `clearAllMocks()`
+- `resetAllMocks()`
+- `restoreAllMocks()`
+- `intent(name, define)`
+
+## Intent DSL
+
+Preferred phases:
+
+- `context`
+- `run`
+- `verify`
+- `cleanup`
+
+Compatibility aliases:
+
+- `arrange`, `act`, `assert`
+- `given`, `when`, `then`
+- `setup`, `infer`, `teardown`, `finally`
+
+Meme aliases (default enabled):
+
+- `cook`, `yeet`, `vibecheck`, `wipe`
+
+Disable meme aliases with `--no-memes` or programmatic `noMemes: true`.
+
+Ordering guarantees:
+
+- Arrange-phase aliases must run before Act/Assert.
+- Act-phase aliases must run before Assert.
+- At least one Assert-phase alias is required.
+- Cleanup phases always run after run phases.

package/docs/publish.md

@@ -0,0 +1,55 @@
+# Publish Guide
+
+This guide covers publishing Themis to npm.
+
+## Preconditions
+
+- npm account has publish access for scope `@vitronai`
+- you are logged in (`npm login`)
+- working tree is clean
+- quality checks pass
+
+## Release Checklist
+
+1. Update version in `package.json` (`npm version ...`).
+2. Update `CHANGELOG.md`.
+3. Confirm the public messaging still matches the project:
+   - best-in-class unit test framework for AI agents in Node.js and TypeScript
+   - AI verdict engine for human and agent review loops
+4. Run:
+
+```bash
+npm run validate
+npm run pack:check
+```
+
+5. Review publish payload:
+
+```bash
+npm pack --dry-run
+tar -tf vitronai-themis-*.tgz
+```
+
+6. Publish:
+
+```bash
+npm publish --access public
+```
+
+## Post Publish
+
+Verify installation:
+
+```bash
+npx @vitronai/themis test --help
+```
+
+If needed, deprecate a release:
+
+```bash
+npm deprecate @vitronai/themis@<version> "<message>"
+```
+
+## VS Code Extension
+
+The scaffold under `packages/themis-vscode` is a separate release surface. It does not ship in the npm tarball and can be published later on its own schedule.

package/docs/release-policy.md

@@ -0,0 +1,54 @@
+# Release Policy
+
+This document defines release expectations for Themis.
+
+## Current Stage
+
+Current line: `0.1.0-beta.x`
+
+Beta means:
+
+- the core CLI, artifact, and JS/TS package shape should be considered mostly stable
+- compatibility remains a deliberate goal across beta builds
+- breaking changes are still possible, but they should be uncommon and called out clearly
+
+## Versioning Model
+
+Themis follows semantic versioning semantics with pre-release tags:
+
+- `0.1.0-alpha.N`: unstable early pre-release
+- `0.1.0-beta.N`: pre-release with mostly stable product shape
+- `0.1.0`: first stable contract baseline
+- `0.1.x`: backward-compatible fixes and minor enhancements
+- `0.2.0+`: intentional breaking changes with migration notes
+
+## Compatibility Rules During Beta
+
+- CLI flags should remain stable unless a clear product issue requires change.
+- Programmatic API should prefer additive changes over renames or removals.
+- Payload schemas keep explicit `schema` identifiers (`themis.agent.result.v1`, `themis.failures.v1`).
+- If schema behavior changes in a breaking way, schema ID must bump.
+
+## Deprecation Policy
+
+- New deprecations are documented in `CHANGELOG.md`.
+- Deprecated APIs should keep at least one pre-release cycle before removal when practical.
+- Meme aliases can be disabled any time with `--no-memes`; strict environments should use this flag.
+
+## Quality Gates
+
+Before publishing:
+
+- `npm test`
+- `npm run typecheck`
+- `npm run benchmark:gate`
+
+## Publishing Policy
+
+- Publish target: npm public package `@vitronai/themis`.
+- Required metadata: license, repository, bugs URL, homepage.
+- Recommended command:
+
+```bash
+npm publish --access public
+```