docs(forge): define concept taxonomy

AGENTS.md

@@ -2,7 +2,9 @@
 
 Forge is a multilingual engineering lab organized by technology concepts, not programming languages.
 
-- Keep every experiment self-contained, including its dependencies, commands, and context.
+- Keep every experiment self-contained, including its dependencies, commands, and context, and follow the [experiment README guideline](docs/experiment-readme-guideline.md) for its documentation.
+- Before creating a top-level concept directory, follow the [concept guidelines](docs/concepts.md): reuse an existing concept when it fits, and create one only for a meaningfully distinct engineering focus.
+- Update the root README experiment table whenever adding a new experiment or repository; keep the `Experiment` and `Purpose` columns, and insert the row alphabetically by concept, then by experiment name within a repeated concept.
 - Write technical artifacts in English unless an experiment explicitly requires another language.
 - Keep documentation and tests with the behavior they describe.
 - Preserve focused scope; do not expand one experiment into unrelated repository-wide infrastructure.

README.md

@@ -1,29 +1,29 @@
-# forge
+# ⚒️ forge
 
 A space for experimenting with emerging standards, architectures, and engineering concepts.
 
 Here, ideas are tested through working software: assumptions are challenged, tradeoffs are made explicit, and learning matters more than convention.
 
 ## Experiments
 
-New experiments should follow the [experiment README guideline](docs/experiment-readme-guideline.md) so their intent, execution, and verification remain useful to both humans and agents.
+Use the [concept guidelines](docs/concepts.md) to place experiments by engineering question. New experiments should also follow the [experiment README guideline](docs/experiment-readme-guideline.md) so their intent, execution, and verification remain useful to both humans and agents.
 
