noecosystem-design 0.1.0 → 0.1.2

package/AGENTS.md

@@ -4,6 +4,18 @@
 
 Extend NOE as one coherent system: calm, precise, connected, deliberate, technical, human-centered, premium, quiet, and fast.
 
+## Agent onboarding
+
+1. Read `README.md`, then this file, before making a change.
+2. Use `llms.txt` to locate the focused documentation and
+   `packages/registry/manifest.json` to discover an existing capability.
+3. Treat `noecosystem-design` as an agent-readable source snapshot, not as a runtime
+   import package. Internal source boundaries remain `@noe/*`.
+4. The public `@noe` registry endpoint is not deployment-proven. Local registry build
+   output and tests must not be represented as a working external installation path.
+5. Make claims about a check, deployment, or installation only when its evidence was
+   executed in the current relevant environment.
+
 ## Source-of-truth order
 
 1. Running production behavior.

package/README.md

@@ -1,48 +1,91 @@
 # NOE Design System
 
-A production-grade, agent-friendly design system for NOE: multilingual, fully
-bidirectional, theme-aware React components with semantic tokens, a shadcn-compatible
-`@noe` registry, Storybook documentation and a multi-layered test suite.
+NOE is a multilingual, bidirectional, theme-aware React design system. This package
+publishes an agent-readable source snapshot: semantic tokens, component source,
+registry metadata, reference apps, documentation, and verification contracts.
 
-## Commands (pnpm workspace)
+## Start here
 
 ```bash
-corepack enable && pnpm install     # Node >= 24.19
-pnpm check                          # format + lint + typecheck + tests + builds + verify
+# Give a coding agent the NOE source context.
+npm install noecosystem-design
+
+# The agent starts with these files after installation:
+cat node_modules/noecosystem-design/AGENTS.md
+cat node_modules/noecosystem-design/llms.txt
+cat node_modules/noecosystem-design/docs/design-system/gpt-agent-prompt.md
+
+# For a writable, verifiable workspace, use a repository checkout.
+git clone https://github.com/NOrchestration/noe-design-system.git
+cd noe-design-system
+corepack enable
+pnpm install --frozen-lockfile
+pnpm check
 ```
 
