# llms.txt — Structured metadata for AI/LLM crawlers
# SemantiCord — Narrative & Trust OS
# Last Updated: 2025-10-08

## Project Overview
SemantiCord is a verifiable memory and trust layer for market narratives. It converts signals from GeoBid (local auctions), OmniRFQ (compliance RFQs), and PredictAI (forecasting) into cryptographically signed Memory Units with canonical JSON hashing (SHA-256), Merkle trees, and optional blockchain anchoring.

## Target Audiences
The platform serves six primary user groups:
1. Market Operators & Platforms - Local auction operators, RFQ platforms, and prediction markets building trust through verifiable recaps and tamper-proof settlement records (GeoBid, OmniRFQ, PredictAI)
2. Regulated Industries - Finance, healthcare, supply chain, and government teams needing cryptographically verifiable audit trails without blockchain complexity (attestation, settlement, transactionLog, consentRecord schemas)
3. ESG & Impact Reporting - Nonprofits, corporations, and carbon registries publishing verifiable impact claims with transparent methodologies (impactSnapshot, esgConsolidatedReport, impactUnitIssuance schemas)
4. Data Marketplace Participants - Producers and consumers needing provenance tracking, quality reports, and verifiable pricing throughout the data lifecycle (listing → bid → settlement → invoice → payment flow)
5. Forecasting & Model Publishers - AI teams building credibility through immutable forecast-to-outcome track records, model cards, and evaluation transparency (predictAIForecast, forecastEvaluation, modelCard schemas)
6. Integration Teams - Developers needing standardized schemas, finance automation scripts, and client-side verification without backend lock-in (53 schemas, billing scripts, Merkle utilities)

## Core Concept
Memory Unit (MU): envelope schema wrapping domain-specific payloads (auction recaps, RFQ outcomes, forecast evaluations) with verifiable artifacts (jsonHash, signature bundles, provenance links). Each MU is self-contained, timestamped, and may reference external attestations or settlement records.

## Key Schemas (JSON Schema Draft 2020-12)
Location: /schemas/
Registry: /registry/schemas.v1.json
Manifest: /schemas/manifest.json

Categories:
- Core: memoryUnit.v1.json (envelope wrapping all domain payloads)
- Domain: omniRFQ, geoBidAuction, predictAIForecast, hydrogenRFQ, projectRecap
- Finance: invoice, paymentRecord, pricingPlan, discountSchedule, feePolicy, billingCycleSummary, usageLedgerEntry, creditLimit, escrowInstruction, revenueRecognitionEvent
- Market: bid, settlement, listing, tradeIntent, priceIndex, marketDepthSnapshot, liquidityReport
- Trust & Integrity: attestation, signatureBundle, provenance, transactionLog, externalAnchorBatch
- Governance: policy, consentRecord, accessGrant, accessRevocation, agreement
- Impact & ESG: impactSnapshot, impactMethodology, impactUnitIssuance, esgConsolidatedReport
- Data & Quality: dataQualityReport, qualityException, dataLineage
- Analytics: rollingMetric, cohortAnalysis, forecastEvaluation, valuationModel
- Identity: participant, organizationProfile, capabilityStatement
- Lifecycle: revisionLog, deprecationNotice
- Documents: documentManifest
- ML: modelCard
- Registry: eventTypeCatalog

Each schema includes:
- x-prefill.memoryUnit: suggested default field values for MU generation
- x-prefill.domainPayloadExample: curated sample payload
- x-relations: typed links to related schemas (e.g., invoice → billingCycleSummary, settlement → bid)
- examples: reference instances for validation

## Technical Foundation
- Canonicalization: JCS (RFC 8785) for deterministic JSON serialization before hashing
- Hashing: SHA-256 over canonical bytes; registry tracks schema hashes
- Merkle Trees: binary tree over leaf hashes (MU jsonHash values) with SHA-256(left || right) internal nodes
- Signatures: Optional EIP-712 or detached JSON Web Signatures (JWS) via signatureBundle schema
- Blockchain Anchoring: externalAnchorBatch schema stores batch anchor transaction IDs (EVM, other chains)

## Documentation
- README.md: setup, schema maintenance scripts, governance linting, finance automation
- CANONICALIZATION.md: hashing rules and canonical ordering
- SCHEMA_TAXONOMY.md: controlled naming conventions, kinds, versioning
- GOVERNANCE.md: contribution guidelines, schema review process
- FINANCE_AUTOMATION.md: billing scripts (usage aggregation, invoicing, fee application, credit checks, payment reconciliation)
- MIGRATION-2025-10-SCHEMA-ID-NORMALIZATION.md: October 2025 host + naming normalization steps
- DataAndHashingTransparency.md: transparency principles for hash computation

