The packages project is the open-source package monorepo for moldea. It develops the first-class public and private packages, shared internal packages, private applications, compatibility data, conformance fixtures, documentation, and generation tooling that implement and present the deterministic repository-reading and repository-format ecosystem.

The repository is intentionally separate from the hosted platform monorepo. It contains reusable package products and their shared development infrastructure, not Cloud applications, hosted APIs, runtime infrastructure, or deployment configuration.

@moldea.ai/repository, @moldea.ai/repository-fs, @moldea.ai/core, @moldea.ai/adapter-anthropic, @moldea.ai/adapter-claude-agent-sdk, @moldea.ai/adapter-cloudflare-agents, @moldea.ai/adapter-eve, @moldea.ai/adapter-google-genai, @moldea.ai/adapter-langchain, @moldea.ai/adapter-langgraph, @moldea.ai/adapter-openai, @moldea.ai/adapter-openai-agents-sdk, @moldea.ai/adapter-vercel-ai-sdk, @moldea.ai/cli, and @moldea.ai/website-ui form the available package set. Repository version 2 owns bounded source-neutral pages, ranges, comparisons, and snapshot identities. Repository FS version 2 provides lazy, resource-limited local access without an eager repository-wide inventory. Core version 4.0.1 provides content-free validation and paged agent assignments, explicit canonical content ranges, cheap changed-path matching, and per-agent adapter contexts. The provider and agent-SDK adapters contribute static evidence through those bounded contexts. CLI version 8.0.0 composes the packages into a schema 4 read-only executable with independently keyed agent assignments, a 64 KiB default JSON page, and a 1 MiB maximum JSON page. Website UI provides the shared Astro and Tailwind foundations for moldea public websites. The built-in custom runtime and package-backed anthropic, claude-agent-sdk, cloudflare-agents, eve, google-genai, langchain, langgraph, openai, openai-agents-sdk, and vercel-ai-sdk runtimes are available for deterministic inspection under their published eligibility and source-pattern contracts. Real tarball installation and execution remain the release boundary for every package version.

The official Repository Format version 1 specification is maintained in this repository and published at https://packages.moldea.ai/repository-format/. It is the public contract for canonical files, manifest properties, deterministic validation, semantic evaluation boundaries, and conformance. @moldea.ai/core remains its executable reference implementation.

The remaining product and package design specifications are maintained in the platform repository:

• moldea packages: monorepo organization, package catalog, dependencies, distribution, and shared conventions.
• @moldea.ai/repository: source-neutral repository-reader contract and in-memory reference implementation.
• @moldea.ai/repository-fs: coherent local filesystem reader.
• @moldea.ai/core: deterministic repository-format interpretation and indexing.
• @moldea.ai/cli: read-only Git working-tree composition and executable contract.
• @moldea.ai/adapter-anthropic: TypeScript Anthropic Messages API inspection target.
• @moldea.ai/adapter-claude-agent-sdk: TypeScript Claude Agent SDK query and programmatic-subagent inspection target.
• @moldea.ai/adapter-cloudflare-agents: TypeScript Cloudflare Think and AIChatAgent inspection targets.
• @moldea.ai/adapter-eve: TypeScript Eve filesystem-agent inspection target.
• @moldea.ai/adapter-google-genai: TypeScript Google Gen AI SDK inspection target.
• @moldea.ai/adapter-langchain: TypeScript LangChain createAgent inspection target.
• @moldea.ai/adapter-langgraph: TypeScript LangGraph StateGraph and Functional API inspection targets.
• @moldea.ai/adapter-openai: TypeScript OpenAI Responses API inspection target.
• @moldea.ai/adapter-openai-agents-sdk: TypeScript OpenAI Agents SDK agent and handoff inspection target.
• @moldea.ai/adapter-vercel-ai-sdk: TypeScript Vercel AI SDK agent and generation inspection targets.
• Runtime Adapter Contract: deterministic extension contract for official adapters.
• Runtime Compatibility Matrix: canonical compatibility-data contract and initial adapter inventory.