-| Command               | Purpose                                              |
-| --------------------- | ---------------------------------------------------- |
-| `pnpm lint`           | Biome lint (a11y, correctness, style)                |
-| `pnpm typecheck`      | Strict TypeScript across the workspace               |
-| `pnpm test`           | Offline node tests + Vitest unit project             |
-| `pnpm test:components`| Vitest browser component tests (Playwright/Chromium) |
-| `pnpm test:storybook` | Storybook interaction + accessibility tests          |
-| `pnpm test:e2e`       | Playwright matrix (surfaces × locales × viewports)   |
-| `pnpm build`          | Build all packages, showcase app                     |
-| `pnpm build:storybook`| Production Storybook static build                    |
-| `pnpm verify`         | Registry, i18n, RTL, governance and secret audits    |
-| `pnpm dev`            | Showcase application dev server                      |
-| `pnpm storybook`      | Storybook dev server                                 |
+Read [`AGENTS.md`](AGENTS.md) before changing code. Use [`llms.txt`](llms.txt) as the
+retrieval map, then read the affected package and component records. The canonical
+catalog is [`packages/registry/manifest.json`](packages/registry/manifest.json).
+
+For a GPT coding agent, copy
+[`docs/design-system/gpt-agent-prompt.md`](docs/design-system/gpt-agent-prompt.md),
+replace `<TARGET_REPOSITORY>` and `<DESCRIBE THE REQUESTED OUTCOME...>`, and send it
+as one task prompt. The template carries static NOE context once; put only the
+requested outcome, scope, and non-negotiable constraints in its `Task` section.
+
+## What `noecosystem-design` is — and is not
+
+- It is a source and metadata distribution for people and coding agents.
+- It is not a compiled runtime library: do not write `import { Button } from
+  "noecosystem-design"`.
+- Internal source packages use the `@noe/*` names. They are workspace boundaries,
+  not published npm packages at this time.
+- The shadcn-compatible `@noe` registry is locally generated and tested, but its
+  external site endpoint is not yet evidenced as deployed. Do not claim or assume
+  that `shadcn add @noe/<item>` works against the public domain.
+
+## Agent operating route
+
+1. Read `AGENTS.md`, then `llms.txt`.
+2. Find the requested capability in `packages/registry/manifest.json`; read its
+   `useWhen`, `doNotUseWhen`, accessibility, i18n, and dependency contracts.
+3. Reuse an existing `@noe` component before considering a foundation or new code.
+4. Preserve semantic tokens, i18n, RTL/bidi, and portal direction contracts.
+5. Update source, stories, tests, registry metadata, and documentation together.
+6. Report only executed verification; planned or locally generated registry output
+   is not deployment evidence.
+
+## Workspace commands
+
+| Command | Purpose |
+| --- | --- |
+| `pnpm lint` | Biome correctness, style, and accessibility checks |
+| `pnpm typecheck` | Strict TypeScript validation |
+| `pnpm test` | Offline and unit tests |
+| `pnpm test:components` | Browser component tests in Chromium |
+| `pnpm test:storybook` | Storybook interaction and accessibility tests |
+| `pnpm test:e2e` | Playwright locale, theme, viewport, and browser matrix |
+| `pnpm build` | Build workspace packages and the showcase app |
+| `pnpm build:storybook` | Produce static Storybook output |
+| `pnpm verify` | Registry, i18n, RTL, governance, and secret audits |
+| `pnpm check` | Full local release gate |
 
 ## Architecture
 
 ```text
-apps/
-  showcase/         React + Vite product surface reference
-  storybook/        Stories, docs, a11y and interaction tests
-  web/              Dependency-free visual reference and QA target
-
-packages/
-  design-tokens/    Semantic tokens and CSS contracts (light/dark)
-  ui/               Direction-safe UI primitives (@noe/ui)
-  i18n/             Locale metadata, formatters, pseudo-locales
-  data-ui/          Data table, metrics, chart framing
-  ai-ui/            Agent, run, tool, approval, artifact patterns
-  workflow-ui/      Workflow canvas, nodes, inspector
-  icons/            First-party icon policy and directional mirroring
-  registry/         shadcn-compatible @noe registry output
-  testing/          Reusable test contracts
+apps/                 Reference applications and visual QA surfaces
+packages/design-tokens  Semantic visual decisions only
+packages/ui             Direction-safe interaction primitives
+packages/i18n           Locale metadata, messages, formatters, pseudo-locales
+packages/data-ui        Data, filter, metric, and chart composition
+packages/ai-ui          Agent, tool, approval, run, and artifact states
+packages/workflow-ui    Workflow canvas, node, and inspector patterns
+packages/icons          Icon policy and directional mirroring
+packages/registry       Canonical component catalog and install metadata
 ```
 
-Read `AGENTS.md` before modifying the system. `llms.txt` is the compact retrieval map.
+See [`docs/design-system/README.md`](docs/design-system/README.md) for the focused
+documentation index and [`docs/design-system/agent-guide.md`](docs/design-system/agent-guide.md)
+for the coding-agent workflow. The ready-to-paste
+[`docs/design-system/gpt-agent-prompt.md`](docs/design-system/gpt-agent-prompt.md)
+is the recommended task wrapper for GPT.

package/docs/design-system/README.md

@@ -1,6 +1,6 @@
 # NOE Design System documentation
 
-The documentation describes the implementation in this repository and marks externally blocked work explicitly. It does not treat a file, workflow definition, or intended deployment as proof that the corresponding system ran.
+The documentation describes the implementation in this repository and marks externally blocked work explicitly. It does not treat a file, workflow definition, npm source snapshot, or intended deployment as proof that the corresponding system ran.
 
 ## Navigation
 
@@ -11,6 +11,7 @@ The documentation describes the implementation in this repository and marks exte
 - `i18n.md`, `rtl.md`: locale, direction and bidi architecture.
 - `accessibility.md`: WCAG-oriented requirements.
 - `testing.md`, `visual-qa.md`: test and evidence strategy.
