How Network Intelligence Works

System check

These cards read the current hub.json export and its recorded provenance. They are a quick health check for the page you are looking at. A green card means the corresponding data is present in this snapshot. Amber means review is recommended. Red means the dashboard is reporting a real limitation or failure.

Checking

Checking dashboard systems

Loading the latest export and source provenance.

A failed collector is not treated as zero mentions. The dashboard shows source availability so a quiet-looking result is not mistaken for complete coverage.

Dashboard orientation

The main page is a static browser view of hub/dashboard/data/hub.json. It does not call collectors or SQLite directly. The controls change what is visible in your browser; they do not rewrite the source items or the export.

Area	What it does	What to know
Brand	Selects All brands or one registered brand.	The current operating scope is FXV-first. FeelXVideos, FeelMe, and Net69 are present in the registry so the hub can expand later.
Theme toggle	Switches between dark and light presentation.	Your choice is saved in this browser under `datoro-dashboard-theme`.
Network view	Starts with the five-second view, then shows a separate high-attention queue followed by the broader action queue of findings that have not been marked taken care of in this browser.	The high-attention queue isolates complaint, scam, refund, and churn-signal intents and shows owner, status, suggested action, age, and source. Both queues use the selected brand scope; the high-attention queue is stable when the general Signal filter changes.
Archive view	Shows findings marked taken care of in this browser.	Archive state is browser-local workflow housekeeping. It does not delete the Markdown item, remove source evidence, or change the generated export.
Data provenance view	Shows latest source runs, targets, timestamps, run statuses, availability states, coverage confidence, counts, errors, and known coverage gaps.	Use this view before treating a low count or quiet period as meaningful.
Brand mentions view	Shows the raw normalized source feed separately from the classified action queue.	Filter by global Brand scope, keyword variant, date range, platform, sentiment, intent, source type, or optional subreddit. Each row keeps its evidence quality, source link, source context, collection method, and availability state; author names and raw JSON are not shown.
Guide icon	Opens this readme page.	This page runs its own system check against the same export used by the dashboard.

Source availability and coverage confidence

The coverage panel and Data provenance view report the latest state of each source route. Coverage confidence describes what the recorded result supports; it is not a claim that the source is exhaustive.

State	Meaning	Confidence label	How to read the count
Available	The route responded and returned one or more records.	Bounded	Results are available for this route and window; listed source gaps still limit completeness.
Partial	Some configured queries, communities, pages, or records were incomplete.	Partial	The count may omit activity and must not be treated as a complete volume.
Unavailable	The route failed, was blocked, or returned no usable result.	None	Unavailable is not zero activity.
Manual import	Evidence was supplied through a human-controlled CSV/JSON or webhook handoff.	Manual	Useful for review, but not automated or exhaustive coverage.
No match	The checked route completed without returning a matching record.	Not established	No match is not proof of zero activity.

A repeated import can return existing records and insert zero new rows while remaining available or manual. The dashboard uses the returned count and explicit availability state, not the inserted-row count alone.

Five-second view

The Network view begins with a compact decision summary so a reviewer can identify the strongest available signal, its source, and the size of the action queue without opening the raw Brand mentions feed.

Top current signal: one finding from the selected brand scope. The ranking gives priority to urgent signals, then heads-up signals, then positive or neutral signals. Within a signal group, open or assigned findings come before watch-list findings, followed by the most recent last-seen date.
Evidence: the top finding includes its controlled intent, theme, relative age, and a readable source link. An old finding remains visibly old; the coverage panel above the summary remains the authority on source completeness.
Action queue: the count covers findings with status open or assigned in the selected scope. The breakdown shows urgent, heads-up, and positive or neutral items. Monitoring findings are not counted as work needing action now.
High-attention queue: a separate active queue for complaint, scam, refund, and churn-signal intents. It shows the owner, recorded status, suggested action, relative age, and safe source link so a response-critical item remains visible even when overall volume is low. It follows the selected Brand scope and browser archive, not the general Signal filter.
Scope and filters: the summary changes with the Brand selector. It is deliberately stable when the Signal filter changes, so the headline does not silently rescope.