The specification documents remain the design authority. Implemented compatibility artifacts derive from the canonical technical matrix and website maturity source and remain subject to their conformance requirements.

.github/
  workflows/                   # Verification, npm publication, and GitHub Pages deployment
apps/
  website/                     # Private Astro packages-documentation application
    content/                   # Getting-started guide and runtime target maturity
compatibility/
  runtimes.yaml                # Canonical technical runtime compatibility inventory
configs/
  typescript/                  # Shared environment and declaration configs
  vite/                        # Shared ESM library build configuration
  vitest/                      # Shared package test configuration
fixtures/                      # Repository-wide conformance fixtures
docs/
  npm-releases.md             # Trusted npm publication and bootstrap process
  runtime-compatibility.md     # Generated compatibility presentation
specifications/
  repository-format.md         # Official Repository Format version 1 contract
packages/                      # Private shared implementation packages
  adapter-static-analysis/    # Provider-neutral adapter source-analysis primitives
projects/
  adapter-anthropic/           # Anthropic Messages API runtime adapter
  adapter-claude-agent-sdk/    # Claude Agent SDK runtime adapter
  adapter-cloudflare-agents/  # Cloudflare Think and AIChatAgent runtime adapter
  adapter-eve/                # Eve filesystem-agent runtime adapter
  adapter-google-genai/        # Google Gen AI generate-content runtime adapter
  adapter-langchain/           # LangChain createAgent runtime adapter
  adapter-langgraph/           # LangGraph StateGraph and Functional API runtime adapter
  adapter-openai/              # OpenAI Responses API runtime adapter
  adapter-openai-agents-sdk/   # OpenAI Agents SDK runtime adapter
  adapter-vercel-ai-sdk/       # Vercel AI SDK runtime adapter
  cli/                         # Read-only local command-line composition
  core/                        # Deterministic repository-format interpretation
  repository/                  # Source-neutral reader contract and memory reader
  repository-fs/               # Explicit local-filesystem repository reader
  website-ui/                  # Shared Astro and Tailwind website foundations
scripts/
  runtime-compatibility/       # Matrix validation and deterministic generation
eslint.config.js
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
tsconfig.json
turbo.json
vitest.config.ts
vitest-integration.config.ts

Every immediate child of projects/ is an independently meaningful first-class package. Every immediate child of packages/ is a private shared implementation package. Every immediate child of apps/ is a private application built from or around the ecosystem. Applications do not appear in the package catalog, carry no independent public package compatibility promise, and may depend on projects or internal packages; projects and internal packages never depend on applications.

/docs is reserved for concise, durable project concepts and processes. API and HTTP endpoint documentation belongs outside /docs, in the owning project's established documentation location.

The website owns its getting-started guide, display-only discovery copy, and synthetic examples generated through real public package exports and the declared CLI executable. Its internal capability catalog covers Core operations and diagnostics, runtime evidence, reader behavior, and CLI commands. Package documentation and canonical runtime support data remain authoritative; see apps/website/README.md for generation and verification ownership.

An arrow means that the package on the left depends on the package on the right.

repository-fs       → repository
core                → repository
adapter-*           → core
cli                 → repository + repository-fs + core + active adapter packages
packages-website    → website-ui + core + repository + repository-fs + cli + adapter-*
                     (deterministic packages are build-time dependencies)

Shared internal packages may support first-class projects but never depend on them. Published packages must bundle private internal implementation or otherwise ensure that private imports and declarations do not leak into the consumer artifact.

The catalog records approved architecture, not implementation or release status. The custom adapter remains built into @moldea.ai/core and has no separate package project.

The initial public tooling, instruction-consumption, and package-backed adapter phase is limited to the Node.js ecosystem. Runtime Compatibility Matrix version 2 therefore records npm packages only and interprets every package range with node-semver semantics.

• Node.js 24.15.0 or newer within Node.js 24 for repository development
• pnpm 11.9.0