-- `registry.md`, `mcp.md`, `agent-guide.md`: coding-agent discovery.
+- `gpt-agent-prompt.md`: ready-to-paste GPT task wrapper with outcome, autonomy, output, and stop rules.
+- `registry.md`, `mcp.md`, `agent-guide.md`: coding-agent discovery and package/registry boundaries.
 - `ci-cd.md`, `security.md`: automation and governance.
 - `contributing.md`: change workflow.

package/docs/design-system/agent-guide.md

@@ -1,11 +1,51 @@
 # Coding-agent guide
 
-1. Read `AGENTS.md` and the affected package documentation.
-2. Search `@noe` before generating code.
-3. Prefer existing product patterns, then approved foundations, then 21st.dev discovery.
-4. Use semantic tokens and logical CSS.
-5. Keep user-facing copy in the message system.
-6. Exercise English, Persian, pseudo-LTR and pseudo-RTL.
-7. Test portal direction, keyboard behavior and technical-value isolation.
-8. Update stories, tests, registry metadata and docs in the same change.
-9. State evidence precisely; never convert intended work into completed work.
+## Start a GPT task
+
+Copy [`gpt-agent-prompt.md`](gpt-agent-prompt.md), replace its target repository and
+`Task` placeholder, and send it as one prompt. Put the requested outcome, scope, and
+non-negotiable constraints in `Task`; do not re-paste this guide or `AGENTS.md`.
+The prompt already defines the agent's success criteria, autonomy boundary, response
+format, and stop rules.
+
+## Scope and distribution
+
+`noecosystem-design` is an npm-distributed source snapshot for discovery, review, and
+retrieval. It is not a compiled runtime package, so do not import from it. For an
+implementation change, use a writable checkout of this repository. The workspace's
+internal package boundaries use `@noe/*`.
+
+After `npm install noecosystem-design`, the agent entrypoints are
+`node_modules/noecosystem-design/AGENTS.md` and
+`node_modules/noecosystem-design/llms.txt`. The canonical component catalog is
+`node_modules/noecosystem-design/packages/registry/manifest.json`. An agent may read
+these files in place; it must not edit the installed dependency. Clone the repository
+when it needs to implement and verify a design-system change.
+
+The first-party `@noe` registry has local generation and consumer-test evidence. Its
+documented external endpoint must be treated as unavailable until deployment and
+official-MCP installation evidence exist; see `registry.md` and ADR 0007.
+
+## Retrieval and implementation
+
+Read `README.md`, `AGENTS.md`, and the focused documentation selected by `llms.txt`.
+Search `packages/registry/manifest.json` by capability, alias, and component name.
+For a candidate, read its `useWhen`, `doNotUseWhen`, `alternatives`, dependency,
+accessibility, and internationalization contracts before inspecting its source and
+Storybook story. If nothing fits, use the component lookup order in `AGENTS.md` and
+record the reason reuse was unsuitable.
+
+`AGENTS.md` defines the implementation constraints: reuse canonical components;
+preserve semantic tokens, i18n, RTL/bidi, portal direction, and progressive disclosure;
+and update the relevant source, stories, tests, registry metadata, and documentation
+together. Do not duplicate those instructions in a task prompt.
+
+## Evidence before completion
+
+Run checks proportional to the change. At minimum, use the applicable commands in
+`testing.md`; component changes normally require lint, typecheck, unit/browser tests,
+storybook accessibility coverage, registry validation, and RTL review. Test English,
+Persian, pseudo-LTR, and pseudo-RTL where the touched behavior is locale-sensitive.
+
+Report executed commands and observed outcomes. A plan, generated static registry, or
+unverified production URL is not evidence of deployment or successful installation.

package/docs/design-system/architecture.md

@@ -27,6 +27,12 @@ Product code consumes `@noe/*` components. Capability libraries such as TanStack
 
 The static reference app is dependency-free and uses the production token and locale contracts. React packages are source-complete but require a connected environment to install React and Storybook dependencies. The intended integration is React 19+ with a Vite/Tailwind CSS v4 application shell.
 
