This document describes the current Cogita package lanes, upgrade boundaries, and validation requirements. The version table is generated by scripts/check-compatibility-matrix.mjs from each package's package.json. If a package version changes, update the document before the release gate can pass.
| Package | Current version | Compatibility lane | Role |
|---|---|---|---|
@cogita/shared |
0.13.0 | Core platform | Shared types, capabilities, and version contracts |
@cogita/core |
0.15.0 | Core platform | Configuration, plugin registration, and build lifecycle |
@cogita/cli |
0.3.1 | Core platform | Site initialization, development, and build entry points |
@cogita/ui |
0.1.2 | Theme ecosystem | Shared theme UI components |
@cogita/plugin-blog-list |
0.3.5 | Blog theme plugin | Lists, filters, pagination, and archives |
@cogita/plugin-categories |
0.2.7 | Blog theme plugin | Category aggregation and pages |
@cogita/plugin-code-copy |
0.2.6 | Blog theme plugin | Runtime code-copy enhancement |
@cogita/plugin-collections |
1.0.7 | Blog theme plugin | Collection aggregation and pages |
@cogita/plugin-comments |
0.2.7 | Blog theme plugin | Comment configuration and post routes |
@cogita/plugin-content-check |
0.2.5 | Blog theme plugin | Content quality diagnostics |
@cogita/plugin-content-relations |
0.2.1 | Knowledge plugin | Local links, related content, and backlinks |
@cogita/plugin-content-source-json |
0.2.0 | Knowledge plugin | JSON export content-source adapter |
@cogita/plugin-content-source-git |
0.2.0 | Knowledge plugin | Independent Git Markdown content-source adapter |
@cogita/plugin-images |
1.0.7 | Blog theme plugin | Public image and cover handling |
@cogita/plugin-posts-frontmatter |
0.1.6 | Blog theme plugin | Post index and post pages |
@cogita/plugin-reading-progress |
0.3.7 | Blog theme plugin | Reading time and progress |
@cogita/plugin-rss |
1.0.7 | Blog theme plugin | RSS, Atom, and JSON Feed |
@cogita/plugin-search |
0.2.7 | Blog theme plugin | Local search index and pages |
@cogita/plugin-seo |
1.3.7 | Blog theme plugin | Page SEO metadata and audits |
@cogita/plugin-sitemap |
1.3.7 | Blog theme plugin | Sitemap generation |
@cogita/plugin-tags |
1.0.7 | Blog theme plugin | Tag aggregation and pages |
@cogita/theme-lucid |
0.12.1 | Blog theme | Default blog theme and full plugin integration |
@cogita/theme-editorial |
0.3.1 | Blog theme | Editorial-style blog theme |
@cogita/theme-docs |
0.3.1 | Docs theme | Technical handbook and documentation sites |
@cogita/theme-knowledge |
0.3.1 | Knowledge theme | Unified content, search, tags, and backlinks |
@cogita/shared, @cogita/core, and @cogita/cli belong to one Core release lane. They may have different package versions, but changes to build context, ContentIndex, capability identifiers, or virtual modules must be validated in one Changesets release batch. Use CLI and Core packages from the same batch instead of combining unverified versions.
@cogita/theme-lucid and @cogita/theme-editorial combine multiple blog plugins and belong to the blog theme lane. A theme's package.json is the source of truth for its plugin list. When upgrading a plugin, run at least the minimal blog consumer and the real cogita-blog consumer.
@cogita/theme-docs is an independent docs-theme lane and does not depend on the blog plugin set. Validate it with an independent docs consumer, covering the home page, document routes, theme preview, and static output.
@cogita/theme-knowledge combines the unified content index, search, tags, and content relations, and belongs to the knowledge lane. Validate it with an independent knowledge consumer, covering posts, contentDir documents, root deployment, and subpath deployment.
Packages that use Rspress directly currently use @rspress/core ^1.45.1 as the compatibility baseline. Themes expose @rspress/runtime ^1.0.0 as a peer range and support React 18 or React 19. When upgrading Rspress or React, establish a new compatibility lane first, then update the script baseline and rerun every consumer gate.
0.x minor release may contain public API or build-contract changes; do not treat it like a patch-only upgrade.ContentIndex, buildContext, and virtual-module shapes are described by their contractVersion or version header. Consumers should check the contract before reading new fields.pnpm run check:compatibility -- --write to update the version table.pnpm run build:packages and pnpm run test.pnpm run check:release to validate package boundaries, the minimal blog, the independent blog, and the independent docs site.The compatibility check is part of pnpm run check:release. CI rejects a package-version change that does not update this document.