-| Experiment | Status | Purpose |
-| --- | --- | --- |
-| [HTTP QUERY / Node.js + Fastify](http-query-rfc/node-fastify/) | Active experiment | Explore body-bearing HTTP QUERY requests with Fastify. |
-| [Declarative desktop UI / Qt Quick + PySide6](declarative-desktop-ui/qt-quick/python-pyside6/) | Migrated snapshot | Compare a QML view with a minimal Python bootstrap. |
-| [Event-driven desktop UI / Qt Widgets + PySide6](event-driven-desktop-ui/qt-widgets/python-pyside6/) | Migrated snapshot | Demonstrate widget composition and signal-slot interaction. |
-| [Batch processing / Spring Batch log aggregation](batch-processing/log-aggregation/java-spring-batch/) | Migrated snapshot | Import CSV log records through a chunk-oriented batch job. |
-| [Database sharding / order service with Spring and ShardingSphere](database-sharding/order-service/java-spring-shardingsphere/) | Migrated snapshot | Route orders across two MySQL databases by order ID parity. |
-| [API client CLI / TMDB + Cobra](api-client-cli/tmdb/go-cobra/) | Migrated snapshot | Explore a typed API client behind a Cobra command interface. |
-| [API wrapper / cached weather + `net/http`](api-wrapper/cached-weather/go-net-http/) | Migrated snapshot | Wrap a weather API with Redis caching and per-IP rate limiting. |
-| [REST API / routing CRUD with Chi](rest-api/routing-crud/go-chi/) | Migrated snapshot | Explore resource-oriented routing while proxying CRUD requests. |
-| [Content management / Markdown notes with SQLite](content-management/markdown-notes/go-sqlite/) | Migrated snapshot | Persist notes behind a repository boundary with a framework-free client. |
-| [In-memory storage / HTTP key-value store](in-memory-storage/key-value-store/go-http/) | Migrated snapshot | Expose a concurrent map through HTTP with Prometheus instrumentation. |
-| [Numeric precision / money with decimal libraries](numeric-precision/money/go-decimal/) | Migrated snapshot | Compare floating-point pitfalls with rational and decimal representations. |
-| [Batch processing / generic jobs with GoBatch](batch-processing/generic-jobs/go-gobatch/) | Archived learning | Preserve a parked reader-processor-writer and partitioning proof of concept. |
-| [Web framework basics / Express Hello World](web-framework-basics/hello-world/node-express/) | Migrated snapshot | Demonstrate the minimum Express route and server lifecycle. |
-| [Application scaffolding / Express Generator](application-scaffolding/express-generator/node-express/) | Migrated snapshot | Record the conventional routers, views, middleware, and error boundaries generated for Express. |
-| [REST API / TODO service with Express and Sequelize](rest-api/todo-service/node-express-sequelize/) | Migrated snapshot | Separate routing, controllers, and PostgreSQL persistence in a small task service. |
-| [REST API / DNF history with FastAPI](rest-api/system-history/python-fastapi/) | Migrated snapshot | Parse local DNF transaction history through an asynchronous HTTP endpoint. |
-| [Web framework basics / FastAPI request validation](web-framework-basics/request-validation/python-fastapi/) | Migrated snapshot | Demonstrate typed path, query, and body validation with FastAPI and Pydantic. |
+| Experiment | Purpose |
+| --- | --- |
+| [API client CLI / TMDB + Cobra](api-client-cli/tmdb/go-cobra/) | Explore a typed API client behind a Cobra command interface. |
+| [API wrapper / cached weather + `net/http`](api-wrapper/cached-weather/go-net-http/) | Wrap a weather API with Redis caching and per-IP rate limiting. |
+| [Application scaffolding / Express Generator](application-scaffolding/express-generator/node-express/) | Record the conventional routers, views, middleware, and error boundaries generated for Express. |
+| [Batch processing / generic jobs with GoBatch](batch-processing/generic-jobs/go-gobatch/) | Preserve a parked reader-processor-writer and partitioning proof of concept. |
+| [Batch processing / Spring Batch log aggregation](batch-processing/log-aggregation/java-spring-batch/) | Import CSV log records through a chunk-oriented batch job. |
+| [Content management / Markdown notes with SQLite](content-management/markdown-notes/go-sqlite/) | Persist notes behind a repository boundary with a framework-free client. |
+| [Database sharding / order service with Spring and ShardingSphere](database-sharding/order-service/java-spring-shardingsphere/) | Route orders across two MySQL databases by order ID parity. |
+| [Declarative desktop UI / Qt Quick + PySide6](declarative-desktop-ui/qt-quick/python-pyside6/) | Compare a QML view with a minimal Python bootstrap. |
+| [Event-driven desktop UI / Qt Widgets + PySide6](event-driven-desktop-ui/qt-widgets/python-pyside6/) | Demonstrate widget composition and signal-slot interaction. |
+| [HTTP QUERY / Node.js + Fastify](http-query-rfc/node-fastify/) | Explore body-bearing HTTP QUERY requests with Fastify. |
+| [In-memory storage / HTTP key-value store](in-memory-storage/key-value-store/go-http/) | Expose a concurrent map through HTTP with Prometheus instrumentation. |
+| [Numeric precision / money with decimal libraries](numeric-precision/money/go-decimal/) | Compare floating-point pitfalls with rational and decimal representations. |
+| [REST API / DNF history with FastAPI](rest-api/system-history/python-fastapi/) | Parse local DNF transaction history through an asynchronous HTTP endpoint. |
+| [REST API / routing CRUD with Chi](rest-api/routing-crud/go-chi/) | Explore resource-oriented routing while proxying CRUD requests. |
+| [REST API / TODO service with Express and Sequelize](rest-api/todo-service/node-express-sequelize/) | Separate routing, controllers, and PostgreSQL persistence in a small task service. |
+| [Web framework basics / Express Hello World](web-framework-basics/hello-world/node-express/) | Demonstrate the minimum Express route and server lifecycle. |
+| [Web framework basics / FastAPI request validation](web-framework-basics/request-validation/python-fastapi/) | Demonstrate typed path, query, and body validation with FastAPI and Pydantic. |

docs/concepts.md

