// SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) 2026 Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk // SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath) = Marid :toc: :toc-placement: preamble

// ── Licensing ─────────────────────────────────────────────────────────────── image:https://img.shields.io/badge/Code-MPL–2.0-blue.svg?logo=mozilla[Code licence: MPL-2.0,link=“https://opensource.org/licenses/MPL-2.0”] image:https://img.shields.io/badge/Docs-CC–BY–SA–4.0-blue.svg?logo=creativecommons[Docs licence: CC-BY-SA-4.0,link=“https://creativecommons.org/licenses/by-sa/4.0/”]

// ── Standard & quality gates ──────────────────────────────────────────────── image:https://img.shields.io/badge/RSR-Rhodium_Standard-9C27B0[Rhodium Standard Repository,link=“https://github.com/hyperpolymath/rhodium-standard-repositories”] image:https://api.scorecard.dev/projects/github.com/metadatastician/marid/badge[OpenSSF Scorecard,link=“https://scorecard.dev/viewer/?uri=github.com/metadatastician/marid”] image:https://sonarcloud.io/api/project_badges/measure?project=hyperpolymath_marid&metric=alert_status[SonarQube Quality Gate,link=“https://sonarcloud.io/summary/new_code?id=hyperpolymath_marid”] image:https://archive.softwareheritage.org/badge/origin/https://github.com/metadatastician/marid/[Archived in Software Heritage,link=“https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/metadatastician/marid”]

// ── Provenance & ecosystem ──────────────────────────────────────────────────

Julia-first framework for web applications, APIs, and reactive scientific dashboards, with interoperable protocols and frontend independence.

== What this is

Marid is an experimental Julia-first framework with thirteen independently scoped packages, a framework-independent browser client and a relationship explorer. The canonical link:PROJECT_BRIEF.md[project brief] defines acceptance; link:docs/MARID-FRAMEWORK.adoc[the charter] defines build order.

[WARNING]

Prototype implementation exists, but release gates are not accepted. In-memory unit tests do not prove ArangoDB, GraphQL, gRPC or browser interoperability. The previous Gate 5 production-ready claim is superseded by the link:docs/audits/evidence-ledger.adoc[evidence ledger]. See that ledger for the latest local results, explicit unsupported features and external CI blockers. ====

This repository is a Rhodium Standard Repository (RSR) monorepo: the Marid program paths (PROJECT_BRIEF.md, packages/, web/, contracts/, fixtures/, examples/, test/) are carried alongside machine-readable project metadata, an AI-agent gatekeeper protocol, CI/CD, and governance infrastructure.

== Quick start

[source,bash]

git clone https://github.com/metadatastician/marid.git cd marid

Check the repo satisfies the RSR shape:

just validate # structure + metadata checks

Read the contract before anything else:

PROJECT_BRIEF.md # the product/engineering contract (§1–§9)

AGENTS.md # repository instructions for coding agents

# docs/agent-launch.adoc # the Gate 0 kickoff assignment

Julia and Bun local test versions are pinned in mise.toml. Julia packages have independent environments; there is intentionally no root Project.toml. The AffineScript toolchain/build is not yet proven and remains a Gate 0 blocker.

== Local governed HTTP/JSON checkpoint

The link:examples/http_json/README.adoc[unary HTTP example] now binds its actual listener and generated policy to one IR descriptor. It uses HTTP.jl and JSON3; there is no real persistence or application authentication in this demonstration.

The CLI supports explicit legacy globals and opt-in --deny-by-default. Strict mode requires the separately delivered gateway patch, not unmodified upstream. See link:docs/deployment/docker-compose.adoc[reproduction and deployment limits] and the link:docs/audits/evidence-ledger.adoc[ordered evidence ledger]. Full gateway CI and security dependencies remain blockers; no container deployment is claimed.

== AI-Assisted Installation

If you are an AI agent installing this project, read link:docs/AI_INSTALLATION_GUIDE.adoc[the AI installation guide] first — it gives the orientation order, the full prompt sequence, and the privacy notice.

The one trap worth stating up front: do not set RSR_NON_INTERACTIVE=1. It stubs the shell builtin read, which also disables the loops that perform token substitution — the run never terminates and substitutes nothing. Pipe answers to stdin instead.

== What you get

• The Marid program — link:PROJECT_BRIEF.md[brief], thirteen-package prototype (packages/), browser-client skeleton (web/), contract registry (contracts/), fixtures (fixtures/), reference-application skeleton (examples/relationship_explorer/), and interop tests (test/interop/).
• Machine-readable metadata (.machine_readable/descriptiles/) — STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC, NEUROSYM, CLADE, and anchors/ANCHOR, in deed, so tools and agents can read the project’s state and boundaries.
• AI gatekeeper protocol — 0-AI-MANIFEST.deed is the universal entry point that tells an AI agent how to work in this repo before it touches anything, with per-agent instructions in AGENTS.md.
• Typed ABI/FFI seam — src/interface/Abi/ (Idris2 type + layout proofs) over src/interface/ffi/ (Zig implementation), with generated C headers. Retained RSR spine, required by just validate; it is not Marid application code.
• CI/CD — GitHub Actions for quality, security (CodeQL, Scorecard, secret scanning), multi-forge mirroring, and RSR anti-pattern enforcement.
• Supply-chain & reproducibility — container layering (stapeln), Guix shells, SBOM, and signing hooks.
• Governance — GOVERNANCE.adoc, MAINTAINERS.adoc, .github/ community health files, and a release AUDIT.adoc gate.

== Repository map

The authoritative map is generated, so it cannot drift from the tree: link:docs/architecture/REPOSITORY-MAP.adoc[docs/architecture/REPOSITORY-MAP.adoc] (regenerate with just repo-map; CI fails if it is stale).

The short version:

[cols=“1,3”] |=== | Path | What lives there

|===

== Where to go next

• link:PROJECT_BRIEF.md[The project brief] — the canonical contract (§1–§9).
• link:AGENTS.md[AGENTS.md] — repository instructions for coding agents.
• link:docs/agent-launch.adoc[Agent launch prompts] — the Gate 0 kickoff assignment.
• link:docs/marid-architecture.adoc[Marid architecture] — contracts checklist (Gate 0 stub).
• link:docs/marid-compatibility.adoc[Marid compatibility] — version/feature matrices (Gate 0 stub).
• link:docs/marid-roadmap.adoc[Marid roadmap] — the six gates (Gate 0 stub).
• link:docs/audits/README.adoc[docs/audits/] — feasibility evidence (Gate 0 output).
• link:docs/adr/README.adoc[docs/adr/] — Marid architectural decisions.
• link:docs/architecture/REPOSITORY-MAP.adoc[The repository map] — generated; what every directory is for.
• link:docs/EXPLAINME.adoc[EXPLAINME] — the engineering deep-dive: how the pieces actually work.
• link:docs/AFFIRMATION.adoc[AFFIRMATION] — the dated, signed honesty snapshot of the repo’s true state.
• link:docs/AUDIT.adoc[AUDIT] — the release audit gate.
• link:docs/AI_INSTALLATION_GUIDE.adoc[AI installation guide] — for agents instantiating this template.

== Licence

Code, configuration and scripts are link:LICENSE[Mozilla Public License 2.0] (MPL-2.0); prose documentation is CC-BY-SA-4.0. Both texts live in LICENSES/, and per-file SPDX-License-Identifier headers are authoritative. The GitHub-detected licence is MPL-2.0 (the root LICENSE).