From a4ed684c518ec7566e5f0295c23793eeb0f8e3dc Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:07:48 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 472 ---------------------------------------------------- README.md | 469 ++++++++++++++++++++++++++++----------------------- 2 files changed, 263 insertions(+), 678 deletions(-) delete mode 100644 README.adoc diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 5b2a1c3..0000000 --- a/README.adoc +++ /dev/null @@ -1,472 +0,0 @@ -= Binary-Origami Figurator -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2025 hyperpolymath - - -> Infrastructure for pragmatic epistemology. Combining - -- i-docs navigation, -- PROMPT epistemological scoring, and -- boundary objects theory. - -An evidence graph for investigative journalism. - -*Status:* Phase 1 (PoC) - v1.0.0 Release -*Version:* 1.0.0 - -== New Here? Start with the Wiki - -[TIP] -==== -*Confused by the terminology?* The link:wiki/index.adoc[Binary-Origami Wiki] explains everything in metaphors, diagrams, and plain language. -==== - -[quote] -____ -This isn't just a database. It's *infrastructure for folding and unfolding evidence*—so everyone can see the shape that fits their needs. -____ - -=== Why "Binary-Origami"? - -* *Binary*: Evidence is stored as clear, connected data (supports/contradicts, 0-100 scores) -* *Origami*: The same evidence can be "folded" into different forms for different audiences -* *Figuration*: The rules for folding/unfolding are transparent and reversible - -[cols="1,2,1"] -|=== -| Concept | Description | Learn More - -| i-docs Navigation -| "Choose Your Own Adventure" for evidence -| link:wiki/navigation.adoc[Wiki] - -| PROMPT Scoring -| "Nutrition labels" for trustworthiness -| link:wiki/prompt.adoc[Wiki] - -| Boundary Objects -| "Shared maps" with multiple routes -| link:wiki/boundary-objects.adoc[Wiki] - -| Evidence Graphs -| The "skeleton" beneath the origami -| link:wiki/graphs.adoc[Wiki] -|=== - -=== For the Impatient - -1. Try the <> to see it in action -2. Skim the link:wiki/binary-origami.adoc[Binary-Origami Metaphor] page -3. Dive into the link:wiki/faqs.adoc[FAQ] if something's unclear - -== Vision - -We didn't fall from Truth to Post-Truth; we evolved to complex epistemology without building infrastructure. *This system IS that infrastructure.* - -=== Core Concepts - -1. *i-docs Navigation*: Navigation over narration, reader agency -2. *PROMPT Framework*: 6-dimensional epistemological scoring (Provenance, Replicability, Objective, Methodology, Publication, Transparency) -3. *Boundary Objects*: Multiple audience perspectives on same evidence -4. Evidence Graph for Investigative Journalism amd Related Disciplines - -[[quick-start]] -== Quick Start - -=== Prerequisites - -- *Elixir 1.18+* & *Erlang/OTP 27+* -- *Phoenix 1.8+* -- *Podman* & *podman-compose* -- *just* (task runner): https://github.com/casey/just - -=== 1. Clone Repository - -```bash -git clone https://github.com/Hyperpolymath/bofig.git -cd bofig -``` - -=== 2. Start Databases - -```bash -podman-compose up -d -``` - -Verify ArangoDB is running: http://localhost:8529 (root/dev) - -=== 3. Full Setup (deps, databases, seeds) - -```bash -just setup -``` - -Or manually: -```bash -mix deps.get -mix ecto.create -mix run -e "EvidenceGraph.ArangoDB.setup_database()" -mix run priv/repo/seeds.exs -``` - -=== 4. Start Phoenix Server - -```bash -just dev -``` - -Visit: -- *Application*: http://localhost:4000 (register/login required) -- *GraphQL Playground*: http://localhost:4000/api/graphiql (dev only) -- *Health Check*: http://localhost:4000/api/health - -== GraphQL API Examples - -=== Query: Get All Claims - -```graphql -query { - claims(investigationId: "uk_inflation_2023") { - id - text - claimType - confidenceLevel - promptScores { - provenance - replicability - objective - methodology - publication - transparency - overall - } - supportingEvidence { - evidence { - title - evidenceType - } - weight - confidence - } - } -} -``` - -=== Query: Evidence Chain (Graph Traversal) - -```graphql -query { - evidenceChain(claimId: "claim_1", maxDepth: 3) { - rootClaim { - text - } - nodes { - ... on Claim { - id - text - } - ... on Evidence { - id - title - } - } - edges { - relationshipType - weight - confidence - } - maxDepth - } -} -``` - -=== Mutation: Create Claim - -```graphql -mutation { - createClaim(input: { - investigationId: "uk_inflation_2023" - text: "Inflation disproportionately affected renters" - claimType: SUPPORTING - confidenceLevel: 0.85 - promptScores: { - provenance: 70 - replicability: 65 - objective: 75 - methodology: 70 - publication: 65 - transparency: 70 - } - }) { - id - text - promptScores { - overall - } - } -} -``` - -=== Mutation: Import from Zotero - -```graphql -mutation { - importFromZotero( - investigationId: "uk_inflation_2023" - zoteroJson: { - key: "ABC123" - itemType: "journalArticle" - title: "New Economic Study" - url: "https://doi.org/10.1111/example" - creators: [{name: "Smith, J."}] - tags: [{tag: "economics"}] - } - ) { - id - title - zoteroKey - } -} -``` - -=== Query: Navigation Paths - -```graphql -query { - navigationPaths( - investigationId: "uk_inflation_2023" - audienceType: RESEARCHER - ) { - id - name - description - pathNodes { - entityId - entityType - order - context - } - } -} -``` - -=== Mutation: Auto-Generate Navigation Path - -```graphql -mutation { - autoGeneratePath( - investigationId: "uk_inflation_2023" - audienceType: SKEPTIC - ) { - id - name - pathNodes { - entityId - order - } - } -} -``` - -== Project Structure - -``` -bofig/ -├── lib/ -│ ├── evidence_graph/ # Core business logic -│ │ ├── claims/ # Claims context -│ │ │ └── claim.ex -│ │ ├── evidence/ # Evidence context -│ │ │ └── evidence.ex -│ │ ├── relationships/ # Graph edges -│ │ │ └── relationship.ex -│ │ ├── navigation/ # Audience paths -│ │ │ └── path.ex -│ │ ├── arango.ex # ArangoDB client -│ │ ├── prompt_scores.ex # PROMPT scoring -│ │ └── application.ex # OTP supervisor -│ └── evidence_graph_web/ # Phoenix web layer -│ ├── schema/ # GraphQL schema -│ │ ├── types/ # Type definitions -│ │ └── schema.ex # Root schema -│ ├── endpoint.ex -│ └── router.ex -├── priv/repo/ -│ └── seeds.exs # UK Inflation 2023 test data -├── config/ # Environment configs -├── docs/ # Architecture docs -│ ├── database-evaluation.md -│ └── zotero-integration.md -├── ARCHITECTURE.md # Data model, API design -├── ROADMAP.md # 18-month plan -├── CLAUDE.md # AI assistant context -├── Containerfile # OCI container build -└── podman-compose.yml # Container orchestration -``` - -== UK Inflation 2023 Test Dataset - -The seed data includes a complete investigation: - -- *7 Claims* (primary, supporting, counter) -- *10 Evidence items* (expand to 30) - - Official statistics: ONS CPI, Ofgem, BoE - - Academic: Peer-reviewed studies - - Think tanks: Resolution Foundation, IFS - - Interviews: Expert opinions -- *10 Relationships* (supports/contradicts/contextualizes) -- *3 Navigation Paths*: - 1. *Researcher*: Evidence-first, methodology priority - 2. *Policymaker*: Authoritative sources, recommendations - 3. *Affected Person*: Personal impact, clarity - -=== PROMPT Score Examples - -| Evidence | Prov | Repl | Obj | Meth | Pub | Trans | Overall | -|----------|------|------|-----|------|-----|-------|---------| -| ONS CPI Data | 100 | 100 | 95 | 95 | 100 | 95 | *97.5* | -| Academic Study | 85 | 80 | 75 | 85 | 90 | 75 | *81.8* | -| Think Tank Report | 75 | 70 | 65 | 75 | 80 | 70 | *72.3* | -| Expert Interview | 85 | 45 | 60 | 50 | 40 | 75 | *59.0* | - -== Development - -=== Run Tests - -```bash -mix test -``` - -=== Interactive Shell - -```bash -iex -S mix phx.server - -= Query ArangoDB directly - -iex> EvidenceGraph.ArangoDB.query("FOR c IN claims RETURN c") - -= Get a claim - -iex> EvidenceGraph.Claims.get_claim("claim_1") - -= Evidence chain traversal - -iex> EvidenceGraph.Relationships.evidence_chain("claim_1", 3) -``` - -=== Code Quality - -```bash -= Format code - -mix format - -= Static analysis - -mix credo - -= Type checking - -mix dialyzer -``` - -== Deployment (Phase 2) - -- *Hosting*: Hetzner Cloud (EU data sovereignty) -- *ArangoDB*: ArangoDB Oasis (€45/month) -- *Phoenix*: Systemd service, Nginx reverse proxy -- *CI/CD*: GitHub Actions - -== Documentation - -=== Conceptual (Start Here!) - -- link:wiki/index.adoc[Binary-Origami Wiki] - Explains the metaphor and concepts in plain language -- link:wiki/binary-origami.adoc[The Metaphor] - Why "Binary-Origami Figuration"? -- link:wiki/folding-101.adoc[Folding 101] - Hands-on tutorial -- link:wiki/faqs.adoc[FAQ] - Common questions answered -- link:wiki/glossary.adoc[Glossary] - Term definitions - -=== Technical - -- link:ARCHITECTURE.md[ARCHITECTURE.md] - Data model, database design, API specs -- link:ROADMAP.md[ROADMAP.md] - 18-month implementation plan -- link:docs/database-evaluation.md[docs/database-evaluation.md] - ArangoDB comparison -- link:docs/zotero-integration.md[docs/zotero-integration.md] - Two-way sync design -- link:CLAUDE.md[CLAUDE.md] - AI assistant context - -== Key Features - -=== Implemented (v1.0.0) - -* Multi-model ArangoDB integration (document + graph) -* GraphQL API with Absinthe (15 queries, 11 mutations) -* PROMPT epistemological scoring (6 dimensions, audience weighting) -* Claims, Evidence, Relationships, Navigation Paths data models -* Graph traversal algorithms (evidence chains, shortest path, contradiction detection) -* Zotero REST API (import, export, batch-import, sync-status) -* Phoenix 1.8 LiveView frontend (5 pages: Dashboard, Investigation, Graph, PROMPT, Navigation) -* User authentication (phx.gen.auth with bcrypt, magic links) -* D3.js force-directed graph + radar chart visualisations -* Audience-weighted navigation paths (6 types) -* UK Inflation 2023 test dataset (7 claims, 30 evidence, 38 relationships) -* Production deployment (Containerfile, nginx, systemd) -* NUJ user testing protocols -* A2ML v2.1 Cyberwar-Ready Trustfile -* 257 tests, 0 failures, full RSR compliance - -=== Coming Next (Phase 2) - -* Zotero browser extension (one-click import) -* Multi-investigation dashboard -* Real-time collaborative editing -* Advanced visualisations (timeline, heatmap, Sankey) -* IPFS provenance integration -* Hetzner Cloud deployment - -== Philosophy - -This isn't just a database. It's infrastructure for *coordinating without consensus*. - -Every design choice asks: -1. Does this support multiple audience perspectives? -2. Does this make epistemology measurable? -3. Does this enable navigation over narration? - -== Contributing - -Open source from day 1. See [ROADMAP.md](ROADMAP.md) for planned features. - -*Month 3 = Decision Point*: User testing with 25 NUJ journalists determines go/no-go. - -== Related Projects - -* https://github.com/hyperpolymath/lithoglyph[LithoglyphDB] - The narrative-first, reversible, audit-grade database -* https://github.com/hyperpolymath/gpnl[GPNL] - Dependently-typed Glyph Projection Language (compile-time proofs) -* https://github.com/hyperpolymath/lithoglyph-studio[Lithoglyph Studio] - Zero-friction GUI for non-technical users -* https://github.com/hyperpolymath/zotero-formdb[Zotero-Lithoglyph] - Reference manager with PROMPT scores - -== License - -link:LICENSE[MPL-2.0] (Palimpsest License) - -== Contact - -- *Repository*: https://github.com/Hyperpolymath/bofig -- *Issues*: https://github.com/Hyperpolymath/bofig/issues -- *User Testing*: NUJ network (Month 3, 6, 12) - ---- - -*Built with:* Elixir, Phoenix, ArangoDB, Absinthe, LiveView, D3.js - -*Inspired by:* i-docs (PMPL-1.0 Open Doc Lab), Boundary Objects (Star & Griesemer), Pragmatic Epistemology - -*Last Updated:* 2026-02-21 - - -== Architecture - -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. diff --git a/README.md b/README.md index 751cd95..21d6f2d 100644 --- a/README.md +++ b/README.md @@ -1,131 +1,128 @@ -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) + -= Binary-Origami Figurator -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2025 hyperpolymath +\> Infrastructure for pragmatic epistemology. Combining +- i-docs navigation, -> Infrastructure for pragmatic epistemology. Combining +- PROMPT epistemological scoring, and -- i-docs navigation, -- PROMPT epistemological scoring, and - boundary objects theory. An evidence graph for investigative journalism. -*Status:* Phase 1 (PoC) - v1.0.0 Release -*Version:* 1.0.0 +**Status:** Phase 1 (PoC) - v1.0.0 Release **Version:** 1.0.0 -== New Here? Start with the Wiki +# New Here? Start with the Wiki -[TIP] -==== -*Confused by the terminology?* The link:wiki/index.adoc[Binary-Origami Wiki] explains everything in metaphors, diagrams, and plain language. -==== +> [!TIP] +> **Confused by the terminology?** The [Binary-Origami +> Wiki](wiki/index.adoc) explains everything in metaphors, diagrams, and +> plain language. -[quote] -____ -This isn't just a database. It's *infrastructure for folding and unfolding evidence*—so everyone can see the shape that fits their needs. -____ +> This isn’t just a database. It’s **infrastructure for folding and +> unfolding evidence**—so everyone can see the shape that fits their +> needs. -=== Why "Binary-Origami"? +## Why "Binary-Origami"? -* *Binary*: Evidence is stored as clear, connected data (supports/contradicts, 0-100 scores) -* *Origami*: The same evidence can be "folded" into different forms for different audiences -* *Figuration*: The rules for folding/unfolding are transparent and reversible +- **Binary**: Evidence is stored as clear, connected data + (supports/contradicts, 0-100 scores) -[cols="1,2,1"] -|=== -| Concept | Description | Learn More +- **Origami**: The same evidence can be "folded" into different forms + for different audiences -| i-docs Navigation -| "Choose Your Own Adventure" for evidence -| link:wiki/navigation.adoc[Wiki] +- **Figuration**: The rules for folding/unfolding are transparent and + reversible -| PROMPT Scoring -| "Nutrition labels" for trustworthiness -| link:wiki/prompt.adoc[Wiki] +| Concept | Description | Learn More | +|----|----|----| +| i-docs Navigation | "Choose Your Own Adventure" for evidence | [Wiki](wiki/navigation.adoc) | +| PROMPT Scoring | "Nutrition labels" for trustworthiness | [Wiki](wiki/prompt.adoc) | +| Boundary Objects | "Shared maps" with multiple routes | [Wiki](wiki/boundary-objects.adoc) | +| Evidence Graphs | The "skeleton" beneath the origami | [Wiki](wiki/graphs.adoc) | -| Boundary Objects -| "Shared maps" with multiple routes -| link:wiki/boundary-objects.adoc[Wiki] +## For the Impatient -| Evidence Graphs -| The "skeleton" beneath the origami -| link:wiki/graphs.adoc[Wiki] -|=== +1. Try the + Quick Start to + see it in action -=== For the Impatient +2. Skim the [Binary-Origami Metaphor](wiki/binary-origami.adoc) page -1. Try the <> to see it in action -2. Skim the link:wiki/binary-origami.adoc[Binary-Origami Metaphor] page -3. Dive into the link:wiki/faqs.adoc[FAQ] if something's unclear +3. Dive into the [FAQ](wiki/faqs.adoc) if something’s unclear -== Vision +# Vision -We didn't fall from Truth to Post-Truth; we evolved to complex epistemology without building infrastructure. *This system IS that infrastructure.* +We didn’t fall from Truth to Post-Truth; we evolved to complex +epistemology without building infrastructure. **This system IS that +infrastructure.** -=== Core Concepts +## Core Concepts -1. *i-docs Navigation*: Navigation over narration, reader agency -2. *PROMPT Framework*: 6-dimensional epistemological scoring (Provenance, Replicability, Objective, Methodology, Publication, Transparency) -3. *Boundary Objects*: Multiple audience perspectives on same evidence -4. Evidence Graph for Investigative Journalism amd Related Disciplines +1. **i-docs Navigation**: Navigation over narration, reader agency -[[quick-start]] -== Quick Start +2. **PROMPT Framework**: 6-dimensional epistemological scoring + (Provenance, Replicability, Objective, Methodology, Publication, + Transparency) -=== Prerequisites +3. **Boundary Objects**: Multiple audience perspectives on same + evidence -- *Elixir 1.18+* & *Erlang/OTP 27+* -- *Phoenix 1.8+* -- *Podman* & *podman-compose* -- *just* (task runner): https://github.com/casey/just +4. Evidence Graph for Investigative Journalism amd Related Disciplines -=== 1. Clone Repository +# Quick Start + +## Prerequisites + +- **Elixir 1.18+** & **Erlang/OTP 27+** + +- **Phoenix 1.8+** + +- **Podman** & **podman-compose** + +- **just** (task runner): + +## 1. Clone Repository ```bash git clone https://github.com/Hyperpolymath/bofig.git cd bofig ``` -=== 2. Start Databases +## 2. Start Databases ```bash podman-compose up -d ``` -Verify ArangoDB is running: http://localhost:8529 (root/dev) +Verify ArangoDB is running: (root/dev) -=== 3. Full Setup (deps, databases, seeds) +## 3. Full Setup (deps, databases, seeds) ```bash just setup ``` -Or manually: -```bash -mix deps.get -mix ecto.create -mix run -e "EvidenceGraph.ArangoDB.setup_database()" -mix run priv/repo/seeds.exs -``` +Or manually: `` `bash `` `mix` `deps.get` `mix` `ecto.create` `mix` +`run` `-e` `"EvidenceGraph.ArangoDB.setup_database()"` `mix` `run` +`priv/repo/seeds.exs`\` -=== 4. Start Phoenix Server +## 4. Start Phoenix Server ```bash just dev ``` -Visit: -- *Application*: http://localhost:4000 (register/login required) -- *GraphQL Playground*: http://localhost:4000/api/graphiql (dev only) -- *Health Check*: http://localhost:4000/api/health +Visit: - **Application**: (register/login +required) - **GraphQL Playground**: +(dev only) - **Health Check**: -== GraphQL API Examples +# GraphQL API Examples -=== Query: Get All Claims +## Query: Get All Claims ```graphql query { @@ -155,7 +152,7 @@ query { } ``` -=== Query: Evidence Chain (Graph Traversal) +## Query: Evidence Chain (Graph Traversal) ```graphql query { @@ -183,7 +180,7 @@ query { } ``` -=== Mutation: Create Claim +## Mutation: Create Claim ```graphql mutation { @@ -210,7 +207,7 @@ mutation { } ``` -=== Mutation: Import from Zotero +## Mutation: Import from Zotero ```graphql mutation { @@ -232,7 +229,7 @@ mutation { } ``` -=== Query: Navigation Paths +## Query: Navigation Paths ```graphql query { @@ -253,7 +250,7 @@ query { } ``` -=== Mutation: Auto-Generate Navigation Path +## Mutation: Auto-Generate Navigation Path ```graphql mutation { @@ -271,76 +268,84 @@ mutation { } ``` -== Project Structure +# Project Structure + + bofig/ + ├── lib/ + │ ├── evidence_graph/ # Core business logic + │ │ ├── claims/ # Claims context + │ │ │ └── claim.ex + │ │ ├── evidence/ # Evidence context + │ │ │ └── evidence.ex + │ │ ├── relationships/ # Graph edges + │ │ │ └── relationship.ex + │ │ ├── navigation/ # Audience paths + │ │ │ └── path.ex + │ │ ├── arango.ex # ArangoDB client + │ │ ├── prompt_scores.ex # PROMPT scoring + │ │ └── application.ex # OTP supervisor + │ └── evidence_graph_web/ # Phoenix web layer + │ ├── schema/ # GraphQL schema + │ │ ├── types/ # Type definitions + │ │ └── schema.ex # Root schema + │ ├── endpoint.ex + │ └── router.ex + ├── priv/repo/ + │ └── seeds.exs # UK Inflation 2023 test data + ├── config/ # Environment configs + ├── docs/ # Architecture docs + │ ├── database-evaluation.md + │ └── zotero-integration.md + ├── ARCHITECTURE.md # Data model, API design + ├── ROADMAP.md # 18-month plan + ├── CLAUDE.md # AI assistant context + ├── Containerfile # OCI container build + └── podman-compose.yml # Container orchestration + +# UK Inflation 2023 Test Dataset -``` -bofig/ -├── lib/ -│ ├── evidence_graph/ # Core business logic -│ │ ├── claims/ # Claims context -│ │ │ └── claim.ex -│ │ ├── evidence/ # Evidence context -│ │ │ └── evidence.ex -│ │ ├── relationships/ # Graph edges -│ │ │ └── relationship.ex -│ │ ├── navigation/ # Audience paths -│ │ │ └── path.ex -│ │ ├── arango.ex # ArangoDB client -│ │ ├── prompt_scores.ex # PROMPT scoring -│ │ └── application.ex # OTP supervisor -│ └── evidence_graph_web/ # Phoenix web layer -│ ├── schema/ # GraphQL schema -│ │ ├── types/ # Type definitions -│ │ └── schema.ex # Root schema -│ ├── endpoint.ex -│ └── router.ex -├── priv/repo/ -│ └── seeds.exs # UK Inflation 2023 test data -├── config/ # Environment configs -├── docs/ # Architecture docs -│ ├── database-evaluation.md -│ └── zotero-integration.md -├── ARCHITECTURE.md # Data model, API design -├── ROADMAP.md # 18-month plan -├── CLAUDE.md # AI assistant context -├── Containerfile # OCI container build -└── podman-compose.yml # Container orchestration -``` +The seed data includes a complete investigation: -== UK Inflation 2023 Test Dataset +- **7 Claims** (primary, supporting, counter) -The seed data includes a complete investigation: +- **10 Evidence items** (expand to 30) + +- Official statistics: ONS CPI, Ofgem, BoE + +- Academic: Peer-reviewed studies -- *7 Claims* (primary, supporting, counter) -- *10 Evidence items* (expand to 30) - - Official statistics: ONS CPI, Ofgem, BoE - - Academic: Peer-reviewed studies - - Think tanks: Resolution Foundation, IFS - - Interviews: Expert opinions -- *10 Relationships* (supports/contradicts/contextualizes) -- *3 Navigation Paths*: - 1. *Researcher*: Evidence-first, methodology priority - 2. *Policymaker*: Authoritative sources, recommendations - 3. *Affected Person*: Personal impact, clarity +- Think tanks: Resolution Foundation, IFS -=== PROMPT Score Examples +- Interviews: Expert opinions -| Evidence | Prov | Repl | Obj | Meth | Pub | Trans | Overall | -|----------|------|------|-----|------|-----|-------|---------| -| ONS CPI Data | 100 | 100 | 95 | 95 | 100 | 95 | *97.5* | -| Academic Study | 85 | 80 | 75 | 85 | 90 | 75 | *81.8* | -| Think Tank Report | 75 | 70 | 65 | 75 | 80 | 70 | *72.3* | -| Expert Interview | 85 | 45 | 60 | 50 | 40 | 75 | *59.0* | +- **10 Relationships** (supports/contradicts/contextualizes) -== Development +- **3 Navigation Paths**: -=== Run Tests + 1. **Researcher**: Evidence-first, methodology priority + + 2. **Policymaker**: Authoritative sources, recommendations + + 3. **Affected Person**: Personal impact, clarity + +## PROMPT Score Examples + +\| Evidence \| Prov \| Repl \| Obj \| Meth \| Pub \| Trans \| Overall \| +\|----------\|------\|------\|-----\|------\|-----\|-------\|---------\| +\| ONS CPI Data \| 100 \| 100 \| 95 \| 95 \| 100 \| 95 \| **97.5** \| \| +Academic Study \| 85 \| 80 \| 75 \| 85 \| 90 \| 75 \| **81.8** \| \| +Think Tank Report \| 75 \| 70 \| 65 \| 75 \| 80 \| 70 \| **72.3** \| \| +Expert Interview \| 85 \| 45 \| 60 \| 50 \| 40 \| 75 \| **59.0** \| + +# Development + +## Run Tests ```bash mix test ``` -=== Interactive Shell +## Interactive Shell ```bash iex -S mix phx.server @@ -358,7 +363,7 @@ iex> EvidenceGraph.Claims.get_claim("claim_1") iex> EvidenceGraph.Relationships.evidence_chain("claim_1", 3) ``` -=== Code Quality +## Code Quality ```bash = Format code @@ -374,101 +379,153 @@ mix credo mix dialyzer ``` -== Deployment (Phase 2) +# Deployment (Phase 2) + +- **Hosting**: Hetzner Cloud (EU data sovereignty) + +- **ArangoDB**: ArangoDB Oasis (€45/month) + +- **Phoenix**: Systemd service, Nginx reverse proxy + +- **CI/CD**: GitHub Actions + +# Documentation + +## Conceptual (Start Here!) + +- [Binary-Origami Wiki](wiki/index.adoc) - Explains the metaphor and + concepts in plain language + +- [The Metaphor](wiki/binary-origami.adoc) - Why "Binary-Origami + Figuration"? + +- [Folding 101](wiki/folding-101.adoc) - Hands-on tutorial + +- [FAQ](wiki/faqs.adoc) - Common questions answered + +- [Glossary](wiki/glossary.adoc) - Term definitions + +## Technical + +- ARCHITECTURE - Data model, + database design, API specs + +- ROADMAP - 18-month implementation + plan + +- [docs/database-evaluation.md](docs/database-evaluation.md) - ArangoDB + comparison + +- [docs/zotero-integration.md](docs/zotero-integration.md) - Two-way + sync design + +- CLAUDE - AI assistant context + +# Key Features + +## Implemented (v1.0.0) + +- Multi-model ArangoDB integration (document + graph) + +- GraphQL API with Absinthe (15 queries, 11 mutations) + +- PROMPT epistemological scoring (6 dimensions, audience weighting) + +- Claims, Evidence, Relationships, Navigation Paths data models + +- Graph traversal algorithms (evidence chains, shortest path, + contradiction detection) + +- Zotero REST API (import, export, batch-import, sync-status) + +- Phoenix 1.8 LiveView frontend (5 pages: Dashboard, Investigation, + Graph, PROMPT, Navigation) + +- User authentication (phx.gen.auth with bcrypt, magic links) + +- D3.js force-directed graph + radar chart visualisations + +- Audience-weighted navigation paths (6 types) + +- UK Inflation 2023 test dataset (7 claims, 30 evidence, 38 + relationships) + +- Production deployment (Containerfile, nginx, systemd) + +- NUJ user testing protocols + +- A2ML v2.1 Cyberwar-Ready Trustfile + +- 257 tests, 0 failures, full RSR compliance -- *Hosting*: Hetzner Cloud (EU data sovereignty) -- *ArangoDB*: ArangoDB Oasis (€45/month) -- *Phoenix*: Systemd service, Nginx reverse proxy -- *CI/CD*: GitHub Actions +## Coming Next (Phase 2) -== Documentation +- Zotero browser extension (one-click import) -=== Conceptual (Start Here!) +- Multi-investigation dashboard -- link:wiki/index.adoc[Binary-Origami Wiki] - Explains the metaphor and concepts in plain language -- link:wiki/binary-origami.adoc[The Metaphor] - Why "Binary-Origami Figuration"? -- link:wiki/folding-101.adoc[Folding 101] - Hands-on tutorial -- link:wiki/faqs.adoc[FAQ] - Common questions answered -- link:wiki/glossary.adoc[Glossary] - Term definitions +- Real-time collaborative editing -=== Technical +- Advanced visualisations (timeline, heatmap, Sankey) -- link:ARCHITECTURE.md[ARCHITECTURE.md] - Data model, database design, API specs -- link:ROADMAP.md[ROADMAP.md] - 18-month implementation plan -- link:docs/database-evaluation.md[docs/database-evaluation.md] - ArangoDB comparison -- link:docs/zotero-integration.md[docs/zotero-integration.md] - Two-way sync design -- link:CLAUDE.md[CLAUDE.md] - AI assistant context +- IPFS provenance integration -== Key Features +- Hetzner Cloud deployment -=== Implemented (v1.0.0) +# Philosophy -* Multi-model ArangoDB integration (document + graph) -* GraphQL API with Absinthe (15 queries, 11 mutations) -* PROMPT epistemological scoring (6 dimensions, audience weighting) -* Claims, Evidence, Relationships, Navigation Paths data models -* Graph traversal algorithms (evidence chains, shortest path, contradiction detection) -* Zotero REST API (import, export, batch-import, sync-status) -* Phoenix 1.8 LiveView frontend (5 pages: Dashboard, Investigation, Graph, PROMPT, Navigation) -* User authentication (phx.gen.auth with bcrypt, magic links) -* D3.js force-directed graph + radar chart visualisations -* Audience-weighted navigation paths (6 types) -* UK Inflation 2023 test dataset (7 claims, 30 evidence, 38 relationships) -* Production deployment (Containerfile, nginx, systemd) -* NUJ user testing protocols -* A2ML v2.1 Cyberwar-Ready Trustfile -* 257 tests, 0 failures, full RSR compliance +This isn’t just a database. It’s infrastructure for **coordinating +without consensus**. -=== Coming Next (Phase 2) +Every design choice asks: 1. Does this support multiple audience +perspectives? 2. Does this make epistemology measurable? 3. Does this +enable navigation over narration? -* Zotero browser extension (one-click import) -* Multi-investigation dashboard -* Real-time collaborative editing -* Advanced visualisations (timeline, heatmap, Sankey) -* IPFS provenance integration -* Hetzner Cloud deployment +# Contributing -== Philosophy +Open source from day 1. See \[ROADMAP.md\](ROADMAP.md) for planned +features. -This isn't just a database. It's infrastructure for *coordinating without consensus*. +**Month 3 = Decision Point**: User testing with 25 NUJ journalists +determines go/no-go. -Every design choice asks: -1. Does this support multiple audience perspectives? -2. Does this make epistemology measurable? -3. Does this enable navigation over narration? +# Related Projects -== Contributing +- [LithoglyphDB](https://github.com/hyperpolymath/lithoglyph) - The + narrative-first, reversible, audit-grade database -Open source from day 1. See [ROADMAP.md](ROADMAP.md) for planned features. +- [GPNL](https://github.com/hyperpolymath/gpnl) - Dependently-typed + Glyph Projection Language (compile-time proofs) -*Month 3 = Decision Point*: User testing with 25 NUJ journalists determines go/no-go. +- [Lithoglyph + Studio](https://github.com/hyperpolymath/lithoglyph-studio) - + Zero-friction GUI for non-technical users -== Related Projects +- [Zotero-Lithoglyph](https://github.com/hyperpolymath/zotero-formdb) - + Reference manager with PROMPT scores -* https://github.com/hyperpolymath/lithoglyph[LithoglyphDB] - The narrative-first, reversible, audit-grade database -* https://github.com/hyperpolymath/gpnl[GPNL] - Dependently-typed Glyph Projection Language (compile-time proofs) -* https://github.com/hyperpolymath/lithoglyph-studio[Lithoglyph Studio] - Zero-friction GUI for non-technical users -* https://github.com/hyperpolymath/zotero-formdb[Zotero-Lithoglyph] - Reference manager with PROMPT scores +# License -== License +MPL-2 (Palimpsest License) -link:LICENSE[MPL-2.0] (Palimpsest License) +# Contact -== Contact +- **Repository**: -- *Repository*: https://github.com/Hyperpolymath/bofig -- *Issues*: https://github.com/Hyperpolymath/bofig/issues -- *User Testing*: NUJ network (Month 3, 6, 12) +- **Issues**: ---- +- **User Testing**: NUJ network (Month 3, 6, 12) -*Built with:* Elixir, Phoenix, ArangoDB, Absinthe, LiveView, D3.js +------------------------------------------------------------------------ -*Inspired by:* i-docs (PMPL-1.0 Open Doc Lab), Boundary Objects (Star & Griesemer), Pragmatic Epistemology +**Built with:** Elixir, Phoenix, ArangoDB, Absinthe, LiveView, D3.js -*Last Updated:* 2026-02-21 +**Inspired by:** i-docs (PMPL-1.0 Open Doc Lab), Boundary Objects (Star +& Griesemer), Pragmatic Epistemology +**Last Updated:** 2026-02-21 -== Architecture +# Architecture -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. +See TOPOLOGY for a visual +architecture map and completion dashboard.