Skip to main content

​
Kokonut Intelligence turns governed records into usable intelligence.

Kokonut farms generate operational, financial, ecological, governance, sensor, geospatial, and partner data. Kokonut Intelligence is the open-source platform that structures those records, applies permissions and review workflows, computes analytics, supports evidence and reporting, and exposes controlled interfaces for humans, applications, and agents. It is not one universal truth engine. It is a governed implementation layer where data can move from source activity to reviewable records, published views, analysis, and optional public provenance without collapsing those stages together.

Understand the architecture

See the canonical database, APIs, analytics, workflows, field tools, verification, and contract layers.

Follow the record lifecycle

Understand how drafts become reviewed and published records without treating workflow status as scientific certification.

Build on the platform

Choose Directus, the gateway, gRPC, analytics, Field Collector, agents, or smart contracts based on the job.

Open the current repository

Verify live architecture, commands, deployments, schemas, and implementation details at their canonical source.
Current source of truth: implementation details for Kokonut Intelligence live in the active repository at git.kokonut.network/Kokonut-Intelligence. This Knowledge Base explains the public architecture and builder contract; volatile versions, addresses, schema UIDs, test counts, and command details should be verified in the repository that owns them.

​
What Kokonut Intelligence is — and is not

The platform governs records. It does not erase the distinction between data, evidence, interpretation, and decision.

​
Why this layer exists

Without a governed implementation layer, farm information fragments across:
  • field notebooks;
  • spreadsheets;
  • sensors;
  • mobile devices;
  • photos;
  • satellite and drone workflows;
  • invoices;
  • wallets;
  • governance systems;
  • dashboards;
  • reports;
  • partner files;
  • AI-generated drafts.
Kokonut Intelligence creates a shared operating environment where those inputs can become structured and reviewable without requiring every source to become public or on-chain. The durable principle is:
source → structure → review → publish → attest when useful → interpret
Not every record needs every step.

​
Architecture at a glance

The current platform is broader than a database plus dashboard.
The exact software versions and deployment inventory evolve. Builders should use the current repository README, architecture document, deployment records, and contract broadcast artifacts for implementation-specific values.

​
Responsibility map

​
The canonical core

For builder purposes, the most important architectural rule is:
PostgreSQL + Directus are the canonical schema/API layer.
This means:
  • core records should not be reconstructed independently inside every dashboard;
  • external applications should not invent incompatible versions of canonical farm records;
  • analytical stores should not silently become the authority for governed record state;
  • agent-generated summaries should reference governed data rather than replacing it;
  • public reports should be reproducible from reviewed source records where practical.

​
Schema ownership

The current repository version-controls:
  • PostgreSQL migrations;
  • Directus snapshots;
  • ClickHouse schemas;
  • seed data;
  • metric definitions;
  • governance configuration;
  • attestation configuration;
  • contract deployment artifacts.
Builders changing a shared data contract should update the owning schema and its documentation together.

​
Governed record lifecycle

Governed records generally follow:
draft → submitted → verified → published
rejected supports rework and exception paths. Domain-specific state should remain separate. Examples include:
  • payment status;
  • attestation status;
  • execution status;
  • revocation;
  • order fulfillment;
  • metric verification;
  • certification readiness;
  • contract upgrade state.
verified is a workflow state, not a universal truth label. It means the relevant authorized review step passed for that record class. It does not automatically mean scientifically validated, externally audited, legally approved, certified, or regulator-endorsed.

​
Human review remains part of the system

The current platform deliberately keeps sensitive transitions human-controlled. For example:
  • governed metrics can be computed as draft/unverified values before a human reviewer accepts them;
  • agents can draft and submit but cannot verify or publish;
  • strategy and decision systems can generate recommendations without automatically executing them;
  • critical actuation and upgrade paths use approval/timelock controls.
This is an architectural safety property, not an inconvenience to automate away.

​
Evidence maturity

Kokonut Intelligence distinguishes record workflow from evidence strength. A useful public claim should not become stronger merely because it passed JSON validation or was written to a blockchain. The platform uses an evidence-maturity model that progresses from narrative/self-reported material toward structured, reviewed, evidence-linked, attested, and externally verified records. Conceptually:
Public carbon claims are held to a higher evidence threshold in the current implementation. Builders should not infer verified climate outcomes from trees, biochar, vegetation indices, model output, or an EAS attestation alone.

​
Evidence quality and record status are different axes

A record can be:
  • published but limited in evidentiary strength;
  • internally verified but not externally verified;
  • evidence-linked but still uncertain;
  • attested but later revoked or superseded;
  • scientifically strong but intentionally private.
That distinction should remain visible in APIs, dashboards, reports, and agent outputs.

​
MRV relationship

