{ "ok": true, "data": { "service": "ai-insights-for-humans", "title": "AI Insights for Humans", "purpose": "Public notebook for practical AI insight, plus standard PlatPhormNews discovery and MCP surfaces.", "baseUrl": "https://tips.platphormnews.com", "auth": { "scheme": "PLATPHORM_API_KEY", "acceptedHeaders": [ "Authorization: Bearer", "X-PlatPhorm-API-Key" ], "protectedActions": [ "POST /api/v1/reports" ] }, "routes": [ { "method": "GET", "path": "/", "status": "implemented", "public": true, "protected": false, "description": "Public AI insights notebook and reading paths." }, { "method": "GET", "path": "/api/health", "status": "implemented", "public": true, "protected": false, "description": "Platform health payload for the publication." }, { "method": "GET", "path": "/api/v1/health", "status": "implemented", "public": true, "protected": false, "description": "Versioned platform health payload." }, { "method": "GET", "path": "/api/docs", "status": "implemented", "public": true, "protected": false, "description": "Machine-readable API and route documentation." }, { "method": "GET", "path": "/api/v1/entries", "status": "implemented", "public": true, "protected": false, "description": "Read-only JSON index of notebook entries." }, { "method": "GET", "path": "/api/v1/entries/{id}", "status": "implemented", "public": true, "protected": false, "description": "Read-only JSON detail for one notebook entry." }, { "method": "GET", "path": "/api/v1/classroom", "status": "implemented", "public": true, "protected": false, "description": "Read-only classroom slides, teaching loop, and enhancement plan payload." }, { "method": "GET", "path": "/api/v1/integrations", "status": "implemented", "public": true, "protected": false, "description": "Read-only Dictionary and Notes integration map with public handoff boundaries." }, { "method": "GET", "path": "/api/v1/platform-literacy", "status": "implemented", "public": true, "protected": false, "description": "Read-only interactive tips distilled from PlatPhormNews root discovery and policy surfaces." }, { "method": "POST", "path": "/api/v1/reports", "status": "implemented", "public": false, "protected": true, "description": "Protected generation of a real notebook/platform summary report." }, { "method": "GET", "path": "/api/mcp", "status": "implemented", "public": true, "protected": false, "description": "MCP metadata and JSON-RPC usage information." }, { "method": "POST", "path": "/api/mcp", "status": "implemented", "public": true, "protected": false, "description": "JSON-RPC 2.0 MCP endpoint for real notebook tools, resources, and prompts." }, { "method": "GET", "path": "/openapi.yaml", "status": "implemented", "public": true, "protected": false, "description": "OpenAPI 3.1 contract for public and protected routes." }, { "method": "GET", "path": "/llms.txt", "status": "implemented", "public": true, "protected": false, "description": "Concise LLM-readable site summary." }, { "method": "GET", "path": "/llms-full.txt", "status": "implemented", "public": true, "protected": false, "description": "Complete LLM-readable notebook and platform summary." }, { "method": "GET", "path": "/llms-index.json", "status": "implemented", "public": true, "protected": false, "description": "Structured LLM index generated from real entries." }, { "method": "GET", "path": "/robots.txt", "status": "implemented", "public": true, "protected": false, "description": "Crawler policy and sitemap pointer." }, { "method": "GET", "path": "/sitemap.xml", "status": "implemented", "public": true, "protected": false, "description": "Canonical URL sitemap for the notebook." }, { "method": "GET", "path": "/sitemap-index.xml", "status": "implemented", "public": true, "protected": false, "description": "Sitemap index for platform crawlers." }, { "method": "GET", "path": "/rss.xml", "status": "implemented", "public": true, "protected": false, "description": "RSS feed generated from notebook entries." }, { "method": "GET", "path": "/feed.xml", "status": "implemented", "public": true, "protected": false, "description": "RSS-compatible feed alias." }, { "method": "GET", "path": "/atom.xml", "status": "implemented", "public": true, "protected": false, "description": "Atom feed generated from notebook entries." }, { "method": "GET", "path": "/manifest.webmanifest", "status": "implemented", "public": true, "protected": false, "description": "Web app manifest for install and preview surfaces." }, { "method": "GET", "path": "/.well-known/mcp.json", "status": "implemented", "public": true, "protected": false, "description": "MCP capability discovery manifest." }, { "method": "GET", "path": "/.well-known/agents.json", "status": "implemented", "public": true, "protected": false, "description": "Agent-facing route and policy discovery manifest." }, { "method": "GET", "path": "/.well-known/security.txt", "status": "implemented", "public": true, "protected": false, "description": "Security contact and policy file." }, { "method": "GET", "path": "/.well-known/trust.json", "status": "implemented", "public": true, "protected": false, "description": "Trust, auth, public/protected, and exposure policy." } ], "classroom": { "endpoint": "/api/v1/classroom", "slideCount": 6, "slides": [ { "id": "shared-terms", "title": "Teach the term before the trick", "entryIds": [ "term-first-learning", "dictionary-backed-verification" ], "dictionaryTerm": "retrieval relevance" }, { "id": "artifact-first", "title": "Put an artifact on screen", "entryIds": [ "classroom-teaching-loop", "receipts" ], "dictionaryTerm": "receipt" }, { "id": "dry-run-action", "title": "Preview action before authority", "entryIds": [ "tool-dry-run", "integration-contract-cards" ], "dictionaryTerm": "dry run" }, { "id": "abstention-branch", "title": "Make stopping a valid answer", "entryIds": [ "abstention-design", "schema-first-output" ], "dictionaryTerm": "abstention" }, { "id": "notes-to-glossary", "title": "Turn confusion into curriculum", "entryIds": [ "note-to-definition-pipeline", "misconception-map" ], "dictionaryTerm": "provenance" }, { "id": "self-quiz-transfer", "title": "End with recall, artifact, transfer", "entryIds": [ "self-quiz-cards", "teaching-with-aha-checkpoints" ], "dictionaryTerm": "prompt fixture" } ] }, "integrations": { "endpoint": "/api/v1/integrations", "services": [ { "id": "dictionary", "name": "PlatPhorm Dictionary", "url": "https://dictionary.platphormnews.com", "publicReads": [ "Approved public terms", "Dictionary search", "OpenAPI and llms discovery", "Term graph and provenance lookup", "Read-only MCP introspection" ], "protectedBoundary": "Moderation, import, admin, private submissions, audit logs, protected reports, model-assisted moderation, registry mutation, and destructive actions require PLATPHORM_API_KEY when enforcement is enabled." }, { "id": "notes", "name": "PlatPhorm Notes", "url": "https://notes.platphormnews.com", "publicReads": [ "App shell and discovery files", "Public templates", "Term detection previews", "Note analysis previews", "Workflow templates and integration status" ], "protectedBoundary": "No visitor key entry. Backend calls to Dictionary, Docs, OpenContent, Sheets, Phorm, SVG, and other PlatPhorm services require PLATPHORM_API_KEY server-side." } ], "dictionaryTermBridges": [ { "term": "retrieval relevance", "href": "https://dictionary.platphormnews.com/api/v1/search?q=retrieval%20relevance&limit=5", "entryIds": [ "retrieval-relevance", "glossary-before-demo" ], "classroomUse": "Define retrieval and relevance before students score chunks.", "notePrompt": "What retrieved chunk looked authoritative but did not answer the question?" }, { "term": "receipt", "href": "https://dictionary.platphormnews.com/api/v1/search?q=receipt&limit=5", "entryIds": [ "receipts", "dictionary-backed-verification" ], "classroomUse": "Treat a source, command, row, calculation, or assumption as a claim handle.", "notePrompt": "Which sentence in the answer needs a receipt before you would reuse it?" }, { "term": "dry run", "href": "https://dictionary.platphormnews.com/api/v1/search?q=dry%20run&limit=5", "entryIds": [ "tool-dry-run", "integration-contract-cards" ], "classroomUse": "Show the action plan before any tool mutates state.", "notePrompt": "What target ids, selectors, or rollback notes were missing from the tool preview?" }, { "term": "abstention", "href": "https://dictionary.platphormnews.com/api/v1/search?q=abstention&limit=5", "entryIds": [ "abstention-design", "confidence-buckets" ], "classroomUse": "Make unknown, partial, protected-required, and needs-review legitimate outcomes.", "notePrompt": "Where should the model have stopped instead of filling the answer?" }, { "term": "prompt fixture", "href": "https://dictionary.platphormnews.com/api/v1/search?q=prompt%20fixture&limit=5", "entryIds": [ "refusal-fixtures", "socratic-eval-prompts" ], "classroomUse": "Keep examples that should pass, refuse, redirect, or require more evidence.", "notePrompt": "Which prompt should become a fixture because it revealed a boundary?" }, { "term": "provenance", "href": "https://dictionary.platphormnews.com/api/v1/search?q=provenance&limit=5", "entryIds": [ "dictionary-provenance-check", "citation-triangulation" ], "classroomUse": "Ask where a term or fact came from before teaching from it.", "notePrompt": "What source or scope would change how you teach this definition?" } ], "notesWorkflowBridges": [ { "id": "observe-before-judging", "title": "Observe before judging", "notesWorkflow": "Students capture what they saw, expected, think it means, and need defined.", "dictionaryHandoff": "Repeated undefined phrases become Dictionary candidate definitions after review.", "notebookEntries": [ "notes-as-observation-log", "misconception-map" ], "classroomPrompt": "Write one observation from the demo that changed what you would inspect next." }, { "id": "term-detection-review", "title": "Term detection review", "notesWorkflow": "Students paste a short reflection and preview which technical terms need definitions.", "dictionaryHandoff": "Open Dictionary search for each high-confusion term before publishing a new definition.", "notebookEntries": [ "term-first-learning", "glossary-before-demo" ], "classroomPrompt": "Which term did the class use in two different ways?" }, { "id": "definition-staging", "title": "Definition staging", "notesWorkflow": "A rough learner explanation is staged as a draft, not treated as approved.", "dictionaryHandoff": "Human review decides whether the draft becomes a public Dictionary term.", "notebookEntries": [ "note-to-definition-pipeline", "human-approval-queue" ], "classroomPrompt": "What would you change before this definition becomes shared class language?" }, { "id": "self-quiz-recall", "title": "Self-quiz recall", "notesWorkflow": "Students create recall, artifact, and transfer questions from the day's entries.", "dictionaryHandoff": "Definitions become answer keys only after the concept scope is clear.", "notebookEntries": [ "self-quiz-cards", "concept-ladder-lesson" ], "classroomPrompt": "What is the transfer question that proves you can use this idea elsewhere?" } ] }, "platformLiteracy": { "endpoint": "/api/v1/platform-literacy", "tipCount": 10, "rampLevels": [ { "id": "level-1", "label": "First-time learner", "learnerCan": "Explain the difference between public read, protected action, and private data.", "practice": "Sort routes from robots.txt into safe-to-read and stop-sign groups." }, { "id": "level-2", "label": "Careful operator", "learnerCan": "Use sitemaps, RSS, llms files, OpenAPI, and JSON-LD to inspect a site without guessing.", "practice": "Build a source-backed checklist for one public surface." }, { "id": "level-3", "label": "Agent workflow designer", "learnerCan": "Read MCP tools/resources/prompts and design a public-safe workflow with explicit stop states.", "practice": "Write a dry-run plan for a read-only MCP inspection." }, { "id": "level-4", "label": "Ethical AI security operator", "learnerCan": "Audit public automation behavior while respecting trust policy, robots policy, auth boundaries, trace redaction, and no-secret rules.", "practice": "Produce a report that says what was inspected, what was skipped, why it was skipped, and what evidence supports each conclusion." } ], "tips": [ { "id": "public-dmz", "title": "Public DMZ means safe read-only front door", "surface": "Root MCP manifest and trust policy", "sourceUrl": "https://platphormnews.com/.well-known/mcp.json", "aha": "Public does not mean powerful. Public means safely inspectable.", "safeBoundary": "Do not test destructive, private, protected, credential, admin, or mutation paths without explicit authorization." }, { "id": "network-graph", "title": "The network graph is the map of the city", "surface": "GET /api/network/graph", "sourceUrl": "https://platphormnews.com/api/network/graph", "aha": "Discovery is not guessing URLs. Discovery is reading the map the platform publishes.", "safeBoundary": "Stay inside trusted domains and published discovery routes. Do not crawl arbitrary user-provided URLs." }, { "id": "robots-llms", "title": "robots.txt and llms files teach crawler manners", "surface": "robots.txt, llms.txt, llms-full.txt, llms-index.json", "sourceUrl": "https://platphormnews.com/robots.txt", "aha": "The safest crawler is the one that reads instructions before touching the site.", "safeBoundary": "Never put tokens, keys, or secrets into URLs, traces, screenshots, feeds, or public artifacts." }, { "id": "mcp-toolbox", "title": "MCP is a toolbox, not a permission slip", "surface": ".well-known/mcp.json and /api/mcp", "sourceUrl": "https://platphormnews.com/.well-known/mcp.json", "aha": "Tool discovery comes before tool execution.", "safeBoundary": "Do not call sync, refresh, ingestion, reporting, or policy-update tools unless authorized and key-gated." }, { "id": "openapi-contract", "title": "OpenAPI is the menu with ingredients listed", "surface": "/api/docs and /openapi.yaml", "sourceUrl": "https://platphormnews.com/api/docs", "aha": "Guessing endpoint behavior is amateur hour; reading the contract is how experts move fast safely.", "safeBoundary": "Use read-only endpoints for practice. Treat POST, sync, ingestion, and reporting routes as protected unless explicitly documented otherwise." }, { "id": "jsonld-identity", "title": "JSON-LD is the site's ID card", "surface": "Homepage JSON-LD", "sourceUrl": "https://platphormnews.com", "aha": "A page can speak to humans in HTML and to machines in JSON-LD at the same time.", "safeBoundary": "Do not treat structured data as secret or authority by itself; verify with the corresponding public route." }, { "id": "rss-sitemap", "title": "RSS tells what changed; sitemaps tell what exists", "surface": "RSS, Atom, sitemap, sitemap index", "sourceUrl": "https://platphormnews.com/rss.xml", "aha": "The public site tells you where to look if you start with the sitemap instead of guessing.", "safeBoundary": "Use published sitemaps instead of brute-force path discovery." }, { "id": "agent-policy", "title": "Agent policy tells bots how to behave", "surface": ".well-known/agent-policy.json", "sourceUrl": "https://platphormnews.com/.well-known/agent-policy.json", "aha": "A well-behaved agent is safer because it knows where not to go.", "safeBoundary": "No secrets, cookies, raw IP addresses, raw JA4 digests, private traces, or private audit details in public reports." }, { "id": "trace-context", "title": "Trace headers are the breadcrumb trail", "surface": "MCP manifest and agent policy trace fields", "sourceUrl": "https://platphormnews.com/.well-known/agent-policy.json", "aha": "Observability is useful only when it does not leak the thing it observes.", "safeBoundary": "Never put authorization, API keys, cookies, session tokens, or raw private payloads into trace state or baggage." }, { "id": "source-backed-status", "title": "Status should say how it knows", "surface": "Network graph and compliance payloads", "sourceUrl": "https://platphormnews.com/api/network/graph", "aha": "Green without evidence is decoration. Green with source and time is operational signal.", "safeBoundary": "Do not convert degraded or declared-only status into a claim of live success." } ] }, "enhancementPlan": [ { "id": "phase-1-content-depth", "phase": "Phase 1", "title": "Content depth and curriculum structure", "outcome": "The site becomes a richer teaching notebook with entries, playbooks, classroom slides, AHA checkpoints, and self-quiz material.", "scope": [ "Add classroom, Dictionary, Notes, integration, and governance entries.", "Expand reading paths around classroom teaching and cross-site workflows.", "Expose classroom slides through API, MCP, and llms surfaces." ], "tests": [ "Entry inventory and insight coverage tests.", "Reading path reference tests.", "Classroom content depth tests." ], "status": "implemented" }, { "id": "phase-2-cross-site-handoffs", "phase": "Phase 1", "title": "Dictionary and Notes public handoffs", "outcome": "The notebook links to real Dictionary and Notes public surfaces while clearly preserving protected boundaries.", "scope": [ "Add integration cards with purpose, public reads, protected boundary, and handoff links.", "Add Dictionary term bridges and Notes workflow bridges.", "Publish integration payloads through API docs, llms index, MCP, and protected report output." ], "tests": [ "Integration payload unit tests.", "E2E checks for Dictionary and Notes links.", "No banned platform key names in public surfaces." ], "status": "implemented" }, { "id": "phase-3-classroom-mode", "phase": "Phase 1", "title": "Full-screen classroom mode", "outcome": "Teachers can use the notebook as a focused, full-screen teaching surface without losing links to entries, Dictionary, or Notes.", "scope": [ "Add a classroom mode client component with slide controls.", "Support browser fullscreen when available and a full-viewport overlay fallback.", "Keep slide text compact, readable, and linked to real content." ], "tests": [ "Playwright classroom overlay test.", "Responsive smoke check on desktop and mobile viewport sizes.", "Keyboard/next/back navigation check." ], "status": "implemented" }, { "id": "phase-4-e2e-and-contract-suite", "phase": "Phase 1", "title": "Complete local test suite", "outcome": "Unit, platform contract, API, discovery, and browser e2e checks run from repo scripts.", "scope": [ "Add Playwright configuration and e2e scripts.", "Test homepage, classroom mode, integrations, protected report rejection, and discovery parity.", "Keep existing TypeScript, lint, unit, and build gates." ], "tests": [ "pnpm test", "pnpm test:e2e", "pnpm build" ], "status": "implemented" }, { "id": "phase-5-live-platform-verification", "phase": "Next", "title": "Live alias and network verification", "outcome": "The deployed https://tips.platphormnews.com alias is verified against BrowserOps/Evals style route, discovery, and UI checks.", "scope": [ "Run live read-only route standard checks against tips.platphormnews.com.", "Compare llms, OpenAPI, RSS, sitemap, MCP, and API docs with local output.", "Capture screenshots for classroom mode on desktop and mobile." ], "tests": [ "RUN_LIVE_INTEGRATION_TESTS=true read-only smoke.", "BrowserOps journey after production deploy.", "No secret leakage and protected action rejection checks." ], "status": "next" }, { "id": "phase-6-protected-workflow-bridge", "phase": "Future", "title": "Protected Dictionary and Notes workflow bridge", "outcome": "If needed later, this site can stage protected Dictionary/Notes workflow requests server-side with PLATPHORM_API_KEY.", "scope": [ "Add protected server routes only when a real write workflow is approved.", "Require PLATPHORM_API_KEY for any submission, staging, ingestion, report, or sync action.", "Return protected_required and honest degraded states when the key or owning service is unavailable." ], "tests": [ "Auth rejection without key.", "Protected success only with configured key.", "Trace and redaction tests for cross-site requests." ], "status": "future" } ], "insightLabModules": [ { "id": "logprobs", "entryId": "logprobs", "title": "The sentence is fluent. The token path may not be.", "operatorMove": "Read names, dates, citations, and refusal-boundary words with the token margin visible." }, { "id": "receipts", "entryId": "receipts", "title": "Claims become safer when each one has a handle.", "operatorMove": "Require one receipt per important claim before accepting a summary, diagnosis, or recommendation." }, { "id": "counter-evidence", "entryId": "counter-evidence", "title": "Confidence is cheaper before the answer gets defended.", "operatorMove": "Do not ask for confidence until the model has named what could falsify the answer." }, { "id": "temperature", "entryId": "temperature", "title": "The creativity dial changes spread, not truth.", "operatorMove": "Use low temperature when correctness has one target; raise it when diversity is the target." }, { "id": "context-position", "entryId": "context-rot", "title": "The middle can be technically present and practically lost.", "operatorMove": "Place the task contract first and repeat the highest-risk constraint at the end." }, { "id": "attention-routing", "entryId": "attention-viz", "title": "Some heads act like tiny routing specialists.", "operatorMove": "Use attention maps to form hypotheses, then perturb the prompt or run a causal check." } ], "fieldGuide": { "playbooks": [ { "id": "hallucination-triage", "title": "Hallucination triage", "outcome": "A reviewer can identify which claims are supported, which claims need receipts, and which answer parts should be withheld.", "entryIds": [ "logprobs", "retrieval-relevance", "receipts", "citation-triangulation", "confidence-buckets" ], "steps": [ "Locate fragile spans", "Separate retrieval from generation", "Attach receipts", "Decide the confidence bucket" ] }, { "id": "prompt-change-control", "title": "Prompt change control", "outcome": "The prompt change ships with a semantic diff, targeted fixtures, and a clear before/during/after eval record.", "entryIds": [ "short-system-prompts", "semantic-diff", "eval-sandwich", "red-team-mutants", "refusal-fixtures" ], "steps": [ "Shrink the contract", "Diff the meaning", "Run the eval sandwich", "Mutate the boundary" ] }, { "id": "agent-action-gate", "title": "Agent action gate", "outcome": "Every action moves through preview, inspect, authorize, execute, and verify without hiding protected states.", "entryIds": [ "tool-dry-run", "abstention-design", "latency-budget", "model-routing", "memory-hygiene" ], "steps": [ "Preview the action", "Respect blocked states", "Spend checks by risk", "Verify after execution" ] } ], "failureCaseStudies": [ { "id": "source-shaped-hallucination", "title": "The source-shaped hallucination", "aha": "A citation beside a sentence is not the same thing as support under the sentence.", "entryIds": [ "receipts", "citation-triangulation", "logprobs" ] }, { "id": "middle-context-loss", "title": "The buried constraint", "aha": "Presence in context is not the same thing as usable salience.", "entryIds": [ "context-rot", "retrieval-relevance", "schema-first-output" ] }, { "id": "tool-call-overreach", "title": "The tool call that did too much", "aha": "Tool safety starts before execution, not after the audit log catches damage.", "entryIds": [ "tool-dry-run", "abstention-design", "latency-budget" ] }, { "id": "prompt-edit-regression", "title": "The helpful prompt edit that moved the boundary", "aha": "Style examples can become behavioral instructions if you do not test the boundary.", "entryIds": [ "semantic-diff", "refusal-fixtures", "red-team-mutants" ] } ], "ahaLadder": [ { "id": "answer-to-signal", "title": "From answer to signal", "operatorQuestion": "Where would this answer break first?" }, { "id": "prompt-to-contract", "title": "From prompt to contract", "operatorQuestion": "What is the model allowed to leave blank?" }, { "id": "tool-to-action", "title": "From tool to action", "operatorQuestion": "What would stop this action before it runs?" }, { "id": "confidence-to-decision", "title": "From confidence to decision", "operatorQuestion": "What does this confidence label change?" } ] }, "feeds": [ "/rss.xml", "/feed.xml", "/atom.xml" ], "discovery": [ "/openapi.yaml", "/llms.txt", "/llms-full.txt", "/llms-index.json", "/.well-known/trust.json", "/.well-known/agents.json", "/.well-known/mcp.json" ] } }