ai-design-context 0.4.0

package/AGENTS.md

@@ -0,0 +1,156 @@
+# AI Design Context Agent Guide
+
+AI Design Context is an AI-first knowledge base for teaching coding agents how to design modern consumer products.
+
+Do not treat this repository as a documentation dump. Treat it as a knowledge graph.
+
+## Core Flow
+
+Follow this order:
+
+```text
+observation -> research -> knowledge -> rules -> patterns -> prompts -> reference projects -> reviews
+```
+
+Never skip upstream evidence. Never generate UI from taste alone.
+
+## Architecture Source
+
+Read `docs/KNOWLEDGE_ENGINE.md` before changing repository structure, adding object types, or changing relationships.
+
+Use it as the source of truth for:
+
+- schema-first object metadata;
+- global IDs, aliases, and slugs;
+- object metadata;
+- relationship types;
+- registry records;
+- navigation;
+- DesignLint readiness;
+- long-term scalability.
+
+## Working Rules
+
+- Improve architecture before adding volume.
+- Prefer improving existing knowledge over creating parallel files.
+- Keep every object connected to upstream sources and downstream usage.
+- Use schema-compatible YAML front matter for new knowledge objects.
+- Preserve schema-compatible YAML front matter on every migrated research, rule, pattern, prompt, and reference project.
+- Use typed relationships only.
+- Treat manual indexes as transitional context pages.
+- Use generated indexes as the preferred navigation layer for the migrated minimal chain.
+- Do not add rules without research.
+- Do not add patterns without required rules and related research.
+- Do not add prompts that invent design advice outside rules and patterns.
+- Do not treat reference projects as demos; use them to validate the graph.
+
+## Agent Context Retrieval
+
+Before planning or changing a user-facing product, UX, UI, accessibility, motion, or prompt task, resolve focused graph context:
+
+```bash
+npm run context -- --task <task-slug-or-phrase> --intent implement
+```
+
+Add `--platform mobile` when narrow-screen behavior matters. Before reviewing an implementation, reference fixture, benchmark artifact, or prompt output, use:
+
+```bash
+npm run context -- --review <path-or-object-id> --intent qa
+```
+
+Read the returned research and rules before making product decisions. Treat `draft` and `seed` objects as bounded guidance. If no context resolves, record an observation or research need rather than inventing a rule. Skip the command for backend-only, infrastructure-only, or unrelated maintenance tasks.
+
+## Knowledge Objects
+
+- Observation
+- Research
+- Rule
+- Pattern
+- Prompt
+- Skill
+- Checklist
+- Review
+- Reference Project
+
+## Local Skill Specs
+
+The current reusable agent skills live in `skills/*/SKILL.md`.
+
+Use them when the task matches their role:
+
+- `skills/product-designer/SKILL.md` for product direction, primary action, object model, and pattern selection.
+- `skills/ux-reviewer/SKILL.md` for journey clarity, usability, state coverage, and user friction.
+- `skills/information-architect/SKILL.md` for object model, navigation, hierarchy, labels, and status language.
+- `skills/mobile-ux-expert/SKILL.md` for touch-first mobile behavior, capture flows, primary actions, and context preservation.
+- `skills/interaction-designer/SKILL.md` for flow mechanics, feedback, recovery, previews, and state transitions.
+- `skills/design-system-architect/SKILL.md` for semantic tokens, reusable state behavior, and pattern/component boundaries.
+- `skills/visual-designer/SKILL.md` for visual hierarchy, spacing, typography, color meaning, and polish.
+- `skills/motion-designer/SKILL.md` for purposeful motion and reduced-motion behavior.
+- `skills/accessibility-reviewer/SKILL.md` for labels, focus, target size, contrast, errors, and reduced motion.
+- `skills/performance-reviewer/SKILL.md` for perceived performance, loading behavior, responsiveness, and layout stability.
+- `skills/design-reviewer/SKILL.md` for design QA, traceability checks, and rule/pattern coverage review.
+- `skills/prompt-architect/SKILL.md` for graph-backed prompt structure and output contracts.
+- `skills/knowledge-graph-architect/SKILL.md` for schema, registry, generated indexes, relationships, and validation scope.
+- `skills/agent-context/SKILL.md` for focused graph retrieval before implementation or review.
+
+These skill files are not registered knowledge objects yet. Do not add them to `registry/objects.json` until skill metadata migration is explicitly requested.
+
+## Relationship Discipline
+
+Use the relationship types defined in `docs/KNOWLEDGE_ENGINE.md`:
+
+- `derived_from`
+- `cites`
+- `inspired_by`
+- `requires`
+- `validates`
+- `implements`
+- `related_to`
+- `supersedes`
+- `deprecated_by`
+- `replaced_by`
+
+Every new object should be traceable.
+
+## Validation Discipline
+
+Research, rules, patterns, prompts, and reference projects are the first migrated chain.
+
+When changing `research/`, `rules/`, `patterns/`, `prompts/`, `examples/`, `registry/objects.json`, or `registry/relationships.json`:
+
+1. Keep front matter and registry records aligned.
+2. Keep relationship targets typed and resolvable.
+3. Run `npm run generate:indexes`.
+4. Run `npm run validate`.
+
+Do not edit generated indexes manually.
+
+The validator is intentionally limited. It does not replace future DesignLint and does not enforce unmigrated object types yet.
+
+## Quality Bar
+
+Progress means:
+
+- stronger relationships;
+- fewer duplicates;
+- better discoverability;
+- clearer specifications;
+- more reliable agent behavior.
+
+Progress does not mean:
+
+- more pages;
+- more prompts;
+- more rules without evidence;
+- more disconnected examples.
+
+## Future Compatibility
+
+Every architectural decision should support:
+
+- 1000+ rules;
+- 300+ patterns;
+- 200+ prompts;
+- multiple reference projects;
+- future DesignLint integration;
+- IDE and MCP integration.

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+## Unreleased
+
+- Rename the project to AI Design Context and use `ai-design-context` as the package name; keep the GitHub URL at `dev-ik/ai-design-rules`.
+- Preserve historical releases, frozen benchmark evidence, stable graph identifiers, and schema URIs under their original names.
+- Package the complete graph and upstream evidence with a dependency-free Node.js 20+ CLI and an explicit publish allowlist.
+- Add `init` for preserving existing agent instructions and creating only missing templates, with repeated-run and symlink protections.
+- Add installed-package `context` retrieval with absolute reading paths while preserving the existing checkout CLI contract.
+- Verify offline installation and use of the actual npm tarball; run repository checks and tests before packing.
+
+## v0.4.0 — Focused Context And Applied Patterns
+
+- Add an agent-led installation guide for pinned knowledge integration into existing product repositories.
+- Add the consequential-action guidance chain: observations, research, `UX-006`, a confirmation pattern, a review prompt, and a reference specification with specification-level validation.
+- Rank task context by exact identifiers and focused titles before incidental mentions, with whole-word matching and support for simple English task phrasing.
+- Resolve all transitive required and upstream knowledge dependencies while limiting optional graph expansion; include an explanation for every selected object.
+- Select platform context from eligible rules and patterns before ranking, and preserve JSON object fields with additive selection reasons.
+- Apply `VIS-001` and `VIS-002` in Daily Home Surface and `UX-004` in Context-Preserving Preview, with concrete hierarchy, focus, interruption, and fallback contracts.
+- Add regression coverage for realistic queries, dependency completeness, cycles, platform selection, and missing targets.
+- Define the next paired rendered Todo run, with identical generation conditions, mobile/desktop state captures, interaction checks, and evaluation limits.
+- Record the first paired rendered Todo run with frozen source, forty screenshots, exact context bundles, runtime measurements, and an internal unblinded evaluation.
+- Extend Quick Capture State Review with populated-list keyboard paths and geometry checks for saving, wrapped errors, and retry, based on the observed benchmark gaps.
+
+### Evidence Boundary
+
+The updated patterns and review prompt remain `draft` / `seed`. The [rendered Todo pair](evidence/todo/2026-09-28-codex-paired-todo/EVALUATION.md) scored 7.42 versus 7.67 in an internal unblinded evaluation, with equal visual-hierarchy scores and a worse sequential keyboard capture path in the rules-assisted output. One pair does not establish a general quality gain, independent validation, or an improvement over the previous release. The resulting review-prompt revision still needs a new paired run.
+
+## v0.3.0 — Expressive Systems And Agent Context
+
+- Added primary-source observations for expressive platform materials, adaptive web UI, systematic motion, and observable agentic workflows.
+- Added research on expressive system UI, motion as state continuity, and contextual agentic interfaces.
+- Added `VIS-002`, `UX-004`, and `UX-005` for content-first expression, purposeful motion, and visible agent work.
+- Added the `reference-driven-design` skill for evidence-backed reference selection without brand copying.
+- Expanded Prototype Review and Design QA with visual layers, responsive behavior, complete state coverage, motion fallbacks, and agent lifecycle review.
+- Improved research-led context retrieval so matching research can resolve downstream rules, prompts, and review gates.
+
+### Evidence Boundary
+
+The new visual, motion, and agentic knowledge remains `draft` and `seed`. It is traceable to primary-source observations, but it does not yet have paired rendered benchmark evidence or independent evaluation. This release improves the knowledge and review workflow; it does not claim measured visual-quality gains.
+
+## v0.2.1 — Validation Hardening
+
+- Fixed Unicode task lookup and exact object resolution in the agent context CLI.
+- Removed unsafe HTML rendering from the runnable Todo fixture.
+- Made the main validation command read-only so stale generated indexes fail CI.
+- Hardened rendered benchmark screenshot path, file, and metadata validation.
+- Improved malformed knowledge-object diagnostics and expanded regression coverage.
+
+## v0.2.0 — Evidence-Aware QA and Context Retrieval
+
+- Added focused agent context retrieval for implementation and QA tasks.
+- Added DesignLint v0 for evidence-chain relationship checks.
+- Added benchmark-evidence validation with explicit directional-versus-rendered boundaries.
+- Extended the graph with accessibility and performance observations, research, rules, prompts, reviews, and templates.
+- Added a runnable Todo reference fixture with responsive and accessibility QA coverage.
+- Expanded registry validation, generated indexes, and automated test coverage.
+
+### Evidence Boundary
+
+The current Todo benchmark remains directional only. It does not claim paired rendered benchmark evidence, independent evaluation, or measured performance validation.
+
+## v0.1.0 — Foundation + Benchmark Ready
+
+- Established the schema-first knowledge graph foundation.
+- Migrated research, rules, patterns, and prompts to metadata-backed objects.
+- Added generated indexes for research, rules, patterns, prompts, examples, and graph reporting.
+- Added validation tooling for metadata, registry coverage, relationships, and generated index sync.
+- Added benchmark methodology and evaluation rubric.
+- Added first todo benchmark evidence.
+- Completed OSS cleanup with no personal project references.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+AI Design Context is a public OSS project for practical, evidence-driven product design knowledge.
+
+## Expected Behavior
+
+- Be direct, respectful, and specific.
+- Critique ideas, files, and claims instead of people.
+- Explain reasoning when proposing changes.
+- Keep discussions focused on repository quality and public usefulness.
+- Welcome good-faith contributions from people with different levels of design, engineering, and AI tooling experience.
+
+## Unacceptable Behavior
+
+- Harassment, insults, threats, or personal attacks.
+- Discriminatory language or behavior.
+- Publishing private information without permission.
+- Repeated low-effort comments that derail maintainers or contributors.
+- Presenting unsupported claims as evidence.
+
+## Evidence Standard
+
+This project values benchmark-backed and source-backed claims. If a discussion concerns product quality, design rules, or AI output improvement, prefer reproducible evidence over preference.
+
+## Enforcement
+
+Maintainers may edit, close, hide, or remove issues, pull requests, comments, or accounts that violate this code of conduct.
+
+For security-sensitive reports, use `SECURITY.md` instead of public issues.

