# 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.