Development-tool requirements are intentionally separate from consumer runtime guarantees. Node-specific packages declare and verify the runtime ranges defined by their focused specifications. Environment-neutral packages must not import Node.js modules or inherit Node globals.

Install the pinned workspace dependencies:

pnpm install

Run the complete repository verification workflow:

pnpm format:check
pnpm lint
pnpm typecheck
pnpm build
pnpm test

Useful focused commands:

Root docs:check, docs:generate, website:dev, and website:check run website:prepare first. Direct website-package commands are low-level tasks and require that preparation. Root website:build uses Turbo's dependency ordering. The website-specific tasks in turbo.json own source/environment cache inputs and restore the generated model together with its matching static artifact. An uncached website-only cleanup runs before building or restoring those outputs so removed pages cannot survive a cache hit.

Public JavaScript artifacts are ESM-only unless a focused specification establishes another format. Vite bundles JavaScript in library mode with explicit entry points, stable output names, source maps by default, and deliberate dependency externalization. Packages may omit JavaScript source maps when bundling a private workspace implementation would expose private import paths in published artifacts. TypeScript performs strict source checking and emits declarations separately so public types remain a first-class package artifact. Package build scripts clean their output directory once, run Vite, and then emit declarations; the shared Vite configuration does not delete output owned by another build step. Website UI additionally publishes source Astro components and CSS because the consuming Astro application owns their compilation and Tailwind source scan.

Environment-neutral packages extend configs/typescript/environment-neutral.json; Node-specific packages extend configs/typescript/node.json. Declaration builds use the corresponding *-library.json configuration and set package-local rootDir and outDir values.

Package tests use Vitest without global test APIs. Tests are colocated with the source modules they exercise, and Node and non-React tests use the *.test-unit.ts, *.test-integration.ts, and *.test-e2e.ts names for the categories they own. Each package exposes a granular script for every category it contains, and its test command runs unit, integration, then end-to-end correctness suites when present. Shared conformance fixtures live at repository level when they represent a contract implemented by multiple packages.

Unit tests retain Vitest's short default timeout and may read static fixtures, but their correctness must not depend on exercising real filesystem, compiler-program, package-manager, or child-process boundaries. Integration tests share a 120-second cross-platform test and hook budget through configs/vitest/test.config.ts; individual overrides are reserved for operations with measured requirements beyond that budget. Tests that depend on real workspace packages, temporary filesystems, compiler programs, package installation, or child processes belong to the integration suite even when the production API is synchronous.

Repository FS, the Anthropic, Claude Agent SDK, Cloudflare Agents, Eve, Google Gen AI, LangChain, LangGraph, OpenAI, OpenAI Agents SDK, and Vercel AI SDK adapters, and CLI runtime composition are tested at packed-consumer boundaries. CI builds the required public tarballs on the pinned development runtime, then installs and executes the artifacts with package scripts disabled and strict engine validation on Node.js 22.11.0, latest Node.js 22, Node.js 24.11.0, latest Node.js 24, and Node.js 26.8.1. The adapter harnesses exercise each installed public export and inspection boundary, while the CLI harness verifies installed package identities and real version, composition, validate, and inspect commands through the packed composition. Repository's optional testing subpath is also exercised with strict peers on Vitest 1.0.0, 2.0.0, 3.2.4, and 4.1.10; a separate pnpm 11.21.0 consumer proves that installing the complete CLI closure preserves an existing root Vitest 3.2.4. This keeps consumer runtime guarantees independent from the newer runtime required by repository development tooling.

Turborepo derives build order from declared workspace dependencies. Package dependencies must remain explicit and acyclic, and no task may rely on workspace enumeration order or undeclared cross-project state.

Each runtime adapter's docs/binding-example.md contains one marked virtual file set that its public-entrypoint integration tests inspect through Core. Edit those Markdown blocks directly; do not maintain a second fixture copy. configs/package-documentation/example reads only the selected document, and existing packed-documentation checks require the example to ship. These checks establish static relationships, not live SDK execution or fresh paid qualification evidence.