The MRV methodology defines how observations become evidence. Kokonut Intelligence implements the infrastructure needed to operationalize that methodology. The platform can support:
  • ground observations;
  • soil and water sampling;
  • remote sensing;
  • drone imagery;
  • vegetation indices;
  • IoT streams;
  • harvest records;
  • biodiversity observations;
  • evidence hashes and CIDs;
  • reviewer metadata;
  • attestation records;
  • reporting snapshots.
It should not be described as requiring one fixed IPFS → EAS path for every observation.

​
Field Collector

Kokonut Intelligence includes an offline-first Field Collector for farm data capture. Its purpose is to let field teams collect structured records even when connectivity is unreliable. The current platform exposes the collector through the local/mobile stack and supports a policy-aware gateway for synchronization. Useful field workflows include:
  • farm activities;
  • harvests;
  • expenses;
  • field notes;
  • soil and water observations;
  • GPS and media evidence;
  • later synchronization into governed records.

Why offline-first matters

Farm-data infrastructure should fit real operating conditions. Connectivity failures should delay synchronization, not force field teams back into unstructured side channels.
Builder rule:
Offline creation must not bypass review.
A locally captured record still enters the governed lifecycle after synchronization.

​
API and integration surfaces

Kokonut Intelligence exposes several interfaces because not every consumer has the same needs.

​
Authentication boundaries matter

Different API layers can have different authentication models. A Directus bearer token should not automatically be assumed valid for:
  • gateway routes;
  • device synchronization;
  • gRPC;
  • agent capability access;
  • smart-contract execution.
Builders should use the owning interface’s documented authentication model rather than creating a universal super-token.

​
Analytics and decision support

The platform now supports a wide range of analytical methods, including:
  • versioned metrics;
  • forecast-vs-actual analysis;
  • financial and operational reporting;
  • ecological analytics;
  • geostatistics;
  • time-series trends;
  • anomaly detection;
  • scenario analysis;
  • process mining;
  • process costing;
  • systems-thinking models;
  • stock-and-flow simulation;
  • strategy and portfolio analysis;
  • OODA-style decision workflows;
  • risk and readiness models.
This breadth creates an important builder responsibility:
A computed output must retain its method, inputs, scope, and limitations.

​
Scores are methods, not truth

Kokonut Intelligence contains multiple scoring and readiness models. Those can support a particular decision context. They should not be collapsed into one universal farm-quality or impact ranking.

​
Systems and organizational intelligence

The current platform extends beyond farm accounting into systems and organizational analysis. Implemented areas include:
  • causal-loop analysis;
  • leverage-point identification;
  • system archetypes;
  • double-loop learning;
  • stock-and-flow simulation;
  • process intelligence;
  • organizational work items and escalation;
  • objectives and portfolio management;
  • budgeting and S&OP;
  • capability and strategy maps;
  • threatcasting and backcasting;
  • stakeholder and consent systems;
  • governance circles and roles.
These tools should be understood as decision-support structures. They do not replace:
  • farm operators;
  • governance votes;
  • legal authority;
  • scientific review;
  • partner due diligence;
  • human judgment.

​
Agents and AI

Kokonut Intelligence includes an internal agent ecosystem with:
  • agent identities;
  • capability manifests;
  • tasks;
  • action logs;
  • AI summaries;
  • scoped Directus/MCP access;
  • shared agent scaffolding;
  • bounded data access.
The critical permission boundary is:
Agents can draft and submit. They cannot verify, publish, attest, or score governed records on their own.

​
Internal agents vs. Agentic Marketplace

Kokonut has two related but separate surfaces: Marketplace identity, payment, escrow, and reputation logic should not be silently reimplemented inside Kokonut Intelligence. Read Kokonut × AI Agents →

​
Smart contracts and chain roles

Kokonut Intelligence now includes an active smart-contract layer rather than only off-chain schemas and attestations.

​
Gnosis

The current repository documents deployed Gnosis contracts for areas including:
  • Guild registry and domains;
  • task coordination;
  • evidence review;
  • Guild governance;
  • Guild Points / KGP;
  • upgrade timelocks;
  • credit-token infrastructure;
  • price oracle;
  • selective disclosure.
Some contracts use upgradeable proxy patterns with timelock controls.

​
Celo

Celo remains the primary attestation chain for Kokonut evidence through EAS. The repository contains registered schemas for several claim classes and maintains the technical attestation configuration.
Deployment addresses, schema UIDs, contract counts, and current verification status are volatile implementation facts. Builders should verify them in the current repository deployment/attestation documentation and chain explorers instead of relying on copied values from this page.

​
Different chains, different authority

Being connected across chains does not make these roles interchangeable.

​
SAFE execution boundary

Kokonut’s execution architecture also separates proposal from authorization. Where SAFE workflows are used, automation can prepare or propose a transaction while human owners retain execution authority. Builder principle:
A service that can propose a treasury action should not be documented as if it can independently move funds.
This same distinction should appear in:
  • agent capabilities;
  • API permissions;
  • governance dashboards;
  • transaction-status labels;
  • audit logs.