+`noecosystem-design` distributes this repository as an agent-readable source snapshot.
+It is not a compiled replacement for the internal `@noe/*` package boundaries and it
+does not provide a root runtime import. Consumers needing implementation access should
+work from a repository checkout; consumers needing a registry item must follow the
+deployment gate in ADR 0007.
+
 ## Decisions
 
 - One canonical message architecture and centralized locale metadata.

package/docs/design-system/gpt-agent-prompt.md

@@ -0,0 +1,56 @@
+# GPT implementation prompt
+
+Use this after `npm install noecosystem-design`. Replace the values in angle
+brackets, then send the complete prompt to the coding agent. Keep the static
+context below intact; put task-specific details only in `Task`.
+
+```text
+Role
+You are the NOE design-system implementation agent working in <TARGET_REPOSITORY>.
+Use the installed noecosystem-design package as a read-only source of design-system
+context.
+
+Task
+<DESCRIBE THE REQUESTED OUTCOME, SCOPE, AND ANY NON-NEGOTIABLE CONSTRAINTS>
+
+Success criteria
+- The requested outcome works in the target repository.
+- Reuse the relevant NOE capability or established product pattern before creating
+  new UI.
+- Preserve every applicable NOE contract, including tokens, i18n, RTL/bidi,
+  accessibility, stories, tests, registry metadata, and documentation.
+- Run checks that are proportionate to the change and report only results actually
+  observed.
+
+Context
+1. Read node_modules/noecosystem-design/AGENTS.md and llms.txt first.
+2. Search node_modules/noecosystem-design/packages/registry/manifest.json for the
+   requested capability. Read the matching record and focused documentation before
+   implementation files.
+3. AGENTS.md is the authoritative static constraint set. Follow it without restating
+   it in the response.
+
+Constraints
+- noecosystem-design is a source snapshot, not a runtime dependency. Do not import
+  from it; use a writable repository checkout for implementation work.
+- Do not present the public @noe registry as deployed or installable without direct
+  deployment evidence.
+- Do safe local investigation, edits, and validation autonomously. Ask before an
+  external write, destructive action, purchase, credential change, or material scope
+  expansion.
+
+Response
+Lead with the outcome. Then give:
+- Changed: only the material files or behavior changed.
+- Evidence: commands run and their observed results.
+- Blockers or risks: only if they materially affect completion.
+
+Stop rules
+Ask one focused question only when a material decision cannot be safely inferred.
+Otherwise, finish when the success criteria are met. If evidence is unavailable,
+state the exact gap instead of implying completion.
+```
+
+The prompt intentionally states the goal, constraints, autonomy boundary, expected
+output, and stop conditions once. Do not append a second copy of `AGENTS.md`; direct
+the agent to the installed file instead.

package/docs/design-system/registry.md

@@ -9,6 +9,10 @@
 
 When this output is mounted under the NOE site, its public paths are `https://noecosystem.com/design-system/r/registry.json` and `https://noecosystem.com/design-system/r/{name}.json`. The local publication test starts a static HTTP server against this output and verifies every declared URL. This proves the build layout, not the external deployment.
 
+The npm package `noecosystem-design` distributes registry source and metadata only. It
+does not host or deploy these URLs, and installing the npm package does not make
+`@noe/<item>` available through the shadcn CLI or MCP.
+
 Run `pnpm test:registry:consumer` to install `@noe/button` into a temporary consumer with the official shadcn CLI against the locally served registry. This is a pre-deployment protocol check; ADR 0007 still requires the same flow through the official MCP against the deployed domain before the registry can be described as agent-installable.
 
 Descriptions tell coding agents when to use an item and encode direction, accessibility and progressive-disclosure expectations. CI validates unique names, required metadata, valid referenced files and JSON parsing.

package/llms.txt

