MD-OS is an early reference implementation of a Markdown-native Operating
Filesystem. Its central discipline is not simply that files exist under
md-os/ops/, but that every operational file has a clear lifecycle role.
The release workspace may start with a sparse md-os/ops/ tree. Canonical runtime
files are generated by initialization and build scripts. The critical
requirement is therefore lifecycle clarity: source, generated, local, demo,
live, and archived state must not be confused.
The formal path table is maintained in:
docs/FILESYSTEM_CONTRACT.md
The epistemic role of theory, research, and calculation artifacts is governed by:
md-os/kb/EPISTEMIC_LIFECYCLE_MODEL.md
Runtime lifecycle answers what kind of file an artifact is. Epistemic lifecycle answers what kind of claim the artifact makes: heuristic, line of thought, frozen principle, derivation, prediction/readback, or correction. Both classifications are required before a theory-oriented result is promoted into a strong claim.
Portable MD-OS state should not depend on the absolute directory where the
workspace was checked out, copied, or scaffolded. Source, generated, demo, live,
and archived state should store repository-relative paths such as
md-os/ops/global_index.md whenever the referenced file is inside the workspace.
Runtime code resolves the active workspace at startup. Explicit environment
overrides (MDOS_WORKSPACE_ROOT and MDOS_ROOT) take precedence. If
they are not set, the runtime searches upward from the current working
directory for an MD-OS workspace and then falls back to the package location.
Absolute paths are allowed only when they describe the host itself or an external host configuration:
md-os/ops/local/**
external MCP host cwd/script configuration
transient terminal, hardware, software, or desktop observations
Those paths are host-local, cleanable, and not publishable source of truth. After moving a workspace, rebuild generated state and refresh host-local discovery instead of editing absolute paths into canonical files.
Files that should be treated as canonical inputs:
AGENTS.md
ME.md
README.md
docs/**/*.md
docs/**/*.svg
docs/**/*.png
docs/papers/zenodo/paper.tex
md-os/kb/**
md-os/kb/imports/*/{README,SOURCE_MANIFEST,KNOWLEDGE_NODES,RELATIONS,IDENTITY_FRAME,OPERATING_BINDING}.md
md-os/kb/imports/*/canonical_import.json
md-os/examples/**
md-os/ops/projects/*/project.json
md-os/ops/programs/*.md
md-os/ops/calculations/wolfram/*.json
md-os/ops/calculations/wolfram/scripts/*.wl
md-os/ops/imports/knowledge/*/manifest.json
md-os/ops/imports/knowledge/*/raw/**
md-os/ops/roles/*/ROLE.md
md-os/ops/roles/*/intake/raw/**
md-os/ops/sources/**
md-os/ops/connectors/connector_registry.json
md-os/ops/connectors/*.json
md-os/ops/policies/*.json
md-os/ops/evals/**
md-os/ops/actions/**
md-os/ops/processes/**
md-os/ops/releases/self/proposals/*.json
md-os/ops/episodes/*.{json,md}
md-os/ops/experiments/contextual_feeling/*/report.{json,md}
md-os/ops/experiments/reflective/*/report.{json,md}
md-os/ops/apfc/cognitive/self_reflection/{prepared,episodes}/*.json
md-os/ops/apfc/cognitive/phenomenal_candidate/{prepared,episodes}/*.json
md-os/ops/tasks/*.json
md-os/ops/action_receipts/*.json
md-os/ops/verifications/*.json
md-os/ops/trajectories/*.json
md-os/ops/skills/candidates/*.{json,md}
md-os/ops/skills/promoted/*.{json,md}
These files define identity, knowledge, project definitions, official presentation material, natural-language programs, calculation profiles, source observations, connector availability, operational application state, and proposed self-release state.
Files produced by deterministic builders from source inputs:
md-os/ops/compiled/**
md-os/ops/projects/*/status.md
md-os/ops/projects/*/agenda.md
md-os/ops/projects/*/work_items.ndjson
md-os/ops/agenda/global_agenda.*
md-os/ops/summary/active_work_items.*
md-os/ops/archive/**
md-os/ops/core/agentic_core.*
md-os/ops/global_index.*
md-os/ops/imports/knowledge/*/{inventory,classification,relations,identity_patch,promotion_plan,questions,readback}.*
md-os/ops/imports/knowledge/*/extracted/**
md-os/ops/markdown_graph.*
md-os/ops/semantic_knowledge_graph.*
md-os/ops/semantic_knowledge_summary.*
md-os/ops/semantic/commitment_gate_status.*
md-os/ops/releases/self_release_index.*
md-os/ops/agi/{loop_status,promotion_gate}.*
md-os/ops/agi/neuromorphic_learning_status.*
md-os/ops/agi/apfc_causal_learning_status.*
md-os/ops/skills/skill_registry.*
md-os/ops/evals/agi_eval_report.*
md-os/ops/failures/failure_index.*
md-os/ops/world/world_model.*
md-os/ops/benchmarks/agi_benchmarks.*
md-os/ops/benchmarks/software_repair/index.*
md-os/ops/runtime/**
md-os/ops/workspace_inventory.*
md-os/ops/system_hygiene_status.*
md-os/ops/replay_report.*
graphify-out/**
md-os/ops/roles/*/intake/inventory.*
md-os/ops/roles/*/intake/entities.json
md-os/ops/roles/*/intake/task_map.md
md-os/ops/roles/*/intake/questions_for_expert.md
md-os/ops/roles/*/intake/candidate_operations.md
md-os/ops/roles/*/cases/cases.*
md-os/ops/roles/*/graph/relation_graph.*
md-os/ops/roles/*/analysis/sensemaking.json
md-os/ops/roles/*/analysis/role_understanding.md
md-os/ops/roles/*/analysis/root_cause_candidates.md
md-os/ops/roles/*/analysis/work_patterns.md
md-os/ops/roles/*/analysis/questions_for_expert.md
docs/papers/zenodo/paper.pdf
Generated state should be reproducible. Builders may rewrite their known outputs. The paper PDF is a generated publication artifact, but the paper itself is not separate from the system: its source is official presentation material and must be updated with architectural changes.
Graphify visualization and orientation files under graphify-out/ are derived
readback, not canonical knowledge nodes. The Markdown and semantic graph
builders therefore exclude them from source-node coverage; Graphify can rebuild
them from the operating filesystem. Its graphify-out/cache/** subtree is a
separate host-local cache and may be deleted without deleting source knowledge.
Software-repair benchmark cases, fixtures, candidate fixtures, provider
descriptors and programs, and independent oracles under
md-os/benchmarks/software_repair/ are repository source. Candidate sets,
CandidateProvider requests/results/receipts, PlanGraphs, and completed run evidence under
md-os/ops/benchmarks/software_repair/ are live, append-only experimental
state. The benchmark index is generated and rebuildable. Temporary worktrees
under .sandbox/ are local and must not survive a completed run.
Files that describe the current host or current local runtime:
md-os/ops/state.json
md-os/ops/current_task.md
md-os/ops/continuity.md
md-os/ops/last_summary.md
md-os/ops/services/**
md-os/ops/local/**
graphify-out/cache/**
Local runtime state may be useful for continuity but should be reviewed before publication. Host-local discovery caches are cleanable and remain outside the publishable source boundary unless deliberately promoted through review.
Files used to seed examples and documentation:
md-os/examples/projects/**
md-os/examples/sources/**
md-os/examples/programs/**
md-os/examples/connectors/**
Demo state demonstrates the model. It should not be confused with live agent state.
Files produced during a real operating session:
md-os/ops/journal.ndjson
md-os/ops/changes/**
md-os/ops/artifacts/**
md-os/ops/calculations/wolfram/**
md-os/ops/imports/knowledge/**
md-os/ops/sources/**
md-os/ops/projects/**
md-os/ops/roles/**
md-os/ops/processes/**
md-os/ops/evals/**
md-os/ops/episodes/**
md-os/ops/experiments/contextual_feeling/**
md-os/ops/experiments/reflective/**
md-os/ops/apfc/cognitive/self_reflection/**
md-os/ops/apfc/cognitive/phenomenal_candidate/**
md-os/ops/tasks/**
md-os/ops/action_receipts/**
md-os/ops/verifications/**
md-os/ops/trajectories/**
md-os/ops/semantic/commitment_decisions/**
md-os/ops/skills/candidates/**
md-os/ops/skills/promoted/**
md-os/ops/skills/history/**
md-os/ops/agi/generality_experiments/**
md-os/ops/agi/learning_experiments/**
md-os/ops/agi/capability_experiments/**
Live state should preserve auditability and replay. Ambiguous or contested edits should be registered as append-only change proposals.
Files that preserve inactive or terminal views without deleting canonical state:
md-os/ops/archive/**
md-os/ops/summary/**
Archive and summary views are materialized views. They reduce active reading load while preserving canonical sources and rebuild paths.
Every new operational file should answer:
Is this file source or generated?
Is this file local or publishable?
Is this file demo state or live state?
Is this file rebuildable?
Which builder owns it?
Which connector or host may write it?
Which schema or contract validates it?
If those answers are unclear, the file weakens the Operating Filesystem model.
Initialization and build scripts may create the canonical runtime files:
md-os/ops/continuity.md
md-os/ops/state.json
md-os/ops/last_summary.md
md-os/ops/current_task.md
md-os/ops/journal.ndjson
md-os/ops/connectors/connector_registry.json
md-os/ops/agenda/global_agenda.*
md-os/ops/core/agentic_core.*
md-os/ops/global_index.*
md-os/ops/markdown_graph.*
md-os/ops/semantic_knowledge_graph.*
md-os/ops/semantic_knowledge_summary.*
md-os/ops/semantic/commitment_gate_status.*
md-os/ops/releases/self_release_index.*
md-os/ops/runtime/**
md-os/ops/system_hygiene_status.*
md-os/ops/replay_report.*
Their absence in a sparse release workspace should not be described as a missing architecture. The sharper issue is whether the lifecycle and ownership of each generated or local file is explicit.
MD-OS is not yet a mature Operating Filesystem. It is a working reference implementation whose next maturity step is to make lifecycle, schema, permission, replay, and connector ownership mechanically enforceable.