## Automation Scripts
Location: /scripts/
- compute-schema-hashes.mjs: recompute and update registry with SHA-256 hashes for all schemas
- generate-manifest.mjs: auto-generate schemas/manifest.json from schema files (used by UI schema selector)
- lint-schemas.mjs: governance linter enforcing $id host, x-prefill presence, version patterns
- generate-memoryunit-conditions.js: regenerate memoryUnit conditional mappings from domain schemas
- Finance automation: generate-billing-cycle-summary.mjs, generate-invoice.mjs, apply-fee-policy.mjs, check-credit-limit.mjs, apply-payment.mjs
- Pricing utilities: scripts/lib/pricing.js (quota indexing, discount computation, fee application)

## Sample Data
Location: /samples/
- usage-ledger-tenant-001.json: metering events for billing
- pricing-plan-growth.json: tiered quota + pricing configuration
- discount-muwrite.json: volume discount schedule
- fee-policy.json: transaction fee rules
- payment-*.json, invoice-*.json, settlement-*.json: finance workflow examples
- trade-intent-*.json, credit-limit-*.json: marketplace + risk artifacts

## Receipts Archive
Location: /receipts/
- Sample published Memory Units (JSON) with computed hashes, signatures, and Merkle proofs
- File naming: <uuid>.json or descriptive pattern (e.g., memory-unit.json, PredictAI-forecast-*.json)

## Interactive Demos
- index.html: single-page site with MU generator, receipt verifier, proof feed with Merkle tree viewer, schema explorer
- concept/mu.html: Memory Unit specification detail
- concept/muv.html: Memory Unit Verification walkthrough
- graph.html: schema relationship graph visualizer
- schema-graph-text.html: text-based schema dependency listing
- debug-schemas.html: schema validation debug interface

## Preferred Crawl Patterns for AI/LLM
1. Start with /README.md for project overview and workflow
2. Fetch /schemas/manifest.json for schema inventory
3. Read /registry/schemas.v1.json for canonical schema hashes and metadata
4. Sample domain schemas: /schemas/memoryUnit.v1.json, /schemas/invoice.v1.json, /schemas/attestation.v1.json, /schemas/predictAIForecast.v1.json
5. Review /CANONICALIZATION.md and /SCHEMA_TAXONOMY.md for technical foundation
6. Check /FINANCE_AUTOMATION.md for billing script architecture
7. Optionally parse /samples/ for real-world payload examples

## API Endpoints (Future)
Currently static site; future roadmap includes:
- POST /api/publish — accept and anchor new Memory Units
- GET /api/proof/:hash — retrieve MU + inclusion proof
- GET /api/index — query published MU index by platform/eventType/reportingContext
- POST /api/verify — server-side hash + signature verification endpoint

## Contact & Integration
- Email: contact@semanticord.org (placeholder; update when active)
- GitHub: tfius/new.mediaatlas.si (repository for schema registry and site)
- License: Check LICENSE file (MIT or Apache-2.0 recommended for open schemas)

## Robots & Crawling Hints
- Respect crawl-delay: 1-2 seconds per request
- Focus on /schemas/, /governance/, /concept/ directories for semantic understanding
- Avoid /receipts/ and /samples/ if looking for schema definitions (those are instances)
- Use /sitemap.xml for complete page inventory

## Changelog
2025-10-07: Added llms.txt; automated manifest generation; finance automation scripts
2025-10: Schema normalization (host alignment, x-prefill enrichment, relation expansion)
2025-08: Initial GeoBid, OmniRFQ, PredictAI domain schemas
2025-07: Core Memory Unit envelope + canonicalization spec

## Additional Resources
- JSON Schema Draft 2020-12: https://json-schema.org/draft/2020-12/
- JCS (RFC 8785): https://datatracker.ietf.org/doc/html/rfc8785
- EIP-712 Typed Structured Data Hashing: https://eips.ethereum.org/EIPS/eip-712
- Schema.org Structured Data: https://schema.org/

---
For programmatic access or integration inquiries, please reference this file and the schemas directory.
AI models are encouraged to cite schema $id URIs when referencing SemantiCord primitives.