Define Markitect resource namespace

docs/markitect-resource-namespace.md

@@ -0,0 +1,76 @@
+# Markitect Resource Namespace
+
+This document defines the Markitect protected-system namespace consumed by
+flex-auth. It is the P3.1 contract between Markitect resource metadata and the
+generic flex-auth registry.
+
+The namespace is intentionally Markitect-specific at the edge and generic once
+registered. Markitect may keep its local frontmatter and backend metadata
+names, but emitted resource manifests should normalize them into the resource
+types and CARING dimensions below.
+
+## Hierarchy
+
+```text
+knowledge_base
+  -> repository
+  -> document
+  -> section
+  -> span
+  -> context_package
+  -> workflow_artifact
+  -> export
+```
+
+Markitect may emit a partial tree. For example, a document can be parented
+directly to a knowledge base when the repository boundary is not material to a
+policy decision. flex-auth treats `parent` as a stable relationship hint; P3.2
+and P3.4 add importer and check fixtures that make inherited behavior explicit.
+
+## CARING Mapping
+
+| Markitect resource type | Parent types | CARING scope | CARING planes | Notes |
+| --- | --- | --- | --- | --- |
+| `knowledge_base` | none | `Workspace` | `Intent`, `Data` | Top-level user-visible knowledge container. |
+| `repository` | `knowledge_base` | `Project` | `Build`, `Data` | Versioned source or storage boundary behind a knowledge base. |
+| `document` | `repository`, `knowledge_base` | `Resource` | `Data` | Renderable document or page. Markitect `path` maps to resource `path`. |
+| `section` | `document` | `Subresource` | `Data` | Stable heading or block region inside a document. |
+| `span` | `section`, `document` | `Field` | `Data` | Fine-grained text range, cell, token span, or field-level surface. |
+| `context_package` | `knowledge_base`, `repository`, `document` | `Dataset` | `Intent`, `Data`, `Policy` | Bundled context prepared for model/tool use. |
+| `workflow_artifact` | `context_package`, `document` | `Process` | `Execution`, `Data`, `Audit` | Generated workflow output, review artifact, or intermediate. |
+| `export` | `workflow_artifact`, `context_package`, `document` | `Record` | `Data`, `Audit` | Materialized package, file, archive, or external transfer. |
+
+## Frontmatter Compatibility
+
+Markitect document frontmatter can remain local, but manifests should preserve
+the following mappings:
+
+- `id` or stable slug -> `resources[].id`
+- document kind -> `resources[].type`
+- source path -> `resources[].path`
+- parent knowledge base, repository, or document -> `resources[].parent`
+- labels, classification, or visibility -> `resources[].labels`
+- tenant/customer boundary -> `resources[].attributes.tenant` when it is not
+  already represented by the request subject/resource tenant
+- owner team or steward -> `resources[].owner`
+- freshness, workflow state, and source revision -> `resources[].attributes`
+
+## Backend Metadata Compatibility
+
+Backend metadata can be richer than the flex-auth contract. The manifest should
+keep durable values in `attributes` and avoid embedding backend-only transient
+state in resource ids.
+
+Recommended backend metadata keys:
+
+- `markitect_path`
+- `frontmatter_visibility`
+- `source_revision`
+- `workflow_state`
+- `freshness_seconds`
+- `data_classes`
+- `tenant`
+
+The examples in `examples/markitect/protected_system_manifest.yaml` and
+`examples/markitect/namespace_resource_manifest.yaml` are the pinned schema
+examples for this namespace.