A local-first TypeScript engine that turns reviewed Reddit and community discussion signals into evidence-safe GEO knowledge graphs, prioritized opportunities, and human-reviewed publishing packages.
Workflow outputs are drafts. Publishing Packages are the only publishable assets.
Canonical Authority Assets define the publishing standard for future keywords. Every package requires canonical alignment and human review before publication.
Authority order, publication rule, and evidence boundary
- Canonical Publishing Package
- Package Payload Source Paths
- Freeze and Governance Documents
- Workflow Outputs
- Backtests and Regression Tests
Keyword
-> Workflow Draft
-> Canonical Alignment
-> Publishing Package
-> Human Review
-> Publish
A keyword becomes publishable only after it:
- passes canonical alignment;
- generates a publishing package;
- preserves the evidence boundary;
- maintains support-verification routing;
- matches the canonical authority structure.
Community discussion provides discussion intelligence, not product truth. Discussion patterns may inform decisions, but they do not verify claims.
- Workflow Freeze v1:
frozen_v1_with_monitoring - Canonical Publishing Standard v1:
active - Publishing Packages:
required - Workflow Outputs:
draft_only
This project treats community research as a reusable knowledge system rather than a prompt-to-article shortcut.
| Capability | What It Adds |
|---|---|
| Reddit discussion intelligence | Converts recurring hesitation, practical failures, and decision friction into paraphrased reusable assets. |
| Five knowledge libraries | Structures real hesitation into Question, Decision, Evidence, Scenario, and Persona assets. |
| Topic Graph | Connects isolated assets into topic-level decision and verification networks. |
| Opportunity Intelligence | Ranks Support, GEO Blog, FAQ, Visual Verification, and Pillar Branch opportunities. |
| Canonical Alignment | Detects structural, evidence, routing, and commercial drift before packaging. |
| Publishing Packages | Unifies Reddit, Blog, Support, Visual, Alt Text, backtest results, and final review status. |
The system does not automatically publish content. Its purpose is to transform reviewed discussion signals into structured authority assets that can be verified and published responsibly.
Keyword tools can show what people search for. Reddit discussions can reveal why a decision remains difficult: what buyers hesitate over, what fails under real-use pressure, what tradeoffs repeat, and what needs to be verified before someone can act confidently.
GEO Knowledge Engine preserves those recurring meanings without reusing the original wording:
- hesitation becomes a reusable Question Asset;
- a practical failure becomes a Scenario or Evidence Asset;
- a repeated tradeoff becomes a Decision Asset;
- contextual constraints help form a more specific Persona Asset;
- verification needs become Support and Visual Verification opportunities.
Reddit hesitation
-> paraphrased knowledge asset
-> decision node
-> verification opportunity
-> human-reviewed publishing package
These signals can inform FAQ coverage, support checks, visual verification, GEO Blog decision frameworks, and future Pillar planning. They remain discussion intelligence rather than verified product truth.
flowchart LR
A["Reddit and Community Signals<br/>JSON / XLSX / OAuth"] --> B["Knowledge Assets<br/>Question / Decision / Evidence<br/>Scenario / Persona"]
B --> C["Topic Graph"]
C --> D["Opportunity Ranking"]
D --> E["Workflow Draft"]
E --> F["Canonical Alignment"]
F --> G["Publishing Package"]
G --> H["Human Review"]
The operational pipeline is:
Asset Intake
-> Knowledge Extraction
-> Knowledge Database
-> Knowledge Quality
-> Topic Graph
-> Opportunity Intelligence
-> Workflow Draft
-> Canonical Alignment
-> Publishing Package
A complete publishing package can contain:
- Reddit Draft
- GEO Authority Blog
- Support Verification Guide
- Visual Verification Prompt System
- Alt Text and Caption Appendix
- Backtest Executive Summary
- Final Decision
- Reusable Rules
The package payload and its relative sourcePaths are the machine-readable source of truth. The DOCX package is the formal human-review layer.
The repository includes three sanitized publishing standards:
These packages are not ordinary workflow examples. They demonstrate the required continuity between discussion framing, decision structure, evidence boundaries, support verification, visual checks, and final packaging.
Local operational outputs remain excluded from Git because they may contain private paths, raw source material, or transient review artifacts.
Requirements:
- Node.js 22
- npm
- Python 3 for public DOCX inspection
npm.cmd ci
npm.cmd run typecheck
npm.cmd run build
npm.cmd test
npm.cmd run audit:publicRun the canonical Blog alignment example:
node dist/examples/blog-canonical-alignment-example.jsThe intake layer is designed to retain decision value rather than copied language. It captures recurring concerns, source metadata, practical scenarios, and verification pressure, then hands reviewed signals to deterministic extraction and quality layers.
Reddit is the most mature discussion source in v1, but the knowledge model remains product-agnostic and source-extensible.
Reddit-style signals can enter through two read-only paths:
Local JSON or XLSX Upload -> RawKnowledgeSignalInput
Official Reddit OAuth API -> RawKnowledgeSignalInput
Supported modes:
local_upload: import reviewed local JSON or XLSX signals.api_urls: collect explicitly selected Reddit threads through the official API.api_search: collect a bounded query and optional subreddit selection through the official API.
Local upload is the default and canonical mode. OAuth collection is opt-in and requires:
REDDIT_CLIENT_ID
REDDIT_CLIENT_SECRET
REDDIT_USER_AGENT
API signals begin as raw and human_review_required. Raw API payloads remain in an ignored, short-lived local cache and do not become reusable assets. The gateway does not post, vote, comment, or fall back to HTML scraping.
See Reddit Source Gateway v1 for limits, caching, configuration, and compliance boundaries.
- Start with the Keyword Production Queue.
- Import reviewed signals with Import New Knowledge Assets.
- Generate a review package with Generate Canonical GEO Publishing Package.
- Review the payload and DOCX using the Operator Manual.
- Publish only after canonical alignment and human review.
- Question Library: user hesitation expressed as reusable questions, not keyword phrases.
- Decision Library: decision forks, common mistakes, and verification needs.
- Evidence Library: paraphrased discussion intelligence that never becomes product truth.
- Scenario Library: environments and real-use pressure for operational verification.
- Persona Library: context-rich reader perspectives that shape tone and content angle.
- No copied Reddit comments in reusable assets.
- No fake evidence or fabricated quotes.
- No product claims inferred from discussion signals.
- No HTML scraping in the canonical intake path.
- No automated Reddit posting, voting, or commenting.
- No direct publication of workflow drafts.
- No affiliate or promotional drift in canonical authority assets.
- Human review remains mandatory.
| Area | Status |
|---|---|
| Workflow Freeze v1 | frozen_v1_with_monitoring |
| Canonical Publishing Standard | canonical_publishing_standard_v1_ready |
| Canonical GEO Authority Blog | canonical_geo_authority_blog_standard_ready |
| GitHub Public Release | github_public_ready_with_monitoring |
| npm publication | Disabled with "private": true |
Known monitoring areas include source-topic leakage, duplicate evidence, persona coverage, Reddit API compliance, and human publication review.
- Canonical Publishing Standard v1
- Canonical GEO Authority Blog Rules v1
- Workflow Freeze v1
- Operator Manual
- v1.0.0 Release Notes
- Security Policy
- Contributing
Licensed under the Apache License 2.0.