Open-source infrastructure does not mean all farm evidence should be public. The current architecture supports:
  • role- and row-scoped access;
  • field-level restrictions;
  • audit logs;
  • consent management;
  • partner-specific views;
  • private stakeholder evidence;
  • off-chain evidence;
  • hashes and CIDs;
  • selective-disclosure contracts;
  • public-safe summaries.
Raw stakeholder feedback, sensitive farm evidence, credentials, personally identifying records, exact locations, or private partner material should not be exposed simply because a public dashboard or attestation exists.
A public attestation can prove that a claim or evidence relationship was anchored without revealing the entire private payload.

​
Platform integrity

Kokonut Intelligence increasingly treats the platform itself as governed infrastructure. Current integrity patterns include:
  • ordered/checksummed schema migrations;
  • pinned container images;
  • policy-aware gateway routes;
  • lifecycle audit history;
  • scoped agent access;
  • durable scheduler/worker patterns;
  • event/outbox handling;
  • human approval gates;
  • contract upgrade timelocks;
  • CI across Python, Directus extensions, and Solidity.
For builders, that means infrastructure shortcuts can be compatibility changes even when the public API looks unchanged.

​
Builder entry points

Data model & workflows

Work in PostgreSQL migrations, Directus snapshots, permissions, hooks, lifecycle rules, and public-safe views.

Field tools

Improve offline collection, mobile synchronization, device auth, GPS/media capture, and field UX.

Analytics

Add or improve metrics, forecasts, geostatistics, process intelligence, systems analysis, or forecast reconciliation.

Evidence & MRV

Improve evidence lineage, maturity, QA, sampling context, attestation preparation, or reviewer workflows.

APIs

Build through Directus, gateway REST, gRPC/Protobuf, or approved SDK surfaces without bypassing permissions.

Agents

Build bounded draft/analysis workflows with explicit inputs, outputs, permissions, review rules, and audit logs.

Smart contracts

Work on Guild, evidence-review, credit, oracle, privacy, or upgrade infrastructure with the repository’s Foundry tests and deployment controls.

Reporting

Improve report generation, public-interest summaries, uncertainty notes, evidence gaps, and partner-specific outputs.

​
Developer quickstart

Use the live repository’s README and AGENTS.md as the command source. The current high-level local flow is:
Metric computation should not be documented as automatic verification. The current workflow separates computed draft values from later reviewer verification.

​
Current local surfaces

The base stack includes interfaces such as:
  • Caddy/TLS entrypoint;
  • Directus API and admin;
  • Field Collector;
  • FastAPI gateway;
  • Metabase;
  • gRPC;
  • MQTT;
  • PostgreSQL;
  • ClickHouse;
  • Redis;
  • worker/orchestration services.
Exact ports and exposure differ between base, local override, sandbox, and production configurations. Use the repository deployment docs rather than assuming every internal database or analytical service is exposed on the host.

​
Builder quality rules

Before changing Kokonut Intelligence or building on it, confirm:
  • The canonical record owner is clear.
  • Draft, submitted, verified, and published states remain distinct.
  • Domain-specific lifecycle states are not overloaded into the canonical status field.
  • Computed metrics are not silently treated as human-verified values.
  • Evidence maturity is not inferred from database completeness alone.
  • Attestation is treated as provenance, not automatic scientific truth.
  • Private evidence remains private unless publication is explicitly authorized.
  • Agents cannot self-verify, self-publish, self-attest, or silently execute privileged actions.
  • Forecasts remain distinguishable from actuals.
  • Model/score definitions are versioned and reviewable.
  • API authentication follows the specific interface being used.
  • Offline/mobile sync does not bypass review.
  • Contract upgrades and treasury actions preserve human/timelock authority.
  • Shared schema/API changes include compatibility and migration planning.
  • Public documentation changes when the public contract changes.

​
Current maturity

​
Repository documentation map

The active repository contains deeper technical material for:

Open the live repository

Use the current OneDev repository for implementation details rather than the older GitHub mirror.

​
Continue through the builder system

Build with Kokonut

Return to the ecosystem-wide builder contract, canonical-source rules, maturity states, and contribution workflow.

MRV Methodology

See the evidence lifecycle that Kokonut Intelligence operationalizes.

Common Data Schema

Understand the 13-field baseline compatibility contract and its boundaries.

Kokonut × AI Agents

Explore the agent architecture while preserving review, authority, and evidence boundaries.

Ecological Impact Frameworks

See how EBF and CRISP interpret evidence without becoming automatic certification.

Framework Introduction

Reconnect the implementation layer to Framework methodology, local authority, and interoperability.
Kokonut Intelligence is most useful when it makes the path from source record to decision inspectable — without pretending that storage, scoring, automation, or blockchain provenance can replace evidence and judgment.