package/CONTRIBUTING.md

@@ -0,0 +1,128 @@
+# Contributing
+
+AI Design Context accepts concise, practical contributions that help AI coding agents design better consumer products.
+
+## Contribution Pipeline
+
+Use the same order as the repository:
+
+```text
+observation -> research -> knowledge -> rules -> patterns -> prompts -> reference projects -> reviews
+```
+
+Start with evidence. Do not add a rule, pattern, or prompt if the underlying product behavior is not clear.
+
+## What To Contribute
+
+- Product research in `research/`.
+- Design rules in `rules/`.
+- Reusable patterns in `patterns/`.
+- Product prompts in `prompts/`.
+- Review checklists or templates in `checklists/` and `templates/`.
+- Agent skills in `skills/` when a workflow is stable enough to reuse.
+
+## Rule Contributions
+
+Use `templates/RULE_TEMPLATE.md`.
+
+Every rule must include:
+
+- why the rule exists;
+- what good output looks like;
+- what bad output looks like;
+- how to review it.
+
+Do not submit rules that are only taste, preference, or vague advice.
+
+Rules are migrated objects. New or changed rule files must include schema-compatible YAML front matter and be listed in `registry/objects.json`.
+
+If a rule changes upstream sources, update its typed `relationships` front matter.
+
+## Pattern Contributions
+
+Use `templates/PATTERN_TEMPLATE.md`.
+
+Every pattern must follow `docs/PATTERN_SPEC.md` and include schema-compatible YAML front matter.
+
+Patterns are migrated objects. New or changed pattern files must:
+
+- use a stable `PAT-00000` machine ID;
+- keep a human-friendly alias;
+- list required rule relationships;
+- be listed in `registry/objects.json`;
+- have required and related edges in `registry/relationships.json`.
+
+## Documentation Style
+
+Follow `docs/STYLE_GUIDE.md`.
+
+Write for agents that need to act inside a codebase. Prefer direct rules, clear examples, and reviewable criteria.
+
+## Knowledge Object Metadata
+
+New object types and future metadata migrations should follow `docs/KNOWLEDGE_ENGINE.md`.
+
+Do not create disconnected files. Every research, rule, pattern, prompt, checklist, skill, review, or reference project should link upstream sources and downstream usage.
+
+## Schema-First Contributions
+
+New knowledge objects should include YAML front matter compatible with the relevant schema in `schema/`.
+
+Research, rules, patterns, prompts, and reference projects are the first enforced migrated chain. Run:
+
+```sh
+npm run generate:indexes
+npm run validate
+```
+
+before submitting changes to `research/`, `rules/`, `patterns/`, `prompts/`, `examples/`, `registry/objects.json`, or `registry/relationships.json`.
+
+Use global machine IDs for new objects:
+
+- `OBS-00001`
+- `RESEARCH-00001`
+- `RULE-00001`
+- `PAT-00001`
+- `PROMPT-00001`
+- `REVIEW-00001`
+- `CHECK-00001`
+- `REF-00001`
+
+Use `alias` for human-friendly IDs such as `UX-001`.
+
+Use `slug` for file-safe names.
+
+Relationships must be typed. Use only the relationship types defined in `schema/common.schema.json`.
+
+Generated indexes are the preferred navigation layer for the migrated minimal chain:
+
+- `research/GENERATED_INDEX.md`
+- `rules/GENERATED_INDEX.md`
+- `patterns/GENERATED_INDEX.md`
+- `prompts/GENERATED_INDEX.md`
+- `examples/GENERATED_INDEX.md`
+- `graph/GENERATED_GRAPH.md`
+
+Do not edit generated files manually. Update front matter and registry metadata, then run `npm run generate:indexes`.
+
+Manual indexes are transitional. Keep them useful for human context, but do not treat them as the source of truth.
+
+## Reference Projects
+
+Reference projects are intentionally omitted from the first OSS release.
+
+Use `benchmarks/` and `evidence/` when validating new rules, prompts, or review checklists.
+
+Future reference projects are not demos for decoration. They should use generic product archetypes and benchmark-backed evidence.
+
+## Review Checklist
+
+Before opening a contribution:
+
+- The content fits the repository pipeline.
+- The file is in the correct folder.
+- The naming follows existing conventions.
+- The contribution explains why, not only what.
+- There is no filler content.
+- The change does not create a duplicate concept under a different name.
+- Generated indexes are updated when registry metadata changes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dev Ik
+
+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,283 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="AI Design Context logo" width="96" height="96">
+</p>
+
+<h1 align="center">AI Design Context</h1>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <a href="CHANGELOG.md"><img alt="Status: active" src="https://img.shields.io/badge/status-active-success.svg"></a>
+  <a href="evidence/README.md"><img alt="Evidence: benchmark driven" src="https://img.shields.io/badge/evidence-benchmark--driven-orange.svg"></a>
+</p>
+
+> **Build products. Not dashboards.**
+>
+> **Teach AI to think like a product designer.**
+
+**AI Design Context** is a **vendor-neutral, evidence-driven knowledge base** for AI coding agents.
+
+Instead of teaching AI how to generate interfaces, it teaches AI how to design modern software products through **research**, **design rules**, **reusable patterns**, and **reproducible benchmarks**.
+
+Previously named **AI Design Rules**. Historical releases, benchmark artifacts, and stable schema identifiers retain the original name.
+
+---
+
+## Why AI Design Context?
+
+Modern AI coding agents are excellent at generating code.
+
+They are far less consistent at making product decisions.
+
+AI Design Context helps agents move beyond generating screens by providing:
+
+- Research-driven product knowledge
+- Reusable design rules
+- Composable UI patterns
+- Structured design workflows
+- Reproducible benchmarks
+
+Instead of relying on prompts alone, agents learn from an evolving knowledge graph.
+
+---
+
+## Core Principles
+
+- Research before implementation
+- Rules before prompts
+- Evidence over opinion
+- Reusable patterns instead of one-off solutions
+- Benchmarks instead of subjective claims
+
+---
+
+## Knowledge Pipeline
+
+```text
+Observations
+      ↓
+Research
+      ↓
+Rules
+      ↓
+Patterns
+      ↓
+Prompts
+      ↓
+Benchmarks
+      ↓
+Evidence
+      ↓
+Reviews
+```
+
+The repository is built as a **schema-first knowledge graph** for both humans and AI coding agents.
+
+---
+
+## Features
+
+- Vendor-neutral architecture
+- Schema-first knowledge graph
+- Stable IDs and typed relationships
+- Research-driven design rules
+- Reusable product and UI patterns
+- AI agent skills
+- Validation tooling
+- Benchmark framework
+- DesignLint v0 for evidence-chain relationship checks
+
+---
+
+## Supported AI Coding Agents
+
+AI Design Context is model-agnostic and works with any AI coding agent capable of reading repository documentation, including:
+
+- OpenAI Codex
+- Claude Code
+- Cursor
+- GitHub Copilot
+- Gemini CLI
+- Cline
+- Continue
+- Aider
+
+---
+
+## Evidence-Driven Development
+
+AI Design Context does **not** assume it improves AI output.
+
+Every significant change should be validated using reproducible benchmarks.
+
+```text
+Baseline AI
+      ↓
+AI + AI Design Context
+```
+
+The first benchmark is **directional**, not conclusive, and serves as the starting point for future public validation.
+
+---
+
+## Add It to a Product Repository
+
+AI Design Context ships as the dependency-free npm package `ai-design-context` with a CLI and a versioned knowledge graph. Requires **Node.js 20 or later**. The GitHub repository stays at [`dev-ik/ai-design-rules`](https://github.com/dev-ik/ai-design-rules).
+
+After the first npm publication:
+
+```bash
+npm install --save-dev --save-exact ai-design-context
+npx ai-design-context init
+npx ai-design-context context --task quick-capture --platform mobile --intent implement
+```
+
+Commit the project's dependency manifest and lockfile to pin the knowledge version. Installation alone does not edit project files: `init` explicitly appends a marked section to `AGENTS.md` and creates only missing product-context docs, feature/task templates, and review/benchmark checklists. It preserves existing instructions, populated files, and edited integration blocks; repeated runs do not duplicate them. Fill new placeholders with actual product context.
+
+`context` reads the graph from the installed package, independently of the project's working directory. Markdown provides absolute reading paths; JSON adds `knowledgeRoot` and each object's `absolutePath` while preserving graph-relative `path`. Read the selected research and rules before implementing UI changes.
+
+```bash
+npx ai-design-context context --object PAT-00002 --format json
+npx ai-design-context context --review REF-00001 --intent qa
+npx ai-design-context --help
+```
+
+Review queries retrieve matching graph knowledge; they do not analyze arbitrary application files. Matching is lexical, with known IDs and slugs available when phrases do not match. See [Agent Context](docs/AGENT_CONTEXT.md).
+
+Before publication, build a local tarball from this repository and install it into a product repository:
+
+```bash
+# In the AI Design Context checkout. Runs graph checks and tests before packing.
+npm pack
+
+# In the product repository; replace the path with the generated tarball path.
+npm install --save-dev /path/to/ai-design-context-0.4.0.tgz
+npx ai-design-context init
+```
+
+For deliberate updates after publication, run `npm install --save-dev --save-exact ai-design-context@<version>`, review the new guidance, and commit the lockfile. There are no install hooks, application runtime dependencies, or new UI frameworks.
+
+Git submodules and sibling checkouts remain supported alternatives. See [Install with a Coding Agent](starter-kit/INSTALL_WITH_AGENT.md) for both npm and Git workflows.
+
+Maintainers: [npm Releases](docs/NPM_RELEASE.md) describes initial publication and automatic publishing from GitHub Releases with npm Trusted Publishing.
+
+---
+
+## Quick Start
+
+```bash
+npm install
+npm run check
+```
+
+This command validates metadata, relationships, generated indexes, and the repository knowledge graph.
+It is read-only and fails when generated indexes are stale. After changing registry metadata, run `npm run generate:indexes` before `npm run check`.
+
+For focused checks:
+
+```bash
+npm run lint:design
+npm run benchmark:validate
+```
+
+The benchmark validator checks raw evidence completeness and distinguishes directional runs from rendered runs with local visual artifacts. It never treats scores alone as proof of product quality.
+
+Ask the graph for task-specific context instead of reading every index manually:
+
+```bash
+npm run context -- --task quick-capture --platform mobile
+npm run context -- --review examples/todo-reference
+```
+
+Use `--format json` when another agent or script will consume the result. See `docs/AGENT_CONTEXT.md` for the object-resolution and evidence-boundary contract.
+
+---
+
+## Recommended Workflow
+
+1. Read `AGENTS.md`
+2. Follow `docs/INDEX.md`
+3. Explore relevant research
+4. Select applicable rules
+5. Compose patterns
+6. Apply prompts
+7. Validate with benchmarks
+8. Record evidence
+9. Improve the knowledge graph
+
+---
+
+## Repository Structure
+
+```text
+docs/
+research/
+rules/
+patterns/
+prompts/
+skills/
+benchmarks/
+evidence/
+starter-kit/
+schema/
+registry/
+templates/
+reviews/
+observations/
+```
+
+Generated indexes are built from repository metadata.
+
+`starter-kit/` can be copied into a product repository that wants to adopt AI Design Context.
+
+---
+
+## Contributing
+
+Start with:
+
+- `CONTRIBUTING.md`
+- `AGENTS.md`
+- `docs/INDEX.md`
+
+Every contribution should explain:
+
+- where the knowledge came from;
+- why it exists;
+- when it applies;
+- how it relates to existing knowledge.
+
+---
+
+## Project Status
+
+AI Design Context is under active development.
+
+Current public release includes:
+
+- Schema-first architecture
+- Knowledge graph
+- JSON Schemas
+- Stable metadata model
+- Generated indexes
+- Validation tooling
+- Benchmark methodology
+- AI agent skills
+
+See `CHANGELOG.md` for release history.
+
+---
+
+## Roadmap
+
+- Expanded benchmark evidence
+- Public reference archetypes
+- Expanded DesignLint semantics
+- IDE integrations
+- MCP integrations
+- Community-driven rule evolution
+
+---
+
+## License
+
+See `LICENSE`.