The summary is derived from the exported findings snapshot. It does not prove that a source was checked successfully or that the visible top signal is new; read the coverage and freshness information before treating it as current live activity.

Intake, freshness, and summary metrics

Coverage panel: the dashboard always shows the selected scope's latest coverage state and confidence. Partial, unavailable, manual, no-match, and no-run results are disclosed instead of being hidden behind a quiet-looking count. Imported history can still appear below a degraded or review-needed state.
Export generated: when the current JSON export was produced. This is not the same as the time of the last successful source collection.
Last successful collection: the latest successful collector timestamp, or an explicit message when none is recorded.
Review window starts: the start of the configured review window used by the reporting run.
Open items: findings in the selected brand scope whose recorded status is open or assigned.
High risk: open or assigned findings whose recorded risk is high.
High-attention: open or assigned findings whose controlled intent is complaint, scam, refund, or churn-signal. The export summary records the total and per-intent counts.
Needs triage: findings with no category or an uncategorised category.
Oldest open item: the age of the oldest open or assigned finding based on its first-seen date.

The four metric tiles are scoped to the selected brand and all findings. They are intentionally not narrowed by signal or browser-local archive filters. The scope label above the tiles makes this explicit.

Filters and how they combine

The Brand selector and Signal controls narrow the visible action queue. A finding remains visible only when it matches every active selection. The separate Brand mentions view has source-facing filters for keyword variant, date range, platform, sentiment, intent, source type, and the optional Reddit subreddit.

Control	Options	Matching rule
Signal	All signals, Urgent attention, Heads up, Positive / neutral.	Urgent is high risk. Heads up is moderate risk or negative sentiment. Positive / neutral is the remaining signal group.
Brand mentions	Keyword variant, From date, To date, Platform, Sentiment, Intent, Source type, and optional Subreddit.	Every active feed filter must match. Date bounds are inclusive and use the mention's observed date, with published or collection time as a fallback.
Clear all filters	Appears when a Brand or Signal filter is active in the action queue, or when a source filter is active in Brand mentions.	Each clear control resets the filters for its own view. The Brand mentions control does not change the global Brand selector, dashboard view, or archive records.

The general action queue remains intentionally compact. The separate high-attention queue carries the ownership and status fields needed for immediate review, while the raw Brand mentions view provides the detailed source filters needed for evidence review.

Finding anatomy

Each finding is a row on desktop and a stacked card on smaller screens. The four visible columns are:

Column	Displayed information	How to use it
ID and dates	Signal dot before the stable `NI-####` reference, optional review-state badge, first-seen date, and relative last-seen age.	Use the signal and reference ID together when triaging or discussing the finding. A row becomes visually muted when its underlying last-seen date is at least 90 days old. The exact last-seen date, occurrence count, and item file path are intentionally omitted from the compact row.
What was found and source	Concise finding summary, captured verbatim comment when it is distinct from the summary, and each source shown as `Source:` followed by its platform, date, and safe original link.	Use the summary to understand the issue immediately, then read the evidence before acting. If no distinct captured comment exists, the dashboard says No verbatim captured rather than presenting an analyst summary as a quote.
Type	The exported type label, with a safe fallback to the category or Needs review.	Use it as a routing hint, not as proof that the suggested action has been reviewed by a human.
Suggested action	Concise, team-directed action text, Asana copy button, and the archive or restore action.	The team prefix identifies the intended handoff, such as Technical team, Management team, Content team, or Social team. The underlying export still retains routing and action-provenance fields for handoff compatibility.

Brand mentions

The Brand mentions view is the source-facing layer. It is intentionally separate from the action queue so a record can be reviewed before it becomes an intelligence item. Use the global Brand selector together with the feed filters to narrow by keyword variant, inclusive observed-date range, platform, sentiment, intent, source type, and optional subreddit. A row shows platform, source type, source context, evidence quality, observed date, matched term, retained excerpt, classification, collection method, availability state, and an original source link. Reddit-specific fields such as subreddit and parent post remain optional metadata. The feed never displays raw JSON or author names by default.