@@ -0,0 +1,56 @@
+# Forge concept guidelines
+
+Use concepts to group experiments by the primary engineering question they investigate. The hierarchy is concept first, experiment second, and language or runtime implementation last.
+
+A concept is not a language, framework, business domain, delivery shape, or repository of origin. Those details describe how an experiment is implemented or delivered, not why it exists.
+
+## Placement process
+
+1. Identify the experiment's primary hypothesis or engineering question.
+2. Compare that question with the admission boundaries and exclusions below.
+3. Reuse an existing concept when its boundary fits, even if the technology or delivery shape differs.
+4. Do not classify by language, framework, API style, executable type, or source repository.
+5. If no existing concept fits, propose a new concept instead of creating it immediately.
+6. Explain the proposed name, admission boundary, exclusions, why existing concepts do not fit, and which future experiments could reuse it.
+7. Wait for explicit approval before updating the taxonomy or creating its directory.
+8. After placement is approved, add or update the experiment record in the root [experiment table](../README.md#experiments).
+
+## Target taxonomy
+
+The taxonomy reflects current experiment evidence. It can evolve when new experiments expose a genuinely distinct engineering concern; it is not an immutable list.
+
+| Concept | Admit when the primary question is about | Exclude when the primary question is about | Current experiments |
+| --- | --- | --- | --- |
+| `application-boundaries` | Application bootstrap, layering, or responsibility and dependency boundaries. | Protocol semantics or storage algorithms. | [Express Hello World](../web-framework-basics/hello-world/node-express/), [Express Generator](../application-scaffolding/express-generator/node-express/), [Markdown notes](../content-management/markdown-notes/go-sqlite/), [TODO service](../rest-api/todo-service/node-express-sequelize/) |
+| `batch-processing` | Staged jobs, chunks, partitioning, or execution metadata. | Request-response APIs or general application layering without a batch lifecycle. | [GoBatch generic jobs](../batch-processing/generic-jobs/go-gobatch/), [Spring Batch log aggregation](../batch-processing/log-aggregation/java-spring-batch/) |
+| `desktop-ui-architecture` | Desktop UI composition, responsibility boundaries, or event flow. | Web delivery or non-UI application structure. | [Qt Quick](../declarative-desktop-ui/qt-quick/python-pyside6/), [Qt Widgets](../event-driven-desktop-ui/qt-widgets/python-pyside6/) |
+| `external-service-integration` | Consuming, adapting, caching, rate-limiting, or otherwise protecting access to an upstream service. | HTTP behavior owned by the local service or storage as the primary concern. | [TMDB client CLI](../api-client-cli/tmdb/go-cobra/), [cached weather](../api-wrapper/cached-weather/go-net-http/) |
+| `http-semantics-and-contracts` | HTTP method semantics, routing, request validation, representations, or API contracts. | General application layering, upstream adaptation, or storage internals. | [HTTP QUERY](../http-query-rfc/node-fastify/), [Chi routing CRUD/proxy](../rest-api/routing-crud/go-chi/), [DNF history](../rest-api/system-history/python-fastapi/), [FastAPI validation](../web-framework-basics/request-validation/python-fastapi/) |
+| `storage-architecture` | Storage semantics, topology, concurrency, or partitioning where storage itself is the primary subject. | Persistence used only as an implementation detail behind application boundaries. | [in-memory key-value store](../in-memory-storage/key-value-store/go-http/), [database sharding](../database-sharding/order-service/java-spring-shardingsphere/) |
+| `numeric-precision` | Numeric representation, arithmetic correctness, rounding, or precision tradeoffs. | Domain modeling where numeric behavior is incidental. | [money representations](../numeric-precision/money/go-decimal/) |
+
+## When to create a new concept
+
+Create one only when every statement is true:
+
+- [ ] No existing admission boundary describes the primary hypothesis.
+- [ ] The distinction is an engineering concern, not an implementation or packaging detail.
+- [ ] The name would remain useful across languages, frameworks, domains, and repository sources.
+- [ ] Another experiment could plausibly investigate the same concern.
+- [ ] The boundary and exclusions can be stated clearly.
+
+If any statement is false, reuse the closest existing concept and clarify the experiment name or README instead.
+
+## Classification anti-patterns
+
+| Avoid | Why |
+| --- | --- |
+| `rest-api` | Describes a delivery or interface style; classify the underlying question, such as HTTP contracts or application boundaries. |
+| `web-framework-basics` | Groups by implementation context instead of the engineering concern. |
+| Language buckets such as `go` or `python` | Languages belong at the implementation level. |
+| Framework names such as `express` or `fastapi` | Frameworks are tools used to test a hypothesis, not durable concepts. |
+| Business-domain-only buckets such as `weather` or `content-management` | Domains provide examples but do not define the reusable engineering question. |
+
+## Migration status
+
+Current directory paths remain unchanged for now. This guide defines the target classification model; any directory move requires a separate reviewed change that updates affected links and automation.