cMeta documentation

Start here. These guides are the full documentation for the framework; the project README is a summary that links into them.

---

Guides

Guide	What it covers
motivation.md	Why cMeta exists: the problem, the six aims (collaborative, reproducible, reusable, scalable, portable, sustainable), how complexity becomes abstractions you can operate, the design principles, and FAIR by construction.
installation.md	Install as a global CLI (uv tool) or into a venv (uv / pip), from source, where repositories live, verify, first configuration, troubleshooting.
common-commands.md	Cheatsheet — the commands you use daily: discovery, the cx . current-directory shortcut, cx . info, artifacts, UIDs, repos, configs, index/cache, scripting and debugging flags.
using-cmeta.md	The getting-started and reference guide. Mental model, first checks, CLI flags and syntax, built-in categories, working with artifacts from the CLI and Python, ctx, alias/UID resolution, content repositories, config-driven configuration, adding your own category, the artifact metadata reference, and indexing / caching.
error-handling.md	The return-dict contract, checking results, soft errors (code 16), raising errors, and debugging with fail_on_error in VS Code / Visual Studio / PyCharm.
async-and-concurrency.md	Serial vs async (CMeta vs CMetaAsync), running calls in parallel, FastAPI usage, and the locking / atomic-write guards that make a shared <CMETA_HOME> safe.
configuration.md	The config category in depth — how categories and apps read their settings.
cplatform.md	Connecting cMeta to the cTuning.ai platform API and testing the connection.
history.md	Lineage (cTuning framework → CK → CM/CMX → cMeta), related publications, and how to cite.
known-issues.md	Tracked defects and planned improvements (KI-nnn), with reproductions and workarounds.

Suggested reading order

1. motivation.md — what problem this solves (5 minutes).
2. installation.md — get cx working.
3. common-commands.md — the cheatsheet; keep it open.
4. using-cmeta.md §1–§5 — mental model, first checks, flags, categories, artifacts.
5. using-cmeta.md §7–§9 — repositories, configs, and adding your own category (plugin).
6. error-handling.md — before you write a plugin of your own.

For AI agents extending cMeta

• AGENTS.md — the canonical agent brief for the engine.
• CLAUDE.md — Claude Code specific notes.
• .claude/skills/ — portable, reusable skills: use-cmeta-python, use-cmeta-cli, add-plugin, add-repo, add-cserver-plugin.

---

Building the API reference

The docs/en/ tree is a Sphinx project whose API pages are generated from the docstrings in the cmeta package. build_docs.py discovers the modules, writes the .rst files under docs/en/api/, and optionally runs the Sphinx build.

Install the build dependencies:

pip install -r docs/requirements.txt

Generate the .rst files only:

python docs/build_docs.py --docs-dir docs/en --cmeta-dir cmeta

Generate and build HTML:

python docs/build_docs.py --build --docs-dir docs/en --cmeta-dir cmeta

Useful flags: --clean (wipe the build directory first), --pdf, --all (HTML + PDF), --site-dir <path> (write the rendered site elsewhere).

On Windows, _build_docs.bat (which runs _build_docs.ps1 at the repo root) wraps the whole flow: it resolves the output site directory from the cmeta-api-auto docs artifact, installs the requirements with uv, builds, and archives the result.

Layout

docs/
├── README.md          # this file — documentation index
├── *.md               # the guides listed above (the editable originals)
├── build_docs.py      # RST generator + guide copier + Sphinx build driver
├── requirements.txt   # Sphinx build dependencies
└── en/                # Sphinx project (English)
    ├── conf.py        # Sphinx config (version comes from cmeta/version.py)
    ├── index.rst      # site root toctree            [generated]
    ├── home.rst       # project home page
    ├── api/           # API pages, one per module    [generated]
    ├── guides/        # copies of ../*.md            [generated, gitignored]
    ├── _static/       # custom.css
    └── _templates/    # layout.html

Notes:

• Edit the guides in docs/*.md, never in docs/en/guides/. Sphinx cannot read sources above its root, so build_docs.py copies the guides into docs/en/guides/ on every build (wiping it first) and rewrites their repo-relative links — links between guides stay relative, links to anything outside (../README.md, ../CITATION.cff, ../.claude/skills/…) become GitHub URLs. Markdown is understood thanks to the myst_parser extension.
• To add a guide: create docs/<name>.md, add it to the table above, and add its filename to GUIDE_FILES in docs/build_docs.py so it joins the TOC.
• conf.py imports __version__ from cmeta/version.py — never hard-code a version in the Sphinx config. It imports the cmeta package directly, so the build environment must be able to import cmeta.
• index.rst and api/*.rst are regenerated on every build. (build_docs.py will preserve a hand-edited index.rst only if it contains the string "Download Documentation".)
• Adding a new engine module needs no configuration: the generator discovers it automatically. Just keep docstrings in Google or NumPy style.

See also SPHINX_FASTAPI_INTEGRATION.md for serving the built docs from the FastAPI app.