TATERpedia Ratings & Suggested Articles

Adds ServiceNow-style KB quality signals + suggested-articles surfacing on top of the existing TATERpedia wiki (§12bk).

For end users: rating a wiki page

Any TATER user (Auditor+) can rate a TATERpedia wiki page from the page itself:

1. Open any TATERpedia article (from Reports & Policies → Documentation, from a suggested-articles surface on a control/task/incident, or via direct slug URL).
2. Look for the ⭐ Rate this page control near the top of the article (just below the title and tags row).
3. Click 1-5 stars to set your rating. You can change your rating any time by clicking a different star count - re-rating overwrites your previous score.
4. Optionally add a short comment (≤1000 chars) explaining what worked or what didn't. Comments are visible to anyone viewing the page and feed into the "Recent comments" panel on the right rail.
5. Your rating updates the aggregate immediately (page-level avgRating + ratingCount) and the count distribution (how many 1s, 2s, etc.).

Why it matters: aggregate ratings drive the ranking in suggest_wiki_pages - high-rated pages surface higher when an AI agent or a search query is looking for relevant content. A low rating with a substantive comment tells the next author what to fix.

View counts are tracked automatically - you don't need to do anything. Every time you open a wiki page, a fire-and-forget counter increments. The "👁 N views" badge on suggested articles reflects this.

End users see the same UI on every wiki page across all four sister apps (Security, Ops, Manage, My TATER). Rating is org-scoped (your rating lives in your home tenant's partition) but aggregates are cross-org since the wiki itself is shared.

Storage model

• WikiPages (existing, SHARED_TENANT partition) - pages remain cross-org shared.
• WikiRatings (new, partitioned by user's home tenantId) - keeps per-user ratings in each org's partition. Cross-partition query on read for aggregation.
• viewCount, lastViewedAt (new fields on WikiPage itself) - incremented by fire-and-forget POST. Best-effort; failure non-fatal.

This split keeps the wiki itself cross-org while keeping rating activity per-org auditable. Each user can rate each page once; re-rating overwrites.

Rating endpoints

• POST /api/wiki/pages/:slug/rate (Auditor+) - body: rating (1-5), comment (≤1000 chars). Upserts user's rating.
• GET /api/wiki/pages/:slug/ratings (Viewer+) - aggregate count, average, distribution (1-5), top 10 recent comments (must have text), the current user's own rating.

Aggregation runs a cross-partition query (forceQueryPlan: true) on WikiRatings filtered by pageId. Performance: fine at sub-10k ratings per page. If scaling beyond that becomes an issue, cache aggregate on the page doc.

View tracking

POST /api/wiki/pages/:slug/view (Viewer+) - fire-and-forget; returns 200 immediately, increments viewCount on the page in a setImmediate. Non-fatal on failure. Wire into the wiki page render so every view counts; rate-limited by general tier so abuse is bounded.

Suggested articles

GET /api/wiki/suggest?q=&tag=&control_id=&limit=N (Viewer+) returns the top N relevant pages. Scoring:

• title match: +4 per token
• tag match: +3 per token
• summary match: +2 per token
• body match: +1 per token

Filters before scoring:

• control_id - matches scope.entityId, body content containing the id, or tags equal to the id
• tag - exact tag match (case-insensitive)
• Archived pages always excluded

If no q provided, sorts by viewCount desc → updatedAt desc. Default limit 5, max 20.

Wiring suggested articles into tickets

The intended pattern is to surface suggested articles on entity detail panels:

• On a Control detail page: call /api/wiki/suggest?control_id={controlId}
• On a Change Request page: call /api/wiki/suggest?q={controlId + change description keywords}
• On a Major Incident: call /api/wiki/suggest?tag=runbook&q={incident symptoms}
• On a Tasker task: call /api/wiki/suggest?q={category + title keywords}

Render up to 5 suggestions with title + summary + view count + avg rating. Clicking a suggestion opens the wiki page and triggers the view counter.

MCP tools (2, HTTP + stdio parity)

• rate_wiki_page (Auditor+) - rate 1-5 with optional comment
• suggest_wiki_pages (Viewer+) - context-aware search; the high-value one for agent ticket-handling

Agent pattern: "before authoring, search"

The MCP INSTRUCTIONS encourage agents to call suggest_wiki_pages as the FIRST step when starting work on a control, change request, or major incident. Prior wiki content is higher-signal than re-deriving from scratch. After consulting, optionally rate_wiki_page to flag quality (drives future suggestion ranking).

Pitfalls

• Cross-tenant aggregation on read. WikiRatings partitioned by user's tenantId; aggregating ratings for a shared page requires forceQueryPlan: true cross-partition query (per §12av). Don't try to filter by partition key.
• viewCount write is best-effort, NOT transactional. Concurrent views may lose increments (last-writer-wins on the upsert). Acceptable trade-off - view counts are directional signals, not financial transactions.
• Suggested articles search is keyword-only. No semantic / embedding search yet. For very ambiguous queries, falls back to viewCount + recency. Consider this when authoring page titles + summaries: make them keyword-rich.
• avgRating + ratingCount are NOT denormalized to the page document. Compute on demand via the ratings endpoint. If you need them in search results, add a periodic aggregation job.

Related guides

• Comments, mentions, notifications - broader collaboration surface
• AI Compliance Analyst - agents that consume the wiki via MCP