Source-neutral contract: each record keeps a stable source ID, canonical URL, platform, source family/context, timestamps, retained evidence, matching method, provenance, and availability state.
Reddit routes: search RSS checks configured terms; subreddit RSS sweeps configured communities; thread RSS makes a best-effort comment pass for matched posts and every new post in a deep-scan community.
Windows: the initial pilot uses 30 days. Weekly manual runs use a 14-day overlap so a delayed run does not create a gap.
Deduplication: native source IDs are preferred; canonical URLs are the fallback. The same source found through multiple terms or routes appears once with combined collection methods.
Filter behaviour: all active controls combine with an AND rule. The Keyword variant control matches the stored matched_terms values exactly. From and To dates include both selected calendar days. Clear mention filters resets feed-only controls and leaves the global Brand selection unchanged.
Partial coverage: truncated, unavailable, malformed, or rate-limited feeds are recorded as partial or unavailable in provenance. An empty feed is not interpreted as proof that there were no mentions when its route failed.
Retention: body text, author metadata, and the full raw payload are short-lived. The enrichment operation redacts Reddit raw content older than 48 hours while keeping source IDs, links, dates, subreddit, matched terms, collection status, and availability provenance.

Finding actions

Copy for Asana copies a structured text block to the clipboard. It includes the reference, title, brands, risk, routing context, action provenance, suggested action, and source URL. It does not create an Asana task or send anything publicly.
Mark taken care of stores the finding ID and local timestamp in this browser and moves it from Network to Archive. It does not change items/*.md, the SQLite store, or hub.json.
Restore to active removes the browser-local archive record and returns the finding to Network.
Archive filters still use the selected brand and signal. Archive state changes only which side of the workflow the finding appears in.

Archive state is per browser profile. Another user or another browser will not see the same local archive unless a future persistence workflow is designed and approved.

Data provenance view

The provenance view is the operational truth check. It renders one row for each latest recorded source run in the selected brand scope with:

Collector: the collector or source route that ran.
Target: the brand target for that run.
Last run: the recorded start timestamp.
Run status: the legacy operational status retained for compatibility.
Availability: available, partial, unavailable, manual import, or no match. These states are not interchangeable.
Coverage confidence: a conservative label explaining how much the run supports a coverage claim.
New items: the run item count, or unavailable when the run failed.
Returned: records returned by the route before URL/source deduplication. A no-match run is labelled explicitly rather than shown as unexplained zero activity.
Error: the recorded failure detail when one exists.

Below the table, the page lists known coverage gaps from the export. A failed or rate-limited source remains visible as a source limitation. It is never silently converted into a successful zero-count run.

Warnings and failure states

The dashboard distinguishes problems that happen at different stages:

Intake degraded or needs review: collector provenance shows failures or incomplete statuses. Findings may still be useful imported history, but live coverage is incomplete.
Data warning: the JSON parsed, but fields such as brands, sources, or dates are missing or malformed. Rows remain visible where possible and the warning names the data issue.
Export load error: the browser could not fetch or parse the dashboard export. The page identifies this separately and tells the operator to use an HTTP server.
Data render error: the export loaded but a rendering problem occurred. The page reports a render failure instead of presenting a misleading blank result.
Empty result: the page distinguishes an export with no findings, a brand with no findings, and a filter selection with no matching findings. These messages are not used to hide source failures.

Data pools and current limitations

The dashboard is strongest where a source is healthy and the evidence is directly available. It is directional, not exhaustive.

Pool	How it enters	What it contributes	Current limitation
Reddit	RSS-first term search, configured subreddit sweeps, and best-effort thread/comment RSS; read-only OAuth is available as an opt-in parallel path.	Community discussions, complaints, questions, product language, matched comments, parent titles, scores, and route provenance.	RSS and thread feeds may be blocked, rate-limited, malformed, truncated, or incomplete. OAuth needs a registered app and local authorization. Limitations remain visible and are never represented as zero mentions.
EroScripts / Discourse	Public search endpoint with pagination and retry handling.	Niche forum discussion and technical or product signals.	The current endpoint has returned HTTP 429 rate limits. Counts are not trusted until an approved access path is available.
Legacy FXV history	Imported from the corrected legacy Mention Log export.	Historical context, source URLs, dates, and recorded actions.	Only the locally exported rows are available to the hub today. The remaining live Sheet rows still need reconciliation before migration is complete.
Manual and transition sources	X saved searches, Google Alerts, F5Bot webhook or JSON import, Feedly, and optional web research.	Additional coverage outside the automated collector pool.	F5Bot requires webhook setup or JSON import; Google Alerts/search requires CSV or JSON import. Human review remains required before action.

What happens under the hood

The local hub uses a staged pipeline:

Raw state

hub/data/hub.db stores collection results and provenance. It is generated state and must not be hand-edited.

Rules and decisions

hub/registry/ defines brands, terms, and routing rules. Human-editable intelligence records live in the project-root items/ folder.

Reports and page

Reporting writes versioned weekly briefs and hub/dashboard/data/hub.json. The browser reads that JSON and renders the dashboard locally.

Reddit source-ID and URL deduplication plus collector provenance protect against counting the same source repeatedly or treating a failed source as a zero.
Brand matching, routing, type labels, and signal grouping are registry or rule driven. Optional LLM classification is not required for counts and is disabled by default.
The dashboard export contains the classified queue and a separate safe Brand mentions collection with source IDs, type, optional source metadata, matched terms, excerpts, collection method/status, availability state, and original links.
Some existing generated exports may still contain historical partner-risk fields from an earlier rule set. The current dashboard ignores those compatibility fields and does not display or filter them.
The static page has no build step. It must be served over HTTP because the browser fetches data/hub.json; opening index.html directly from file:// will not work reliably.

Local use and deployment

From the project root, serve the dashboard directory with a local HTTP server, then open the printed address:

cd hub
../hub/venv/bin/python -m http.server 8777 --directory dashboard

The static deployment path uses hub/dashboard as the output directory and no build command. The page and this readme use SHA-256 query strings for style.css, app.js, and readme.js. After changing one of those files, recalculate the hashes and update both HTML pages:

sha256sum hub/dashboard/style.css hub/dashboard/app.js hub/dashboard/readme.js

Cloudflare Pages and Cloudflare Access are off-site operational steps. The repository and dashboard contain internal findings and source evidence, so the hosted site must remain private and protected before it is shared.

First-time review checklist

Confirm the selected brand and the export-generated timestamp.
Read the intake banner, if present, and open Data provenance when any collector is unavailable or incomplete.
Read the Five-second view for the top available signal, its age and source, and the action-queue count before opening the raw mentions view.
Use the Brand selector and Signal controls to narrow the action queue. Remember that the metric tiles remain scoped to all findings for the selected brand.
For a high-risk or surprising finding, read the captured evidence and open the original source URL.
Check the finding signal and suggested action before deciding what to do.
Use Copy for Asana to prepare a handoff, or Mark taken care of for local browser housekeeping. Archive is not deletion.
Open Brand mentions to inspect raw source coverage. Use the keyword, date, platform, sentiment, intent, source-type, and subreddit filters, then open the original link and review availability, provenance, and known gaps before making a conclusion about market volume or silence.

Scope and guardrails

FXV-first operating scope, with the registered brands retained for later expansion.
Internal use only. The tool monitors and organises evidence; it does not publicly respond to mentions.
Coverage is directional, not exhaustive. Private communities, closed forums, and several social platforms are not automatically monitored.
Free-first collection remains the MVP posture. Paid services should be considered only when coverage or workload justifies them.
The current dashboard is a generated static snapshot. Automatic refresh and shared archive persistence require a separate, approved operating workflow.
The legacy Perplexity-to-Sheets workflow remains a fallback during the pilot and should not be retired until live history and collector coverage are reconciled.

How Network Intelligence works