@@ -1,20 +1,47 @@
-# NOE Design System retrieval map
-
-- Repository overview: README.md
-- Agent rules: AGENTS.md
-- Architecture: docs/design-system/architecture.md
-- Brand audit: docs/design-system/noe-brand-audit.md
-- Foundations and tokens: docs/design-system/foundations.md, docs/design-system/tokens.md
-- Components: docs/design-system/components.md
-- Internationalization: docs/design-system/i18n.md
-- RTL and bidi: docs/design-system/rtl.md
-- Motion: docs/design-system/motion.md
-- Accessibility: docs/design-system/accessibility.md
-- Agentic UI: docs/design-system/agentic-ui.md
-- Testing and visual QA: docs/design-system/testing.md, docs/design-system/visual-qa.md
-- CI/CD and security: docs/design-system/ci-cd.md, docs/design-system/security.md
-- Registry and MCP: docs/design-system/registry.md, docs/design-system/mcp.md
-- Contribution workflow: docs/design-system/contributing.md
-- Decisions: docs/adr/
-- Static reference app: apps/web/
-- Storybook source: apps/storybook/
+# NOE Design System
+
+> Agent-readable source snapshot for the NOE multilingual, RTL-safe React design
+> system. The npm package is `noecosystem-design`; it is source metadata, not a
+> compiled runtime import. Internal workspace packages use `@noe/*`.
+
+## Status and non-assumptions
+
+- Read `AGENTS.md` before changing any source.
+- `packages/registry/manifest.json` is the canonical component catalog.
+- The `@noe` registry has local build and consumer-test evidence only. The documented
+  noecosystem.com endpoint is not deployment evidence; do not claim it is installable.
+- Do not import from `noecosystem-design`. Work from the source snapshot or clone the
+  repository when a writable, verifiable workspace is needed.
+
+## Retrieval order
+
+1. `docs/design-system/gpt-agent-prompt.md` — ready-to-paste task wrapper for GPT;
+   replace only its target repository and task fields.
+2. `README.md` — package scope, start path, commands, and distribution boundaries.
+3. `AGENTS.md` — mandatory design-system constraints and definition of done.
+4. `packages/registry/manifest.json` — capability search, ownership, use/do-not-use
+   rules, accessibility, i18n, dependencies, and story references.
+5. `packages/registry/r/<item>.json` — installable-item metadata and source closure.
+6. The owning package source under `packages/` and its Storybook story under
+   `apps/storybook/stories/`.
+
+## Focused documentation
+
+- Architecture and package boundaries: `docs/design-system/architecture.md`
+- GPT task wrapper: `docs/design-system/gpt-agent-prompt.md`
+- Agent workflow and retrieval: `docs/design-system/agent-guide.md`
+- Components and catalog terms: `docs/design-system/components.md`
+- Tokens and foundations: `docs/design-system/foundations.md`, `docs/design-system/tokens.md`
+- Locale, RTL, and bidi: `docs/design-system/i18n.md`, `docs/design-system/rtl.md`
+- Accessibility: `docs/design-system/accessibility.md`
+- Agent and tool-state UI: `docs/design-system/agentic-ui.md`
+- Registry status and protocol: `docs/design-system/registry.md`
+- Tests and visual evidence: `docs/design-system/testing.md`, `docs/design-system/visual-qa.md`
+- Security and automation: `docs/design-system/security.md`, `docs/design-system/ci-cd.md`
+- Architectural decisions: `docs/adr/`
+
+## Verification
+
+Use `pnpm check` for the full local gate. For focused changes, run the relevant
+`pnpm lint`, `pnpm typecheck`, `pnpm test`, browser/Storybook/E2E tests, and
+`pnpm verify` checks described in `docs/design-system/testing.md`.

package/package.json

