{ "ok": true, "data": { "service": "ai-insights-for-humans", "version": "0.6.0", "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/focus-mode", "status": "implemented", "public": true, "protected": false, "description": "Read-only focus frames and practice loop 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": "GET", "path": "/api/v1/research-trends", "status": "implemented", "public": true, "protected": false, "description": "Read-only source-backed AI research trends, public-safe demonstrations, and cross-model prompt contracts." }, { "method": "GET", "path": "/api/v1/operator-patterns", "status": "implemented", "public": true, "protected": false, "description": "Read-only operator strengths, drag patterns, repair loops, and reusable workflow prompts." }, { "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": "/sitemap-full.xml", "status": "implemented", "public": true, "protected": false, "description": "Complete sitemap covering product and machine-readable routes." }, { "method": "GET", "path": "/humans.txt", "status": "implemented", "public": true, "protected": false, "description": "Human-readable ownership, purpose, attribution, and contact details." }, { "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." } ], "focusMode": { "endpoint": "/api/v1/focus-mode", "frameCount": 6, "frames": [ { "id": "shared-terms", "title": "Name the term before the trick", "entryIds": [ "plain-then-precise", "term-first-fieldwork", "dictionary-backed-verification" ], "dictionaryTerm": "retrieval relevance" }, { "id": "artifact-first", "title": "Put an artifact on screen", "entryIds": [ "artifact-questions", "inspect-one-claim", "explain-inspect-repair-loop", "receipts" ], "dictionaryTerm": "receipt" }, { "id": "dry-run-action", "title": "Preview action before authority", "entryIds": [ "first-safe-agent-plan", "public-private-sorting", "tool-dry-run", "integration-contract-cards" ], "dictionaryTerm": "dry run" }, { "id": "abstention-branch", "title": "Make stopping a valid answer", "entryIds": [ "readiness-red-yellow-green", "abstention-design", "schema-first-output" ], "dictionaryTerm": "abstention" }, { "id": "notes-to-glossary", "title": "Turn repeated confusion into better tools", "entryIds": [ "definition-vs-proof", "note-to-definition-pipeline", "misconception-map" ], "dictionaryTerm": "provenance" }, { "id": "self-quiz-transfer", "title": "End with recall, artifact, transfer", "entryIds": [ "aha-from-mistake", "self-quiz-cards", "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" ], "fieldUse": "Define retrieval and relevance before scoring 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" ], "fieldUse": "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" ], "fieldUse": "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" ], "fieldUse": "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" ], "fieldUse": "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" ], "fieldUse": "Ask where a term or fact came from before relying on it.", "notePrompt": "What source or scope would change how you teach this definition?" } ], "notesWorkflowBridges": [ { "id": "observe-before-judging", "title": "Observe before judging", "notesWorkflow": "Readers 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" ], "fieldPrompt": "Write one observation from the demo that changed what you would inspect next." }, { "id": "term-detection-review", "title": "Term detection review", "notesWorkflow": "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-fieldwork", "glossary-before-demo" ], "fieldPrompt": "Which term appeared with two different meanings?" }, { "id": "definition-staging", "title": "Definition staging", "notesWorkflow": "A rough 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" ], "fieldPrompt": "What would you change before this definition becomes shared technical language?" }, { "id": "self-quiz-recall", "title": "Self-quiz recall", "notesWorkflow": "Create recall, artifact, and transfer questions from the current entries.", "dictionaryHandoff": "Definitions become answer keys only after the concept scope is clear.", "notebookEntries": [ "self-quiz-cards", "concept-ladder" ], "fieldPrompt": "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-pass reader", "readerCan": "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", "readerCan": "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", "readerCan": "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": "Real-world operator", "readerCan": "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." } ] }, "researchTrends": { "endpoint": "/api/v1/research-trends", "trendCount": 10, "demoCount": 5, "promptPatternCount": 5, "sourceCount": 19, "roadmapItemCount": 6, "demos": [ { "id": "loops", "title": "Loops", "subtitle": "Observe, decide, act, check, reflect", "entryIds": [ "agent-loops", "explain-inspect-repair-loop", "first-safe-agent-plan" ] }, { "id": "openclaw", "title": "OpenClaw", "subtitle": "Capability discovery before agent authority", "entryIds": [ "openclaw-toolchain-dry-run", "tool-protocols-over-adapters", "tool-dry-run" ] }, { "id": "webhooks", "title": "Webhooks", "subtitle": "Event, signature, delivery, retry, replay", "entryIds": [ "webhook-delivery-lifecycle", "receipts", "public-private-sorting" ] }, { "id": "cross-model-prompts", "title": "Premier model prompts", "subtitle": "One contract, many model families", "entryIds": [ "cross-model-prompt-contract", "schema-first-output", "semantic-diff" ] }, { "id": "ai-mind", "title": "AI mind microscope", "subtitle": "Signals, circuits, traces, receipts", "entryIds": [ "mind-microscope", "circuit-tracing-is-partial", "logprobs" ] } ], "promptPatterns": [ { "id": "evidence-first-answer", "title": "Evidence-first answer", "worksAcross": [ "OpenAI GPT/reasoning models", "Anthropic Claude", "Google Gemini" ] }, { "id": "tool-dry-run-contract", "title": "Tool dry-run contract", "worksAcross": [ "OpenAI agents", "Claude tool use", "Gemini function calling" ] }, { "id": "cross-model-comparison", "title": "Cross-model comparison", "worksAcross": [ "OpenAI", "Anthropic", "Google", "open-weight reasoning models" ] }, { "id": "long-context-source-map", "title": "Long-context source map", "worksAcross": [ "Long-context GPT models", "Claude", "Gemini" ] }, { "id": "aha-check", "title": "AHA check", "worksAcross": [ "ChatGPT", "Claude", "Gemini", "local assistants" ] } ] }, "operatorPatterns": { "endpoint": "/api/v1/operator-patterns", "strengthCount": 6, "dragPatternCount": 6, "repairStepCount": 5, "promptCount": 3, "strengths": [ { "id": "raise-the-bar-after-green", "title": "Raise the bar after the first green check", "repairMove": "Convert the next push into a named acceptance target: content, route, test, live smoke, or cross-site handoff." }, { "id": "no-fake-success", "title": "Reject fake success aggressively", "repairMove": "Make the boundary useful: show the dry run, the missing auth, the required receipt, and the next real action." }, { "id": "platform-contract-instinct", "title": "Think in platform contracts", "repairMove": "Start each pass with the site role, then add only the platform surfaces that make that role more usable or inspectable." }, { "id": "network-first-thinking", "title": "Think in networks, not isolated pages", "repairMove": "Every integration card must name owner, public reads, protected actions, and what this page does not do." }, { "id": "plain-to-operator-ramp", "title": "Build the ramp from plain reading to operator judgment", "repairMove": "Use a ladder: word, example, failure, workflow, protected boundary, verification." }, { "id": "blunt-artifact-pressure", "title": "Use blunt language to force artifact clarity", "repairMove": "Translate frustration into a defect sentence: this label implies X, but the product only does Y." } ], "dragPatterns": [ { "id": "scope-pressure-without-priority", "title": "Scope pressure can outrun priority", "repairMove": "Force a three-lane board: must ship now, should expose publicly, and should queue as next content." }, { "id": "deployed-before-fresh-local-proof", "title": "Deploy cadence can get ahead of local proof", "repairMove": "State the evidence level in every report: local fixed, tests green, build green, preview deployed, production verified." }, { "id": "content-volume-can-crowd-the-signal", "title": "Content volume can crowd the signal", "repairMove": "Make every dense section answer: start here, inspect this, try this, stop here." }, { "id": "platform-standard-can-flatten-identity", "title": "The platform standard can flatten product identity", "repairMove": "Put the product purpose at the top of every pass, then wrap the standard around that purpose." }, { "id": "implicit-context-burden", "title": "Implicit context can become a hidden burden", "repairMove": "Add one line when redirecting: current target, unacceptable failure, and what must be true when done." }, { "id": "more-can-outrun-source-quality", "title": "More can outrun source quality", "repairMove": "Use a source ledger: source, what it proves, what it cannot prove, and what should be rechecked later." } ] }, "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", "/sitemap-full.xml", "/humans.txt", "/.well-known/trust.json", "/.well-known/agents.json", "/.well-known/mcp.json" ] } }