Files
marqdo-cli/docs/developers

Marqdo developer entry point

Everything a third party needs starts here. The rule behind this page: depend only on the released CLI and public protocols, never on Marqdo's private Rust structures, marqdo-ir internals, inspect --ir, relative paths into the core checkout, or host memory layout. Adding a new domain function must not require a core commit.

Product version for these docs: 3.0.0-beta.1 (Linux x86_64 beta). Protocol versions are independent: Analysis v2, Trace v2, Execution Events v1, Tool v1, Plugin ABI v1, Foreign wire v1, Provider manifest v2, lock v4, markdown profile marqdo.md.v1.

Pick your entry point

Goal Use Deliverable
AI/math/data/quantum/SKILL libraries, pure algorithms .mq.md package index.mq.md, marqdo.yaml, README, tests
Knowledge/Proof/View/IDE/lint/analysis tools CLI Tool Protocol v1 standalone executable + tool.json + Analysis/Trace consumer
High-performance native callable functions Callable Plugin ABI v1 plugin.yaml, host-targeted library, SDK/header
New foreign language backend (R/Python/Julia/…) Foreign Kernel kernel.json, executable provider, pinned environment
Hardware/device/external-stream resources Resource Provider v2 provider.json, C ABI library, worker helper
Change @exec semantics, add keywords/types not a third-party extension core language RFC + migration + full conformance
  1. quickstart.md — install the archive and run the first project.
  2. libraries.md — publish a pure .mq.md library and consume it through a pinned Git dependency.
  3. tools.md — build an external Tool that consumes Analysis v2 and Trace v2.
  4. extensions.md — plugins, foreign kernels, resource providers, extension selection and lock v4.
  5. analysis-trace.md — the public static/dynamic data contracts, Execution Events v1 and digest binding.
  6. compatibility.md — version axes, platform matrix and the prerelease policy.
  7. release-limits.md — the honest beta limitations (this file ships in the archive as KNOWN_LIMITATIONS.md).

The full worked handbook is ../MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md. Normative contracts live in ../../spec/; this directory is a task-oriented map, not a second specification.

Baseline repository

The current implementation and release entry point is git.cflmy.cn/cflmy/marqdo-cli. The earlier cflmy/marqdo repository is a different, incompatible language/product line; it is not a source of current protocol or syntax truth. See the parent repository README for the repository split.

Testing against a frozen binary

Any external repository should be testable without rebuilding the CLI:

export MARQDO_BIN=/absolute/path/to/marqdo
# Put marqdo-provider-worker next to it for provider tests, exactly as the
# release archive does.
$MARQDO_BIN --version

Compute the binary SHA-256 before and after your suite; it must not move. The reference implementation of this gate is marqdo-extension-conformance and tools/ci/verify_extension_contracts.py in the core repository.