Tiny Context preserves durable project facts and installs a short development contract in AGENTS.md. It helps a coding agent find project-specific requirements and maintain them without prescribing an engineering workflow.
This source version is 0.12.1, configuration schema 5, update mode upgrade-required for schema-4 installations. See the migration notes.
Requires Node.js 24 or newer. Install the package version you intend to use, then run its local CLI:
npm install --save-dev project-tiny-context-harness
npx --no-install ty-context initFor an unreleased source checkout, build and install its actual tarball instead of assuming the published package contains these changes.
Plain init creates only AGENTS.md, .agent/config.yaml, project_context/global.md and project_context/context.toml. It preserves existing files and leaves project facts as TODO until known. Transient file-maintenance locks may create tmp/ty-context; they are not task state. Use --adopt for an existing project. An explicit --harness-folder .codex stores that optional location in package.json; changing an existing installation's root requires separate migration.
No architecture, Area, design system, role Skill, Hook, Makefile, tools directory or CI workflow is installed by default. Existing design documents and confirmed decisions remain useful inputs.
AGENTS.md is the managed startup entry. A root AGENTS.override.md can shadow it; doctor reports that observable condition. Hosts and nested instruction scopes can differ: file installation does not prove that the current model loaded or followed the contract. No global host settings are modified.
Save goals and non-goals, ownership and dependency boundaries, confirmed decisions with reasons, project constraints and repeatable operation/source entrypoints. Reference precise values in their real source rather than copying code. Context describes intended meaning; implementation may disagree and need repair.
There are no mandatory headings, task-progress fields, stable Fact IDs or source-line limits. TODOs and historical test records are allowed. Update Context when durable facts change. Temporary exports and optional handoff notes are not another long-term source of truth.
New defaults contain project_context/global.md plus explicit project selections. architecture.md has no special default status in schema 5. context.toml is routing metadata, not default body text.
npx --no-install ty-context context list --default
npx --no-install ty-context context list --default --json
npx --no-install ty-context context inspect project_context/global.mdThe query shows paths, reasons, diagnostics and whether the set is complete. Invalid manifests return a non-success status; partial results are never a complete empty set.
The CLI is optional for reading. Offline, read global.md and use the manifest's direct default_files, default Area, read_policy = "default" nodes and their transitive default_children. Direct files and default Areas do not themselves seed child traversal. Child edges preserve existing semantics, including a referenced never-default node. Legacy always, optional and never-default names do not imply new selection behavior; diagnostics explain legacy metadata. Do not reinstall the CLI or repeat a query when the set is already known and unchanged. Resolve uncertainty affecting the task; unrelated uncertainty need not freeze all work.
Example optional routing:
default_files = ["project_context/architecture.md"]
[[areas]]
id = "payments"
root = "src/payments"
context = "project_context/areas/payments.md"
kind = "service"
[[context]]
path = "project_context/areas/payments/recovery.md"
role = "domain"
read_policy = "on-demand"
triggers = ["payment recovery"]default_files selects literal body files without activating their children. Areas and workspace folders can be sparse. Ordinary search and inspection discover additional owners; reading them does not authorize changing unrelated projects.
Locate owners from the affected implementation, not only manifest trigger words. Before a substantial capability change, the development contract asks agents to inspect consumers, state/data ownership and dependency direction, and to reuse suitable project and target-platform capabilities. Shared responsibilities that need to evolve together merit a shared owner and migration of affected consumers; visual similarity or a repetition count alone does not. New dependencies or substantial custom machinery merit bounded investigation of material gaps in mature alternatives, reusing decisions whose conditions still hold. A local style or condition fix does not require a fresh architecture or library survey.
Keep sources, visuals, prototypes, assets and exploration records outside Context, in an existing resource location or optionally docs/design-resources/. The existing page, component or feature owner keeps the current adopted entry, applicable scope and confirmed decisions with reasons. Shared resources belong to a shared owner; other owners link there. Global Context needs only useful brief navigation, not resource inventories or generation history.
For example, an existing owner can declare a local entry:
<!-- ty-context-controlling-source domain="design" path="docs/design-resources/web/results/ADOPTED.md" -->
This entry controls result-list composition and assets for desktop, light theme
and populated results. Business and state meaning remain with this owner;
shared visual rules remain with the existing shared design owner. Other regions,
themes and states retain their current requirements.The entry can map several nonconflicting scopes to different resources; one applicable scope has one current basis. A newer candidate or a preference during exploration does not supersede an adopted resource. Authorized partial adoption replaces only its scope, reconciles affected rules and preserves the remaining valid references. Images do not silently override business, accessibility or platform constraints, and stale rules must not silently negate an authorized design change. Keep indices as navigation to the decision owner, repairing relevant stale references without concealing unfinished implementation.
Development follows defaults and affected owners to their current entry, then opens the relevant sources, actually views current visuals and inspects necessary prototypes or behavior descriptions. Adopted resources are implementation requirements within their declared scope. Compare the real target runtime under meaningful conditions such as viewport, fonts, theme, data and dynamic state, and repair deviations. The entry identifies illustrative content outside production scope and project adaptation rules; different screen sizes need not be scaled into one image. Report missing inputs, conflicts, platform limits and unverified scope. Ordinary repairs reuse existing resources; they do not require regeneration, another adoption decision or invocation of a resource Skill.
The existing declaration checks a repository-relative local UTF-8 entry. It does not recursively check linked assets or declarations inside that entry, load images, visit external links or add resources to default Context. Declare a shared entry once in its owning Context: duplicate declarations of the same target are diagnosed, even in the same domain. Different targets with overlapping prose scopes require review; the validator cannot infer those collisions. Resource usability and runtime checks are explicit task work. Structural success proves neither adoption, agent viewing, aesthetics nor production correctness.
The package includes assets/skills/design-resource/, containing SKILL.md, references/stitch.md, references/adoption.md and agents/openai.yaml. The capability uses Stitch for visual generation and design revisions, with official MCP first and the authenticated official Stitch website when a needed operation is unavailable through MCP. It preserves actual editable sources and exports, records reference purpose and necessary versions, distinguishes original outputs from revisions, and reports screenshot-only or missing-input limits honestly. Scope and iterations follow the task; project Context supplies style and design rules. Read the resource capability, Stitch operation reference and adoption guidance, or the corresponding installed files.
The Stitch reference covers live tool/schema discovery, project and screen identity, initial generation, selected-screen edits, requested variants, uncertain-write recovery and retrieval of original HTML/images. It requires actual refreshed output inspection and avoids duplicate generation after an uncertain timeout. Tool signatures are checked against the connected service; a listed tool or successful transport is not proof of a usable design. A local image path in a prompt is not an upload: use an available Stitch attachment/upload operation or the official web flow. If neither Stitch route works, report the missing capability and retain the input bundle; do not silently switch providers. Existing-resource reading and adoption can continue independently.
agents/openai.yaml declares the Stitch MCP dependency for hosts that support this metadata. The connection uses https://stitch.googleapis.com/mcp; configure authentication through the host's supported mechanism using existing authorized credentials. The Skill does not install a server, obtain credentials or edit global settings. Copying or reading a Skill alone does not make its MCP available, and reading the base from a project wrapper does not automatically load the base's metadata. Supporting hosts can use the dependency hint; other hosts need the connection configured separately. Keep authentication values out of project files and logs. See the official connection configuration and Stitch setup.
To opt in, use a project Skill that reads the packaged capability as described below, or copy the entire node_modules/project-tiny-context-harness/assets/skills/design-resource/ directory into your host's supported project Skill location, preserving references/ and agents/. Choose an unused destination; if a local copy exists, review and merge it instead of overwriting project changes. Consult your host's discovery rules and reload as needed. Project Skills and copied Skills are project-owned: init, sync and upgrade do not install or update them. No design directory or resource template is created automatically.
The managed AGENTS.md block remains the generic development entry; this optional Skill is for resource work and does not restore retired design commands or replace the startup contract. An old development Skill does not need to remain enabled alongside it. Explicit upgrade handles supported historical managed assets; project-authored Skills and instructions still need their own review. Already loaded instructions do not change when a file is synced, and host loading is distinct from file installation.
For projects with their own resource Skill, keep that entry and compose the packaged capability into it. The project entry can add target-platform handling, reference conventions, export/integration procedures and project-specific checks while reading design requirements from their existing Context owners. Stitch remains the generator and visual editor; a wrapper must not silently substitute another provider. Other tools may inspect or package results and perform an explicitly needed downstream conversion. Route resource tasks to the project entry through the host's Skill discovery or the project's own AGENTS prose. There is no automatic extends field or extension-directory scan.
An illustrative project Skill can contain:
Read the project's default Context and affected owners.
Read node_modules/project-tiny-context-harness/assets/skills/design-resource/SKILL.md
from the repository root; resolve its relative references from that file's directory.
Use its Stitch route for generation and visual revision, together with this Skill's
target-platform and integration methods. Keep durable design rules in their owning Context.Use the actual installed package location if the project has a different dependency layout. Keep the project Skill outside node_modules and the managed AGENTS block. Referencing the packaged base avoids maintaining another copy of its generic instructions: an intentional dependency update updates the base, while local extension methods remain project-owned. Review upstream changes for conflicts with those methods. If a frozen local copy is preferred, update it by deliberate comparison and merge; sync does not refresh it. If the referenced package is unavailable, report the missing base instead of pretending it was read.
Confirmed style, visual principles, business meaning and interaction rules belong in Context, with their scope and rationale. Design techniques and tool procedures belong in the project Skill. Exact token values, component implementations and design-source entities remain in their actual code or design files; Context links to them instead of duplicating a second inventory. A project does not need to rename or consolidate its existing Context files to use this capability.
For an existing schema-5 installation, install a package version containing this capability and run its local ty-context sync to refresh the managed startup block. This addition does not require a schema migration: project Context, resources, local Skills and prose outside that block remain project-owned. Retain existing adopted entries and resource scopes; moving methods into a wrapper does not require regenerating or re-adopting designs. Review overlapping generic instructions in the local Skill when choosing to reuse the base. Schema-4 installations still follow the explicit upgrade procedure below. These are the package's supported boundaries, not a claim that any particular project's current installation has already been inspected or migrated.
npx --no-install ty-context context create --path project_context/payments.md --role domain
npx --no-install ty-context context register --path project_context/payments.md --role domain
npx --no-install ty-context context register --path project_context/payments.md --role domain --apply
npx --no-install ty-context context move --from project_context/payments.md --to project_context/billing.md
npx --no-install ty-context context transaction status
npx --no-install ty-context context transaction complete
npx --no-install ty-context context transaction rollback
npx --no-install ty-context syncCreate publishes an unregistered scaffold. Register and move preview first; --apply uses the existing path checks, byte/identity comparisons and recoverable file journal. No force bypass is provided. Context mutations use context-mutation-journal-v3; the compatible current recovery parser can read context-mutation-journal-v2. Unrecognized pre-v2 journals require manual recovery with a matching old version. An old schema-4 transaction must be settled by its compatible old CLI before schema migration, even if its journal format is otherwise familiar.
Sync replaces only the managed startup block and preserves surrounding user prose. Schema mismatches, unfinished upgrades/Context transactions and conflicting writes stop relevant maintenance. Several filesystem replacements are not one atomic transaction; do not overwrite a conflicting file to make recovery pass.
npx --no-install ty-context validate-context
npx --no-install ty-context doctorChecks cover manifest parsing, registered and direct-default paths, duplicate identities, portability/path safety and explicitly declared local dependencies using this existing syntax:
<!-- ty-context-controlling-source domain="technical" path="docs/api.md" -->Allowed domains are product, technical, design, acceptance and external. This declaration requests local UTF-8 file validation. Arbitrary prose paths, ordinary Markdown links, examples, remote links and future generated outputs are not mandatory existence checks. Validation does not run generators, access the network, establish factual truth or certify product quality.
Use project tests and actual observations appropriate to the change. The short contract asks agents to preserve user requirements, work within authorization, implement and verify, repair failures, maintain changed facts and report material uncertainty. It requires no separate Skill, fixed report or completion Gate.
For CI, add ty-context validate-context to your own workflow. Tiny Context does not remove independent project lint, tests or security requirements.
npx --no-install ty-context upgrade --check
# Stop relevant old host sessions before acknowledging this precondition:
npx --no-install ty-context upgrade --sessions-stoppedAutomatic retirement supports the pinned schema-4/package-0.11.0 baseline. It preserves the exact normalized default body path set, backs up planned changes, removes exact owned old assets, preserves mixed user content and only retires the current worktree's binding. Backups and pending recovery live under tmp/ty-context, outside host-discovered Skills and default Context. Interrupted upgrades resume through the same explicit command; ordinary sync refuses unfinished publication.
A pending old Context transaction blocks retirement before schema or manifest changes. Use the installed compatible 0.11.0 recovery tool; never substitute @latest. If its old binding conflicts, use its legitimate abandon/end path first, without requiring Final Gate or deleting locks. Unreadable journals are errors, not absence.
Software migration and project-information review are reported separately. Modified executable guidance blocks replacement. Historical records remain untouched. Current declared symbolic/compiler-dependent resources and recognized retired build commands need extraction or replacement with provenance before switching. Ordinary Markdown and direct JSON/YAML values remain readable; there is no general legacy compiler or structured-ID adapter. Review current task inputs, selected resources and other build entrypoints that the bounded inspection does not interpret. Do not regenerate a design to replace a lost adopted decision.
Long-Task, DSA/DRA, role workflows, design preflight/acceptance, observer proofs, routing rankings and modularity gates are retired. Old command names fail with a retirement diagnostic; they do not return a weaker success. New schema guards cannot repair old binaries retroactively: some old commands may change profile configuration before rejecting schema 5. Baseline old bare init can also select a different root before checking schema and reinstall old startup assets. Fixed-root old sync/init reject schema 5; this does not protect against root reselection. Such mixed installations/configuration are unsupported and rejected by new writes. Start a fresh host session after migration so previously loaded instructions do not continue to apply.
ty-context export-context --help lists temporary full/code/source-pack exports and their scope. Export output is not Context or product evidence; review redaction warnings before sharing.
Source-pack updates only its recorded, unchanged generated files. It preserves unlisted user files and unowned historical directories, and refuses to overwrite edited generated output. Export sets are not atomic multi-file transactions.
In this source repository:
npm ci
npm run build --workspace project-tiny-context-harness
npm test
node packages/ty-context/dist/cli.js package sync-source
node packages/ty-context/dist/cli.js package check-sourceCanonical guidance and Context rules live in .codex/ty-context-managed; source mappings derive package assets and README. Regression includes Context/file safety, actual pinned old-version recovery and tarball consumers. Tests prove those behaviors and distributed text, not model compliance or an unmeasured efficiency gain.