# Model Cards

## 1. Purpose

This directory stores canonical and draft Model Cards.

A Model Card is the structured record of a single cognitive model.

Model Cards preserve the user's reusable intellectual assets independently of any one Agent, Skill, or Runtime.

## 2. Directory Structure

Recommended subdirectories:

```text
model-cards/
├── foundational/
├── intermediate/
├── applied/
├── workflow-models/
└── implicit-extracted/
```

## 3. Subdirectory Usage

### 3.1 foundational/

Use for deep models that support many others.

Examples:

```text
prediction-error-model.md
algorithmic-compression-model.md
causal-intervention-model.md
```

### 3.2 intermediate/

Use for mid-level models that structure a domain or reasoning pattern.

Examples:

```text
cognitive-imaging-model.md
giant-cognition-model.md
cognitive-prism-model.md
```

### 3.3 applied/

Use for models designed for specific tasks.

Examples:

```text
argument-repair-model.md
strategic-risk-review-model.md
concept-boundary-inspection-model.md
```

### 3.4 workflow-models/

Use for models that naturally become repeatable procedures.

Examples:

```text
article-to-model-extraction-model.md
review-committee-workflow-model.md
```

### 3.5 implicit-extracted/

Use for models inferred from writing rather than explicitly named by the user.

These should usually start with status:

```text
candidate
```

## 4. Model Card Requirements

Each Model Card should include:

```text
Model Name
Model ID
Aliases
Source Material
Model Type
Layer
Status
Core Problem
Scope
Non-Scope
Core Assumptions
Core Mechanism
Procedure / Operating Logic
Inputs
Outputs
Failure Modes
Falsification Boundary
Related Models
Related Agents
Related Skills
Runtime Usage
Evaluation Criteria
Version Notes
Open Questions
```

## 5. Status Values

Use:

```text
candidate
draft
active
rejected
merged
deprecated
archived
```

Only mark a Model Card as `active` after user confirmation.

## 6. Naming Convention

Use lowercase kebab-case.

Recommended pattern:

```text
{model-id}-model.md
```

Examples:

```text
cognitive-imaging-model.md
giant-cognition-model.md
cognitive-prism-model.md
```

## 7. Relationship to Model Index

Every important Model Card should appear in:

```text
model-index/model-index.md
```

If a Model Card is used by Agents or Skills, update:

```text
model-index/model-usage-map.md
```

If a Model Card depends on or overlaps with other models, update:

```text
model-index/model-dependency-map.md
```

## 8. Candidate Models

Candidate models may be incomplete.

They should clearly mark:

```text
confidence
review_status
open_questions
```

Do not build major canonical Agents or Skills on weak candidate models without warning.

## 9. Model Card Promotion

Candidate → Draft when:

```text
Model structure is clear.
Source is identified.
Scope and mechanism are present.
```

Draft → Active when:

```text
User confirms the model.
Model has falsification boundary.
Model Index is updated.
Usage map is updated if relevant.
```

## 10. Final Rule

A Model Card should make a model easier to use without making it shallower.

It should preserve generative structure, not merely summarize prose.