@@ -1,10 +1,88 @@
 {
   "name": "noecosystem-design",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
+  "description": "Agent-readable NOE design-system source, registry metadata, and verification contracts.",
+  "keywords": [
+    "design-system",
+    "react",
+    "rtl",
+    "i18n",
+    "agent",
+    "shadcn",
+    "registry"
+  ],
+  "homepage": "https://noecosystem.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NOrchestration/noe-design-system.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NOrchestration/noe-design-system/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "AGENTS.md",
+    "README.md",
+    "apps/showcase/index.html",
+    "apps/showcase/package.json",
+    "apps/showcase/src",
+    "apps/showcase/tsconfig.json",
+    "apps/showcase/vite.config.ts",
+    "apps/storybook/.storybook",
+    "apps/storybook/package.json",
+    "apps/storybook/README.md",
+    "apps/storybook/stories",
+    "apps/storybook/vitest.config.ts",
+    "apps/web/app.js",
+    "apps/web/favicon.svg",
+    "apps/web/index.html",
+    "apps/web/README.md",
+    "apps/web/styles.css",
+    "biome.json",
+    "components.json",
+    "docs/adr",
+    "docs/design-system",
+    "llms.txt",
+    "packages/ai-ui/package.json",
+    "packages/ai-ui/src",
+    "packages/data-ui/package.json",
+    "packages/data-ui/src",
+    "packages/design-tokens/package.json",
+    "packages/design-tokens/src",
+    "packages/i18n/package.json",
+    "packages/i18n/src",
+    "packages/icons/package.json",
+    "packages/icons/src",
+    "packages/testing/package.json",
+    "packages/testing/src",
+    "packages/ui/package.json",
+    "packages/ui/src",
+    "packages/workflow-ui/package.json",
+    "packages/workflow-ui/src",
+    "packages/registry/README.md",
+    "packages/registry/catalog-index.json",
+    "packages/registry/component-audit.json",
+    "packages/registry/coss-adoption.json",
+    "packages/registry/docs-index.json",
+    "packages/registry/manifest.json",
+    "packages/registry/manifest.schema.json",
+    "packages/registry/r",
+    "packages/registry/registry.json",
+    "packages/registry/search-index.json",
+    "playwright.config.ts",
+    "pnpm-lock.yaml",
+    "pnpm-workspace.yaml",
+    "scripts",
+    "tests",
+    "tsconfig.base.json",
+    "tsconfig.json",
+    "tsconfig.verify.json",
+    "types",
+    "vitest.config.ts"
+  ],
   "type": "module",
   "packageManager": "pnpm@11.23.0",
   "engines": {

package/packages/registry/README.md

@@ -2,6 +2,9 @@
 
 This is a shadcn-compatible first-party registry source. Descriptions are written for both engineers and coding agents and encode semantic, accessibility, RTL, and usage expectations.
 
+`noecosystem-design` ships this directory as source metadata. It does not deploy the
+registry or make `@noe/<item>` remotely installable by itself.
+
 `pnpm build:static` emits this registry to `dist/r/registry.json` and `dist/r/{name}.json`. When mounted under the site, these are served at `https://noecosystem.com/design-system/r/registry.json` and `https://noecosystem.com/design-system/r/{name}.json`, the public URL layout required by the `@noe` registry template in `components.json`. It is not represented as deployed until a hosting workflow produces observable evidence and a consumer installation succeeds through the official shadcn MCP process.
 
 `pnpm test:registry:consumer` exercises the same registry protocol locally with the official shadcn CLI and a disposable consumer project before deployment.

package/.editorconfig

@@ -1,12 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-insert_final_newline = true
-indent_style = space
-indent_size = 2
-trim_trailing_whitespace = true
-
-[*.md]
-trim_trailing_whitespace = false

package/.github/CODEOWNERS

@@ -1,10 +0,0 @@
-# Default ownership. Organization teams do not exist yet; replace with
-# @NOrchestration/<team> slugs as soon as they are created.
-*                                         @AliMohammadiiii
-
-# Sensitive areas
-/packages/design-tokens/                  @AliMohammadiiii
-/packages/ui/                             @AliMohammadiiii
-/packages/i18n/                           @AliMohammadiiii
-/packages/registry/                       @AliMohammadiiii
-/.github/workflows/                       @AliMohammadiiii

package/.github/dependabot.yml

@@ -1,12 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: npm
-    directory: /
-    schedule:
-      interval: weekly
-    open-pull-requests-limit: 5
-  - package-ecosystem: github-actions
-    directory: /
-    schedule:
-      interval: weekly
-    open-pull-requests-limit: 5

package/.github/pull_request_template.md

@@ -1,17 +0,0 @@
-## Summary
-
-## Design rationale
-
-## Brand impact
-
-## Internationalization and RTL/LTR impact
-
-## Accessibility impact
-
-## Testing evidence
-
-## Screenshots
-
-## Risks and rollback
-
-## Migration notes