Status: designed 2026-11-08, not built. Brainstormed with Jake; nothing is implemented. This page is the recovery point: a builder should be able to plan Project 1 from it without further conversation. Projects 2–4 are sketched and get their own short design pass when they come up, because real engagement data will sharpen them. Decision record: SA-17 on SimpleAgilityDecisionLog.
Search data (ContentIntelligenceDesign) tells us whether readers arrive. This design adds whether they got something once they were there — how long they actually read and what they did on the page — and turns that into three things: targeted content improvements, an honest view of what advertising costs readers, and a measured path from reader to signed-in contributor.
It is written for the whole Simple Agility stack: the collection pattern (Umami in the back-office suite, same-origin tracker, event vocabulary, batch read-back into product tables) applies to any product with readers, and Pressroom already follows most of it. Wikantik is the first product to close a content-improvement loop on top of it.
The question Jake wants answered for a page: did readers spend real time on it, and did they act on it — copy code, follow a link onward, interact with a diagram, sign in. Two pages with the same search traffic can be one that holds readers for six minutes with forty code copies and one that loses them in forty seconds. Those deserve different work:
Success is a backlog that can say "this page gets 300 visits a month, readers leave after 40 seconds, nobody copies its code, its summary is 22 characters and it was last verified 14 months ago" — one actionable sentence that only the product can produce, because half the facts live in the wiki — followed, 28 days after the rework, by a measured verdict on whether readers stayed longer and did more.
Traffic reality (recorded so nobody over-reads early numbers). As of 2026-11-08 the site-level traffic gate in Content Intelligence reads 426 against a required 5,000 (28-day impressions), and the August baseline was ~10 search clicks per 28 days. Per-page engagement numbers will be thin for a long time. That is why collection starts now (history cannot be created retroactively and collection is cheap) while the rules that act on it stay dormant behind gates (see Project 2).
| # | Decision |
|---|---|
| D1 | Umami does all reader-behaviour measurement: reading time, on-page actions, the browser half of the sign-in funnel. No in-house browser collector. |
| D2 | This supersedes the in-wiki browser collector specified in the Content Intelligence spec (§7.6 "The browser collector", its telemetry_event/telemetry_page_daily tables, and the Phase 3 gate of ≥1,000 clicks/28 days). Its useful ideas are kept (below). |
| D3 | All traffic counts. Signed-in users, editors and Jake's own visits are not excluded or split out. No extra complexity there. |
| D4 | Ads stay even when they cost reading time; the response to a measured cost is to reduce ad frequency, not remove ads. |
| D5 | A consent banner is accepted as a necessity of AdSense, but it is not wanted: third-party surface is minimised — Umami for everything it can do, Google ads the only third party, because ads are the only thing that pays. |
| D6 | Signing in through SSO is the prized conversion — it is the path to editing, and a reader becoming an editor is the best outcome. There are no features driving it today; measure the existing trickle first. |
| D7 | A human stays in the loop. The backlog suggests; Jake hands the page to the content agent. No autonomous rework. |
| D8 | Recorded in the wiki as cross-cutting architecture, not only as a repository spec. |
AnalyticsSyncTask does. jakemon is not in this path. (An earlier draft of the brainstorm routed this
through jakemon and /admin/insights/ingest; SA-16 rules that out.)verified_at, cluster and Knowledge Graph coverage still happens inside Wikantik, over the read-back rollup.Goals
Non-goals (now)
grafana_ro view) cover live
looking; Wikantik keeps only what feeds its decisions.Anti-goals — failure even if it technically works
localStorage used for measurement.flowchart LR
Reader["Reader's browser"] -->|"GET /analytics/script.js<br/>POST /analytics/api/send<br/>(same origin)"| Product["Product origin<br/>(Wikantik, Pressroom)"]
Product -->|"LAN proxy"| Umami["Umami<br/>(back-office suite)"]
Umami --- UDB[("Umami PostgreSQL<br/>raw events, 730-day retention")]
Product -->|"batch read, own account<br/>(SA-16)"| Umami
Product --- PT[("Product table<br/>per-page daily rollup (SA-1)")]
Grafana["jakemon Grafana"] -.->|"grafana_ro view"| UDB
Conventions every product follows:
/analytics/script.js and /analytics/api/send on the product's own host, proxied over
the LAN to the suite. CSP stays script-src 'self' / connect-src 'self'; ad blockers that block analytics
hosts don't see a third-party host. The real client IP must reach Umami (Cloudflare's CF-Connecting-IP /
X-Forwarded-For), or geography collapses to the proxy's address.canonical_id) so numbers survive renames. Products declare their vocabulary
on their design page (Wikantik's is below).| # | Project | Depends on | State |
|---|---|---|---|
| 1 | Reader instrumentation + engagement read-back (Wikantik) | Umami reachable from the wiki; a suite-owned engagement view (cross-repo) | Specified below — ready to plan |
| 2 | Engagement opportunity rules + outcome measures (Content Intelligence) | 1, plus accumulated data | Sketched |
| 3 | Sign-in conversion funnel | 1 | Sketched |
| 4 | AdSense with geo-scoped consent, frequency dial, ad-free holdout | 1 (for before/after reading data) | Sketched |
Ads come last on purpose: a clean pre-ads reading-time baseline is what makes their cost measurable.
/wiki/* pages — from the same-origin path. Not on /admin/* or editor routes.ini/wikantik.properties (declared first, per ConfigSurfaceDriftTest): an enable flag
defaulting off, the Umami website id, the same-origin script path, and the read-back connection settings and
credentials (secrets blank in the file, supplied by environment). A dev/test instance with the flag off emits
nothing./analytics/* reaches the suite is the builder's call, with these constraints: no CSP change; real client
IP preserved; the wiki's own request threads never wait on Umami. Two candidates: a path rule on the Cloudflare
tunnel ingress for wiki.wikantik.com (no Wikantik code, but the suite's Caddy must accept that host on
/analytics/*), or a thin streaming proxy in Wikantik's HTTP layer (more code, but self-contained, testable, and
indifferent to where Umami runs). The suite spec's diagram already anticipates "Wikantik → future LAN proxy".| Event | Fires when | Properties |
|---|---|---|
| (page view) | Page load and each SPA route change — Umami native | url path (native) |
page-exit | Tab hidden (visibilitychange), pagehide, or SPA route change away | canonical_id, cluster, active_s, max_scroll_pct |
code-copy | A code block's copy control is used | canonical_id, lang |
wikilink-click | An internal wiki link is followed | canonical_id, target (target page's canonical id or slug) |
outbound-click | An external link is followed | canonical_id, dest (host only) |
diagram-interact | A rendered diagram or math block is clicked/expanded | canonical_id, kind (mermaid | plantuml | math) |
toc-click | Table-of-contents entry used | canonical_id |
sign-in-click | "Sign in" activated | canonical_id (empty off-page) |
Rules: cluster is the page's primary cluster. Property values come from page metadata or a fixed set, never
from free page text. Keep within Umami's event-data limits for the pinned version (builder verifies counts/lengths).
Active time counts only while the page is visible and the reader has interacted (scroll, key, pointer) within the
last 30 seconds — 30 s is my call; tune if data says otherwise. page-exit fires once per page visit; a page visit
that ends without it (crash, killed tab) is an accepted loss. Delivery on pagehide is the known fragile point —
the builder verifies the pinned tracker's send survives page unload (keepalive/beacon) and, if not, sends that one
event with a beacon to the same endpoint.
A scheduled task (nightly is enough; my call) reads the previous few days from Umami with Wikantik's own credentials and replaces rows in a new product table, one row per (day, site, page):
reader_engagement_daily — day, site host, canonical_id, views, visitors, page exits, median and p90 active
seconds, exits reaching ≥75% scroll, and one count column per action event. Typed columns, no JSON blob (same
reasoning as the superseded CI design: every new event goes through a schema review). Permanent rollup, small.
Needs a numbered migration (DDL only).
Page views arrive keyed by URL path; map path → canonical_id through the page index (slug resolution; renamed
pages keep their canonical_id). Events already carry canonical_id.
"Day" is the UTC calendar day (my call): it keeps the replace window simple and matches how the Content Intelligence fact store stamps dates.
Scope of sites (my call): one Umami website per Wikantik instance; for production that is wiki.wikantik.com
only. The site-host column exists so a second Wikantik instance (expected per the stack hub) needs no schema change.
The static marketing site www.wikantik.com is out of scope.
Re-reading a day is idempotent (replace, not add), so late-arriving events are absorbed by re-reading the last few days each run.
Where the median/p90 come from (my call). Umami's event-data API reports sums, averages and distinct values,
not percentiles, and the design wants medians (reading time is heavily skewed, so a mean lies). So Project 1
includes a cross-repo item for the back-office suite: a suite-owned read-only view (analytics_engagement,
beside its existing analytics_traffic) that returns, per (UTC day, website, canonical_id): exits, median and p90
active_s (percentile_cont), exits with max_scroll_pct ≥ 75, and per-event counts. The suite grants it to a
read-only role for Wikantik; SA-15's client contract permits read-only grants on suite-owned views. Wikantik never
touches website_event directly. Page-view and visitor counts can come from the same view or from the API —
builder's choice. If the suite item is late, the read-back ships with views/counts first and fills the time
columns when the view lands; it does not fall back to means under a median's name.
Failure handling: timeouts on every call; a failed run logs a warning with context, increments a metric, and leaves the previous rollups in place.
Engagement columns per page on the existing Content Intelligence admin panel (/admin/insights), and the same facts
available to agents through the existing admin MCP read path (exact tool shape left to the builder, following the
existing list_content_opportunities evidence style). Nothing acts on the data yet.
PrivacyPolicy (and TermsOfService if it mentions analytics) gains a plain
statement: cookieless, self-hosted analytics; what is measured (pages, reading time, the actions above); no personal
profile; retention 730 days for raw events, permanent per-page daily totals. This is a content operation on
production through the admin MCP (prod is authoritative for content), made in the same release that switches the
tracker on; mirror it into docs/wikantik-pages/ afterwards.
page-exit with plausible active_s and
max_scroll_pct in Umami's Events view for the wiki's website; each action event fires once per action.reader_engagement_daily for the previous day, and re-running it changes nothing./admin/insights for pages with data.PostgresTestDb, the Umami client against a stub, and
frontend event emission covered in vitest.wikantik-insights: engaged → refine (above-site-median active time and actions per
view) and bouncing → rework (short active time, low 75%-reach, no actions). Both sized by traffic so effort goes
where readers are. Suggested actions name concrete affordances: diagrams, worked examples, copyable snippets,
onward links.EffectEvaluator: median active time, 75%-reach rate and actions per view, with the
same difference-in-differences adjustment against the site trend and the same honest "insufficient data" verdict.
A rework is then judged on "did readers stay longer and do more", not only on search CTR.sign-in-click (browser, Umami, carries the starting page's canonical_id).Credit goes to the starting page, giving a "pages that make contributors" list distinct from "pages that hold attention". Open for its own pass: where the server-side steps land (product table vs Umami server-side event), and how the return-to page is carried through the SSO round-trip.
page-exit
(an ads property) so reading time and actions can be compared with and without ads. Assignment must not need a
cookie (per-page-view random is enough for page-level comparison).ads.txt on both domains (ca-pub-5083997587716933), the marketing site's account meta tag.| Data | Lives in | Why |
|---|---|---|
| Raw page views and events | Umami (back-office suite) | Observation; the suite owns retention |
| Per-page daily engagement rollup | Wikantik reader_engagement_daily | Functional input to opportunity ranking and effect measurement |
| Sign-in funnel server steps | Wikantik (Project 3 decides table) | Functional input to ranking "pages that make contributors" |
| Dashboards over raw traffic | Grafana via suite-owned grafana_ro view | Observation |
| AdSense revenue | jakemon feed (Project 4) | Third-party source (SA-16) |
The /analytics/* proxy mechanism (within the constraints above); the Umami API calls and paging; the exact rollup
column names; the scheduler cadence beyond "at least nightly"; the admin-panel layout; how the frontend attaches
event handlers (delegated listeners vs per-component); the website registration mechanism (configured id, or a
Pressroom-style reconcile against Umami's API).
docker-compose.backoffice.yml in the Pressroom repo), with the move to the suite on docker2 specified but not
confirmed done; there is no Wikantik website or account in it yet, and no dev/test Umami for Wikantik's ITs.
Project 1's code works against Umami wherever it runs (the target is configuration), so build and test against a
stub, and make "Umami reachable from docker1 with a wikantik account, website and the engagement view" the
gating milestone for production verification. An in-wiki proxy works against either location; a tunnel path rule
depends on the suite's Caddy accepting the wiki host — weigh that when choosing.get_briefing(clusters=["wikantik-development"], prompt="reader engagement Project 1")
and plan Project 1.cta-click)