katalyst-forge 4.1.0__tar.gz → 4.2.0__tar.gz

katalyst_forge-4.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+site/
+node_modules/
+.pytest_cache/
+.ruff_cache/

katalyst_forge-4.2.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog — katalyst-forge
+
+All notable changes to the **katalyst-forge** bundle are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+As of 4.2.0 this package lives in its own repository
+(`esimplicityinc/katalyst-forge`) and tags use the plain `vX.Y.Z` prefix.
+Releases 4.1.0 and earlier were cut from the `katalyst-taxonomy` monorepo
+with `forge-vX.Y.Z` tags.
+
+The Forge **bundle `schema_version`** (declared in `bundle.py`) is the
+consumer-facing node-model contract and is versioned separately from this
+PyPI package version. A breaking node-type/model change bumps `schema_version`.
+
+---
+
+## [4.2.0] -- 2026-07-06
+
+Repo split (RIC-1070). First release from the standalone
+`esimplicityinc/katalyst-forge` repository, extracted from `katalyst-taxonomy`.
+No node-model changes; bundle `schema_version` stays **4**.
+
+### Added
+
+- Standalone repository: the Forge schema bundle, the 21 kata-forge agent
+  definitions and forge skills (extracted from `katalyst-taxonomy-agents`),
+  the creation/scaffold templates, the JSON Schemas, and the Forge lifecycle
+  docs now live and version together as one product.
+- JSON Schemas ship as package data in the wheel under `katalyst_forge/schemas/`.
+
+### Changed
+
+- Release tags drop the `forge-` prefix: this repo tags plain `vX.Y.Z`.
+- Docs move to https://esimplicityinc.github.io/katalyst-forge/.
+
+## [4.1.0] -- 2026-06-26
+
+Delivery-wing evolution (#138 / #140). Bundle `schema_version` stays **4** (additive within the v4 node-model); bundle node count 29 → 30.
+
+### Added
+
+- **`agent_run` node kind** (child of `work_item`): per-stage agent telemetry (`stages`, `totals`, `entered_status` / `exited_status`, `started` / `ended`) -- identifiers and counts only, no prompts or PII.
+- **`work_item.status` 10-state lifecycle enum** (`idea, proposed, accepted, planned, in_progress, blocked, delivered, validated, released, retired`), enforced through the engine's `FieldSpec.allowed_values`.
+- **Single `TRACES_TO` relationship** on `work_item`, disambiguated by the source field's target kind, covering `capabilities`, `user_needs`, `nfrs`, `adrs`, `design_specs`, `specifications`. Adding a new traceable target is a one-line field addition.
+- **`change_entry` -> `work_item` link** (`work_item_id` + `REFERENCES_WORK_ITEM`).
+
+### Changed
+
+- Minimum `katalyst-engine` raised to `>=4.1` -- the `work_item` status enum relies on `FieldSpec.allowed_values`, added in engine 4.1.0.
+- Replaced the per-target relationship definitions (`implements_capability`, `addresses_need`, `satisfies_nfr`) with the single `TRACES_TO` edge. `road_id` / `REFERENCES_ROAD_ITEM` on `change_entry` retained as a deprecated alias of `work_item_id`.
+
+## [4.0.0] -- 2026-06-16
+
+Bundle `schema_version` bumped to **4** and manifest version to **4.0** to reflect the breaking node-kind removals below.
+
+### Removed
+
+- **BREAKING: Relocated mechanism kinds out of the Forge bundle** (#79/#82). Six node kinds no longer ship in Forge: `template`, `action`, `template_overlay`, `dx`, `cicd_job_template`, and `cicd_workflow_template`. Scaffolding/CI-CD mechanisms are now provided by the taxonomy runtime and its plugins rather than declared as Forge node types. Documents using these kinds must migrate (`kata tax migrate`); `template_overlay` becomes `node_wiring`.
+
+### Added
+
+- **`design_spec` node type** in the Design wing (#44). A pre-executable specification artifact sitting between `user_need` and `specification` in the intent chain, capturing visual structure, interaction flows, and testable design constraints. Includes a `design_specs` field + `IMPLEMENTS_DESIGN` cross-reference on `specification`, and the `DESIGNS_FOR_NEED` / `DESIGNS_CAPABILITY` / `IMPLEMENTS_DESIGN` relationships. Brings the Forge bundle to **29 node types**.
+
+## [3.0.1] -- 2026-06-11
+
+### Changed
+- **Corrected bundle `schema_version` to `3`** to reflect the breaking `user_story` → `user_need` rename that shipped in 3.0.0. The `BundleManifest.version` was bumped to `3.0` and `SchemaDefinition.schema_version` to `3`.
+- First release published independently via the per-package `forge-v*` release pipeline.
+
+## [3.0.0] -- 2026-06-10
+
+### Changed
+- **BREAKING: Renamed `user_story` node type to `user_need`** in the Design wing. The kind (`user_story` → `user_need`), directory (`user_stories/` → `user_needs/`), display labels (`User Story`/`User Stories` → `User Need`/`User Needs`), and Neo4j label (`UserStory` → `UserNeed`) all changed. Creation template `user_story.yaml.j2` → `user_need.yaml.j2`. No backward-compatibility alias is provided. (RIC-616)
+
+### Added
+- **`katalyst-xbrl` bundle** companion node types and the pluggable parser registry landed in the same `3.0.0` release train (see root `CHANGELOG.md` for cross-package detail).
+
+---
+
+> Versions prior to 3.0.0 were released in lockstep with `katalyst-taxonomy`
+> under the umbrella `vX.Y.Z` tags. See the root `CHANGELOG.md` for that history.

katalyst_forge-4.2.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2024 eSimplicity
+
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying, distribution,
+modification, or use of this software, via any medium, is strictly prohibited.
+
+This software is licensed for internal use within eSimplicity only.

{katalyst_forge-4.1.0 → katalyst_forge-4.2.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: katalyst-forge
-Version: 4.1.0
-Summary: The Forge bundle — 31 node-type definitions for software delivery taxonomy
+Version: 4.2.0
+Summary: Katalyst Forge: the delivery-lifecycle bundle (node kinds, wings, agents, templates, schemas)
 Author: eSimplicity
 License: Proprietary
+License-File: LICENSE
 Requires-Python: >=3.12
 Requires-Dist: katalyst-engine<5,>=4.1

katalyst_forge-4.2.0/pyproject.toml

@@ -0,0 +1,91 @@
+[project]
+name = "katalyst-forge"
+version = "4.2.0"
+description = "Katalyst Forge: the delivery-lifecycle bundle (node kinds, wings, agents, templates, schemas)"
+license = { text = "Proprietary" }
+requires-python = ">=3.12"
+authors = [
+    { name = "eSimplicity" }
+]
+dependencies = [
+    "katalyst-engine>=4.1,<5",
+]
+
+[project.entry-points."katalyst_engine.bundles"]
+forge = "katalyst_forge.bundle:ForgeBundle"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/katalyst_forge"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.hatch.build]
+include = [
+    "src/katalyst_forge/**/*.py",
+    "src/katalyst_forge/**/*.yaml.j2",
+    "src/katalyst_forge/**/*.yaml",
+    "src/katalyst_forge/**/*.json",
+    "src/katalyst_forge/**/*.tf",
+    "src/katalyst_forge/**/*.hcl",
+    "src/katalyst_forge/**/*.md",
+    "src/katalyst_forge/**/*.just",
+    "src/katalyst_forge/**/*.sh",
+    "src/katalyst_forge/**/Justfile",
+    "src/katalyst_forge/**/Dockerfile",
+    "src/katalyst_forge/**/.dockerignore",
+    "src/katalyst_forge/**/.env.example",
+    "src/katalyst_forge/py.typed",
+]
+
+# JSON Schemas ship as package data inside the wheel so consumers
+# (katalyst-taxonomy's importlib.resources fallback) can resolve them
+# without a repo checkout.
+[tool.hatch.build.targets.wheel.force-include]
+"schemas" = "katalyst_forge/schemas"
+
+# The wheel is built from the sdist, so the sdist must carry schemas/
+# for the wheel force-include to resolve.
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/katalyst_forge/**",
+    "schemas/**",
+    "tests/**",
+    "CHANGELOG.md",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.2",
+    "ruff>=0.5",
+    "pyright>=1.1",
+    # test_wing_schemas.py validates the shipped JSON Schemas
+    "jsonschema>=4.22",
+    "referencing>=0.35",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "B", "I"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pyright]
+include = ["src", "tests"]
+venvPath = "."
+venv = ".venv"
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+addopts = ["-ra"]
+testpaths = ["tests"]
+pythonpath = ["src"]

katalyst_forge-4.2.0/schemas/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Schema Changelog
+
+All notable changes to the Katalyst Taxonomy schemas will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+- **BREAKING: Renamed `user_story` node type to `user_need`** (Forge bundle schema_version → 3). The `kind`, directory (`user_stories/` → `user_needs/`), display labels, and Neo4j label changed; no backward-compatibility alias. Shipped in `katalyst-forge` 3.0.0; schema_version metadata corrected in 3.0.1.
+
+### Added
+- `references` annotation on cross-reference attributes declaring target node types
+- `rel_type` annotation for semantic relationship names (e.g., `TESTS_CAPABILITY`, `PROVIDES_CAPABILITY`)
+- `cross_references` field in registry.json per node type
+- Environment node type (`node_types/system/environment.yaml`) in system wing
+
+### Removed
+- **`subsystem` node type** — Systems are now self-referential (a system can be a child of another system). The `subsystem` taxonomyNodeType has been removed from `nodes/technical.schema.json`, along with its if/then conditional block. All enum/scope lists across plugin manifests (`capabilities`, `design`, `practices`, `archetypes`) and agent schemas (`config.schema.json`, `agent.schema.json`) have been updated to remove `subsystem` references. Existing subsystem nodes should be migrated to nested systems.
+
+---
+
+## [0.16.0] - 2026-03-19
+
+### Added
+- **Per-wing schema split** — `taxonomy-node.schema.json` is now a slim coordinator that delegates to four wing schemas via `$ref`:
+  - `nodes/common.schema.json` — shared field definitions (metadata, specBase)
+  - `nodes/technical.schema.json` — system, subsystem, stack, layer, library
+  - `nodes/portfolio.schema.json` — organization, program, project (with type-specific spec blocks and if/then guards)
+  - `nodes/organizational.schema.json` — team, team_member, user, practice_area, competency (with type-specific spec blocks and if/then guards)
+  - `nodes/design.schema.json` — 15 design types (DDD, capabilities, user research, delivery, architecture, BDD)
+- **`$ref` resolution infrastructure** — new `schema_registry.py` module builds a `referencing.Registry` from all schema files, enabling cross-file `$ref` resolution in Python validation
+- **Cross-wing spec guards** — each wing explicitly forbids type-specific spec blocks from other wings (e.g. `spec.organization` forbidden on technical wing nodes)
+- `practice_area` and `competency` moved to the Organizational wing (alongside team, team_member, user)
+
+### Changed
+- `taxonomy-node.schema.json` reduced from 576 lines to ~24 lines (coordinator only)
+- `taxonomy_linter.py` and `plugin_linter.py` now pass a `referencing.Registry` to `Draft202012Validator`, fixing previously silent `$ref` resolution failures in plugin schemas
+- `_shared.py` classifier updated to detect slug pattern errors regardless of oneOf index prefix in schema_path
+- `pyproject.toml` — added explicit `referencing>=0.35` dependency
+
+### Fixed
+- **Plugin `$ref` resolution** — 30+ cross-file `$ref`s in plugin schemas (pointing at `../common/plugin-requirement.schema.json` and `../common/environment-contract.schema.json`) are now actually resolved during Python-side validation. Previously they were silently skipped.
+
+---
+
+## [0.15.0] - 2026-03-17
+
+### Added
+- **Design plugin** (`katalyst.taxonomy.plugins.design/v1alpha`) — 16 resource kinds across 6 domain areas:
+  - **Capabilities:** `Capability`, `CapabilityRelationship` — business/technical capability modeling with node bindings
+  - **DDD:** `BoundedContext`, `Aggregate`, `ValueObject`, `DomainEvent`, `GlossaryTerm` — Domain-Driven Design tactical patterns
+  - **User Research:** `UserType`, `UserStory`, `UseCase` — personas, stories, and interaction flows
+  - **Delivery Lifecycle:** `RoadItem`, `ChangeEntry` — roadmap governance with ADR/BDD/NFR compliance tracking
+  - **Architecture Decisions:** `Adr`, `Nfr` — Architecture Decision Records and Non-Functional Requirements
+  - **Executable Specs (BDD):** `Feature`, `Scenario` — BDD feature and scenario metadata with Given/When/Then steps
+- **Practices plugin** (`katalyst.taxonomy.plugins.practices/v1alpha`) — 2 resource kinds:
+  - `PracticeArea` — team knowledge organized around 6 pillars (strategy, standards, frameworks, libraries, processes, measures)
+  - `Competency` — skills with 3 level definitions (basic, intermediate, advanced) and dependency DAG
+- `schemas/plugins/design/manifest.json` — design plugin manifest with 16 registered schemas
+- `schemas/plugins/practices/manifest.json` — practices plugin manifest with 2 registered schemas
+- 14 new `taxonomyNodeType` values added to `taxonomy-node.schema.json` for design and practices kinds
+- Plugin schema validation wired into `kata tax lint` for both plugins
+
+### Changed
+- `schemas/plugins/registry.json` — added `design` and `practices` plugins; marked `capabilities` as deprecated
+- `schemas/plugins/capabilities/manifest.json` — added `deprecated: true` and `replacedBy: "design"` fields
+
+---
+
+## [0.14.0] - 2026-03-14
+
+### Added
+- `plugins/commitguard/commitguard-config.schema.json` — CommitGuardConfig schema for declaring supported hook tools (pre-commit, Husky, Lefthook) with install/generate commands
+- `plugins/commitguard/commitguard-binding.schema.json` — CommitGuardBinding schema for mapping kata actions and additional hooks to a specific layer type per tool
+- `hooks/hook-config.schema.json` — Schema for `.katalyst-hooks.yaml` user configuration (tool selection, kata_actions by layer type, additional_hooks)
+- `plugins/extensions/extension.schema.json` — Extension plugin schema (existing, now with bundled seed content)
+
+---
+
+## [0.13.0] - 2026-03-09
+
+### Added
+- Initial public schema hosting setup
+- `index.json` manifest listing all available schemas
+- Version and timestamp metadata in index
+- `katalyst-lock.schema.json` - Lock file schema for tracking installed components and versions
+
+### Changed
+- Replaced `org_unit` taxonomy node type with five new types: `organization`, `program`, `project`, `team`, `team_member`
+- `PARENT_NODE_TYPES` now supports polymorphic parents (`project` can be child of `program` or `organization`; `team` can be child of `organization` or another `team`)
+- Added conditional spec blocks: `spec.organization`, `spec.program`, `spec.project`, `spec.team`, `spec.teamMember`
+
+### Removed
+- `org_unit` taxonomy node type (replaced by `team`)
+
+## [0.1.0] - 2025-01-11
+
+### Added
+- Core schemas:
+  - `taxonomy-node.schema.json` - TaxonomyNode definition (system, subsystem, stack, layer, user, organization, program, project, team, team_member)
+  - `environment.schema.json` - Environment configuration schema
+
+- Plugin schemas:
+  - `plugins/registry.json` - Plugin registry manifest
+  - `plugins/capabilities/` - Capability and CapabilityRelationship schemas
+  - `plugins/cicd/` - CI/CD workflow, job, and stage template schemas
+  - `plugins/layer-actions/` - Layer action catalog schemas
+  - `plugins/layer-types/` - Layer type definition schemas
+  - `plugins/tools/` - Tool catalog schemas
+
+### Schema Features
+- JSON Schema Draft 2020-12 compliance
+- Canonical `$id` URLs at `https://prima.dev/schemas/katalyst/`
+- Support for organizational wing (user, organization, program, project, team, team_member) taxonomy nodes
+- Plugin extension system via `spec.extensions` block

katalyst_forge-4.2.0/schemas/README.md

@@ -0,0 +1,300 @@
+# Katalyst Taxonomy Schemas
+
+This directory contains the **v1** JSON Schema definitions for Katalyst Taxonomy resources.
+
+> **Note:** The v2 modeling engine generates per-kind JSON schemas from LinkML
+> definitions. V2 generated schemas live in `taxonomy/src/katalyst_taxonomy/engine/generated/schemas/`
+> and are produced by `kata tax build-types`. Both v1 and v2 schemas coexist
+> during the transition period. See `plan.md` for migration status.
+
+## Overview
+
+| Schema | Description |
+|--------|-------------|
+| [`taxonomy-node.schema.json`](taxonomy-node.schema.json) | Coordinator schema — delegates to per-wing schemas via `$ref` |
+| [`nodes/common.schema.json`](nodes/common.schema.json) | Shared field definitions (metadata, spec base) |
+| [`nodes/technical.schema.json`](nodes/technical.schema.json) | Technical wing: system, stack, layer, library |
+| [`nodes/portfolio.schema.json`](nodes/portfolio.schema.json) | Portfolio wing: organization, program, project |
+| [`nodes/organizational.schema.json`](nodes/organizational.schema.json) | Organizational wing: team, team\_member, practice\_area, competency |
+| [`nodes/design.schema.json`](nodes/design.schema.json) | Design wing: DDD, capabilities, user research, delivery, architecture, BDD |
+| [`environment.schema.json`](environment.schema.json) | Environment configuration |
+| [`katalyst-lock.schema.json`](katalyst-lock.schema.json) | Lock file for tracking installed components |
+| [`plugins/extensions/`](plugins/extensions/) | Extension plugin schema |
+| [`hooks/hook-config.schema.json`](hooks/hook-config.schema.json) | `.katalyst-hooks.yaml` configuration |
+
+## Schema Version
+
+- **V1 API Version**: `katalyst.taxonomy/v1alpha` (schemas in this directory)
+- **V2 API Version**: `katalyst.taxonomy/v2alpha` (schemas in `taxonomy/src/katalyst_taxonomy/engine/generated/schemas/`)
+- **JSON Schema Draft**: 2020-12
+- **Canonical URL Base**: `https://prima.dev/schemas/katalyst/`
+
+The parser accepts both v1alpha and v2alpha documents. V2 documents use
+`kind` as the node type directly (e.g., `kind: system`) instead of the
+v1 pattern of `kind: TaxonomyNode` + `taxonomyNodeType: system`.
+
+## Core Schemas
+
+### TaxonomyNode (`taxonomy-node.schema.json`)
+
+The coordinator schema for all taxonomy nodes. It delegates to four per-wing schemas via `$ref`:
+
+| Wing | File | Node Types |
+|------|------|------------|
+| **Technical** | `nodes/technical.schema.json` | system, stack, layer, library |
+| **Portfolio** | `nodes/portfolio.schema.json` | organization, program, project |
+| **Organizational** | `nodes/organizational.schema.json` | team, team\_member, practice\_area, competency |
+| **Design** | `nodes/design.schema.json` | business\_domain\_model, capability, user\_type, user\_story, use\_case, work\_item, adr, nfr, change\_entry, specification, assertion |
+
+Shared field definitions (metadata, spec base) live in `nodes/common.schema.json` and are referenced by each wing.
+
+```yaml
+apiVersion: katalyst.taxonomy/v1alpha
+kind: TaxonomyNode
+metadata:
+  name: my-service          # DNS-compatible name
+  labels: {}                # Key-value labels
+taxonomyNodeType: layer     # system | stack | layer | organization | program | project | team | team_member
+spec:
+  description: "My service"
+  owners:
+    - team@example.com
+  environments:
+    - dev
+    - prod
+  parents:
+    node: my-stack          # Parent reference
+  dependsOn:
+    nodes:
+      - other-layer         # Dependencies
+  extensions: {}            # Plugin-specific data
+```
+
+**Key Constraints:**
+- `metadata.name` must match pattern `^[a-z0-9]([-_a-z0-9]{0,61}[a-z0-9])?$`
+- `spec.environments` must have at least one entry
+- `spec.parents.node` required for all types except `system` and `organization`
+
+### Environment (`environment.schema.json`)
+
+Defines environment configurations with template replacements.
+
+```yaml
+apiVersion: katalyst.taxonomy/v1alpha
+kind: Environment
+metadata:
+  name: prod
+spec:
+  description: "Production environment"
+  templateReplacements:
+    ENVIRONMENT: PROD
+    REPLICA_COUNT: "3"
+```
+
+### Lock File (`katalyst-lock.schema.json`)
+
+Tracks installed components and versions.
+
+```yaml
+apiVersion: katalyst.taxonomy/v1alpha
+kind: KatalystLock
+metadata:
+  generatedAt: "2025-01-15T10:30:00Z"
+  generatedBy: "kata tax init"
+  katalystVersion: "1.0.0"
+installed:
+  core:
+    version: "1.0.0"
+    schemaVersion: "v1alpha"
+    installedAt: "2025-01-15T10:30:00Z"
+    source: bundled
+  plugins:
+    layer_types:
+      version: "1.0.0"
+      installedAt: "2025-01-15T10:30:00Z"
+      source: bundled
+      canonical:
+        - app-docker
+        - k8s-kustomize
+```
+
+## Plugin Schemas
+
+Plugin schemas extend the core taxonomy with additional resource types.
+
+| Directory | Plugin | Description |
+|-----------|--------|-------------|
+| [`plugins/capabilities/`](plugins/capabilities/) | Capabilities | Service capability definitions *(deprecated -- use design)* |
+| [`plugins/design/`](plugins/design/) | Design | System design: capabilities, DDD, user research, delivery, architecture, BDD (16 kinds) |
+| [`plugins/practices/`](plugins/practices/) | Practices | Team knowledge with practice areas and competencies (2 kinds) |
+| [`plugins/layer-actions/`](plugins/layer-actions/) | Actions | Executable actions bound to layer types |
+| [`plugins/layer-types/`](plugins/layer-types/) | Layer Types | Scaffolding template definitions |
+| [`plugins/cicd/`](plugins/cicd/) | CI/CD | Pipeline workflow and job templates |
+| [`plugins/tools/`](plugins/tools/) | Tools | Tool catalog definitions |
+| [`plugins/extensions/`](plugins/extensions/) | Extensions | Conditional layer type augmentation |
+| [`hooks/`](hooks/) | Hooks | `.katalyst-hooks.yaml` user configuration |
+
+### Plugin Registry
+
+The [`plugins/registry.json`](plugins/registry.json) file lists all available plugins:
+
+```json
+{
+  "plugins": [
+    { "name": "capabilities", "manifest": "capabilities/manifest.json" },
+    { "name": "layer_actions", "manifest": "layer-actions/manifest.json" },
+    { "name": "layer_types", "manifest": "layer-types/manifest.json" },
+    { "name": "tools", "manifest": "tools/manifest.json" },
+    { "name": "cicd", "manifest": "cicd/manifest.json" }
+  ]
+}
+```
+
+### Layer Types (`plugins/layer-types/`)
+
+```yaml
+apiVersion: katalyst.taxonomy.plugins.layer_types/v1alpha
+kind: LayerType
+metadata:
+  name: app-docker
+spec:
+  description: "Docker application scaffold"
+  template: templates/app-docker
+  defaultLayerDir: app
+  optionalPaths:
+    - README.md
+    - "*/Dockerfile"
+```
+
+### Layer Actions (`plugins/layer-actions/`)
+
+```yaml
+apiVersion: katalyst.taxonomy.plugins.actions/v1alpha
+kind: Action
+metadata:
+  name: build-docker
+  labels:
+    layerType: app-docker
+spec:
+  description: "Build Docker image"
+  type: shell
+  when: pre
+  run: docker build -t $IMAGE_NAME .
+```
+
+### Capabilities (`plugins/capabilities/`)
+
+```yaml
+apiVersion: katalyst.taxonomy.plugins.capabilities/v1alpha
+kind: Capability
+metadata:
+  name: user-authentication
+spec:
+  description: "OAuth2/OIDC authentication service"
+  categories:
+    - security
+    - identity
+```
+
+### CI/CD Templates (`plugins/cicd/`)
+
+```yaml
+apiVersion: katalyst.taxonomy.plugins.cicd/v1alpha
+kind: Stage
+metadata:
+  name: ci
+spec:
+  description: "Continuous Integration stage"
+```
+
+### Hook Config (`hooks/`)
+
+Schema for the user-facing `.katalyst-hooks.yaml` file:
+
+```yaml
+apiVersion: katalyst.taxonomy.hooks/v1alpha
+kind: HookConfig
+spec:
+  tool: pre-commit
+  kata_actions:
+    app-docker:
+      - action: lint
+        stage: pre-commit
+      - action: build
+        stage: pre-push
+    iac-terragrunt:
+      - action: validate
+        stage: pre-commit
+  additional_hooks:
+    - name: hadolint
+      stage: pre-commit
+      run: hadolint Dockerfile
+      files: Dockerfile
+```
+
+## Validation
+
+### Using the CLI
+
+```bash
+# Validate all taxonomy documents
+kata tax lint
+
+# JSON output for CI
+kata tax lint --json
+```
+
+### Using jsonschema (Python)
+
+```bash
+pip install jsonschema
+
+# Validate a single document
+python -m jsonschema my-node.yaml -i schemas/taxonomy-node.schema.json
+```
+
+### IDE Integration
+
+Most IDEs support JSON Schema validation for YAML files:
+
+**VS Code** (with YAML extension):
+```yaml
+# .vscode/settings.json
+{
+  "yaml.schemas": {
+    "./schemas/taxonomy-node.schema.json": ["**/layer.yaml", "**/stack.yaml", "**/system.yaml"]
+  }
+}
+```
+
+**JetBrains IDEs**:
+Configure in Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings.
+
+## Versioning
+
+Schemas follow semantic versioning within the `apiVersion` field:
+
+- **Alpha** (`v1alpha`): Breaking changes possible
+- **Beta** (`v1beta`): Mostly stable, minor changes possible  
+- **Stable** (`v1`): Backwards compatible
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## Extending Schemas
+
+To add custom fields to taxonomy nodes, use the `spec.extensions` block:
+
+```yaml
+spec:
+  extensions:
+    myPlugin:
+      customField: value
+```
+
+For creating new plugin schemas, see the [Plugin Architecture](../docs/extending/plugin-architecture.md) documentation.
+
+## Resources
+
+- [Core Concepts](../docs/users/core-concepts.md) - Understanding the taxonomy model
+- [Plugin Architecture](../docs/extending/plugin-architecture.md) - Creating plugins
+- [Creating Layer Types](../docs/extending/creating-layer-types.md) - Layer type schemas