Every implemented public project owns its full documentation under projects/<project>/docs/**. The cross-package Repository Format contract is owned by specifications/repository-format.md. Package specifications, implementation, tests, public exports, manifests, technical compatibility source, and package-owned documentation are authoritative; the website discovers, validates, renders, searches, and presents visitor-facing package documentation while owning target maturity. Website UI remains a shared public package with repository-owned documentation, but its documentation pages are not published on the packages website. Concise package READMEs remain the GitHub and npm entry points. All ten runtime adapters also publish their package-owned docs for offline use. README links route to the relevant local guide; generated API references and compatibility pages use explicit HTTPS links. Artifact checks require every documentation page and local link target to appear in the package manager's packed inventory.

Generated files are not edited directly. Repository Format changes begin in specifications/repository-format.md, whose metadata, required sections, manifest property reference, internal anchors, and marked complete example are verified before publication. Technical runtime compatibility changes begin in compatibility/runtimes.yaml, while website target maturity is edited only in apps/website/content/runtime-target-maturity.yaml. The website build requires an exact one-to-one match between those maturity entries and the matrix targets and publishes their deterministic combined view at https://packages.moldea.ai/compatibility/runtimes.json. A target may link only to its canonical profile on https://skill.moldea.ai; qualification execution, fixtures, caches, and results remain owned by the skill repository. Run pnpm compatibility:generate to update docs/runtime-compatibility.md. The website model, public Repository Format page, public compatibility JSON, API reference, route manifest, search input, and llms.txt are generated during documentation checks and builds from their canonical repository sources; none is maintained independently. CI reruns the applicable generators and fails when canonical inputs are invalid, routes contradict one another, public exports are omitted, links break, or the static artifact is incomplete.

The coding agent that changes a package or compatibility claim is responsible for reconsidering every affected representation and synchronizing only those that actually changed. Depending on the change, this includes implementation, public exports, package manifest, package specification, README, package-owned documentation, generated API reference, examples, tests and fixtures, compatibility source, generated compatibility documentation, website target maturity, website pages and navigation, compatibility pages, and llms.txt.

Before completing any change, the coding agent must audit the complete diff against its base commit using the npm release project's release-relevance rules. Every changed existing public project selected for publication must receive a greater canonical stable version in the same change, while a newly introduced public project must declare a canonical stable version. The agent must also synchronize directly affected compatible-major workspace dependencies, the lockfile, generated compatibility documentation, package documentation, and version assertions, then run pnpm release:check-changes <base-commit> <current-commit> when both commits are available.

Reconsider and synchronize when affected. Do not edit unrelated surfaces merely because they exist.

Generated output changes through its canonical source and generator. Technical compatibility claims come only from compatibility/runtimes.yaml, and target maturity comes only from the packages website maturity file. Package documentation is part of package maintenance. A website-only maturity change does not create an npm release. Documentation under projects/<project>/docs/** is release-relevant when either compared manifest includes it in the npm file inventory; otherwise it remains website-only. All runtime adapters publish docs, so edits to their shipped guides require an adapter release. Committed manifests, including default npm inclusion and root-level file patterns, determine this boundary without a separate package allowlist. README.md, package.json, LICENSE, declared package files, public exports, and source remain release-relevant; combining docs with a release-relevant change still selects the project.

apps/website is the private Astro static application for the public packages ecosystem. It consumes @moldea.ai/website-ui through the workspace protocol for shared design tokens, interaction states, theme behavior, search behavior, sanitized Markdown, responsive shells, and reusable components while retaining local ownership of navigation data, content generation, page composition, SEO identity, and assets. It uses SITE_URL and BASE_PATH; the defaults match the established https://packages.moldea.ai/ custom domain, while explicit inputs continue to support a GitHub project-site base path without component changes. See its application README for focused commands and source boundaries.

The /capabilities/ page introduces six capability families through eighteen executed illustrations in compact, single-open accordions: structure, agents, decisions, runtime wiring, repository access, and CLI operations. Examples show realistic maintenance mistakes, including undeclared variables, stale policy copies, disconnected instruction loaders, and a failed CI check for a missing reference. Shared file previews, result summaries, and optional dialogs show the examples; package references provide the full technical scope. Search indexes only the visible coverage, sections, and illustrations. The complete executable catalog remains internal verification evidence. Navigation, llms.txt, and the canonical sitemap link the page. Results come from build-time synthetic repositories, never visitor files or runtime execution.

Pull requests run non-deploying repository verification, including documentation discovery, generated API, route, and local search-index checks, website unit and browser tests, type checking, linting, the complete static build, internal-link validation, and final artifact inspection. Relevant pushes to main trigger the Pages workflow, read the configured host and base path from GitHub Pages, build the canonical HTTPS origin from that host, rebuild from the exact merged commit, and deploy with GitHub's official Pages artifact flow. After a successful push deployment, the workflow submits https://packages.moldea.ai/sitemap-index.xml to the sc-domain:moldea.ai Google Search Console property. npm publication remains a separate workflow and is never triggered merely by website or full-documentation changes.

Repository owners must perform one initial GitHub setting if Pages is not already enabled: open Settings → Pages → Build and deployment, set Source to GitHub Actions, and save. This is one-time enablement, not a publication step. After it is enabled, relevant merges and direct pushes publish automatically; a failed build never uploads or deploys a partial replacement.

Search Console submission requires the GOOGLE_SEARCH_CONSOLE_CREDENTIALS Actions secret, configured at the moldea-ai organization level with this repository in its selected-repository policy. The secret contains the JSON key for moldea-sitemap-submitter@moldea-prod.iam.gserviceaccount.com, which must remain an owner of the Search Console property and retain Service Account Token Creator on itself. Manual workflow dispatches deploy the selected ref but do not submit its sitemap. A submission failure is reported after deployment and does not roll back the published Pages artifact.

A push to main automatically selects every release-relevant changed public project and uses the npm workflow as the commit's sole CI and release orchestrator; pull requests invoke the reusable CI workflow directly without a parallel branch-push run. Website-only documentation changes under projects/<project>/docs/**, standardized test files, and colocated *.test-fixtures.* support files are excluded; Shipped documentation, README, manifest, production source, license, and declared package-artifact changes remain included. An existing selected project must declare a stable version strictly greater than its version at the preceding commit, except when that same stable version remains absent from npm after an earlier failed or interrupted publication. A newly introduced project with no base manifest must declare a canonical stable version. The npm workflow verifies every main commit exactly once, including successful no-op releases, then creates package-qualified immutable tags and publishes the exact checksummed tarballs in dependency order through trusted publishing. Linux verification uses the official Playwright image pinned to the packages website's installed version instead of downloading Chromium and operating-system dependencies during each run. A project whose version is invalid for its release state fails before publication. Manual CI remains available for branch checks, while manual publication dispatch remains available for new-package bootstrap and release recovery. See docs/npm-releases.md.

The first implementation project was @moldea.ai/repository, followed by its in-memory reader and shared conformance suite. Core's universal behavior was then completed through that memory-reader boundary, followed by Repository FS, the CLI's installed-tarball runtime boundary, and the first official package-backed adapters. The Anthropic, Claude Agent SDK, Cloudflare Agents, Eve, Google Gen AI, LangChain, LangGraph, OpenAI, OpenAI Agents SDK, and Vercel AI SDK adapters now own verified TypeScript technical targets with deterministic fixtures, diagnostics, evidence, package metadata, and packed-runtime verification. Their provider-neutral source analysis, relationship classification, and operation-local inspection caches live in the private @moldea.ai/adapter-static-analysis package and are bundled into each public adapter artifact. Website UI now owns the reusable public-website foundation independently of the runtime package chain. Package publication remains an explicit independently versioned release operation.