@rubytech/create-siteoffice-code 0.1.256

package/payload/platform/plugins/deep-research/PLUGIN.md

@@ -0,0 +1,19 @@
+---
+name: deep-research
+description: "Structured multi-source research workflow: query decomposition, search strategy, source evaluation, synthesis, citation formatting, plus four named knowledge-worker skills (book-mirror, strategic-reading, academic-verify, data-research). Uses Claude Code's native WebSearch and WebFetch tools."
+tools: []
+skills:
+  - skills/deep-research/SKILL.md
+  - skills/book-mirror/SKILL.md
+  - skills/strategic-reading/SKILL.md
+  - skills/academic-verify/SKILL.md
+  - skills/data-research/SKILL.md
+always: false
+embed: false
+---
+
+# Deep Research
+
+Structured research methodology for multi-source investigation. Uses Claude Code's native `WebSearch` and `WebFetch` tools — no API keys required. No MCP server; the plugin provides skills only.
+
+The researcher specialist is the primary consumer of this methodology. The admin agent can also call `WebSearch` directly for single queries without delegating to the researcher.

package/payload/platform/plugins/deep-research/recipes/README.md

@@ -0,0 +1,36 @@
+# Recipes
+
+Recipes for the `data-research` skill. Each recipe is a YAML file that declares the field-by-field shape of an extraction, the source kinds it accepts, the validations to apply, and the graph target.
+
+A recipe is a contract. The owner reads the recipe and knows what `data-research` will write to the graph before it runs.
+
+## Recipe shape
+
+```yaml
+name: <recipe-name>
+description: One-line description of what this recipe extracts.
+source_kinds:
+  - email-thread       # one or more of: email-thread, web-page, pdf, text-file, form-submission
+fields:
+  - name: <field name>
+    type: string | number | date | boolean
+    required: true | false
+    validation:        # optional
+      min: <number>
+      max: <number>
+      pattern: <regex>
+      enum: [a, b, c]
+graph_target:
+  label: <Node label that must exist in the live Neo4j ontology>
+  identity:            # property names that together uniquely identify a row
+    - <field name>
+    - <field name>
+  relationships:       # optional
+    - type: <RELATIONSHIP_TYPE>
+      target_label: <Node label>
+      target_match: <field name>   # the field whose value resolves the target node via memory-search
+```
+
+## Updating a recipe
+
+Recipes are part of the plugin and are committed alongside the plugin. To add or change a recipe, the owner names the extraction in conversation, the operator drafts the YAML, the owner reviews it, and the file is saved here. The `data-research` skill loads recipes by name at run-time; it does not author or modify them inline.

package/payload/platform/plugins/deep-research/skills/academic-verify/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: academic-verify
+description: "Traces an academic or scientific claim through the publication chain to a primary source, checks for retraction, and returns one of four verdicts: verified, contradicted, retracted, or cannot be confirmed. Triggers when the owner says 'verify this study', 'is this paper real', 'check the citation', 'is X actually peer-reviewed'."
+---
+
+# Academic verify
+
+This skill is for claims that arrive as "studies show", "research suggests", or a named paper title. It traces the claim to the actual paper, the actual journal, and the actual conclusion of the source. It never says "verified" without a primary source URL.
+
+## When to run
+
+Run when the owner asks whether an academic or scientific claim is real. The trigger phrases are above. Also run when the owner repeats a strong claim attributed to "research" or "a study" and asks to check.
+
+## Inputs
+
+`claim` (the statement to verify) and optionally `source` (the citation the owner has, if any: a paper title, DOI, author and year, journal name, or a URL).
+
+If `claim` is missing, refuse. If `source` is missing, the skill will try to find the source from the claim wording.
+
+## Method
+
+1. **Find the originating paper.** If the owner provided a DOI or URL, fetch it. If they provided a paper title, search via `WebSearch` for the title in quotes, prioritising the journal's own site or a known repository (Google Scholar, PubMed, arXiv, OpenAlex). If they provided only the claim wording, search for the claim's distinctive phrasing in quotes.
+2. **Confirm the chain.** Pull these four facts from the source page:
+   - Paper title, authors, journal name, year.
+   - DOI (or arXiv ID, or PubMed ID).
+   - Peer-review status (peer-reviewed journal, preprint, working paper, conference abstract).
+   - The paper's own abstract or conclusion as written.
+3. **Check for retraction.** Search Retraction Watch and the journal's own page for a retraction notice. Capture the date and reason if found.
+4. **Cross-reference the claim against the paper.** Read the paper's abstract or conclusion. Compare the owner's claim wording to what the paper actually says. Decide one of four verdicts:
+   - **Verified.** The paper exists, is peer-reviewed (or clearly named as preprint), is not retracted, and the claim wording matches what the paper concludes.
+   - **Contradicted by source.** The paper exists but the claim wording overstates, reverses, or generalises beyond what the paper actually concludes.
+   - **Retracted.** The paper has been retracted. Name the date and reason.
+   - **Cannot be confirmed.** A search could not find a primary source, or the primary source is behind a paywall and only a secondary summary is available.
+5. **Return the verdict with the chain.** Verdict in the first sentence. Below it, the four facts from step 2. If retracted, the retraction details. If cannot-be-confirmed, name what was searched and where it stopped.
+
+## Output format
+
+```
+**Verdict.** <verified | contradicted by source | retracted | cannot be confirmed>
+
+**Source.**
+- Title: <paper title>
+- Authors: <list>
+- Journal: <journal name>, <year>
+- DOI: <DOI or other identifier>
+- Peer-review status: <peer-reviewed | preprint | working paper | conference abstract>
+- Primary source URL: <URL>
+
+**The paper concludes.** <one to three sentences, paraphrased tightly or quoted verbatim if wording matters>
+
+**The claim says.** <the owner's claim, verbatim>
+
+**Match.** <one paragraph on whether the claim faithfully represents the paper's conclusion. If contradicted, name the specific divergence.>
+
+(If retracted:)
+**Retraction.** <date, reason, retraction notice URL>
+```
+
+## Discipline
+
+- **Never say "verified" without a primary source URL in the output.** A claim is verified against the actual paper, not against a secondary summary.
+- **Paywalled abstracts.** If the abstract is behind a paywall, the verdict is "cannot be confirmed". Surface the paywall, do not infer from training memory what the paper says.
+- **Preprints.** A preprint is not the same as peer-reviewed. Surface the distinction explicitly; the owner may not want to act on a preprint result.
+- **Press release vs paper.** Press releases routinely overstate the paper's conclusions. If the chain goes paper → press release → claim, the verdict is usually "contradicted by source"; name the divergence.
+- **Author affiliation conflicts.** Surface known conflicts of interest from the paper's disclosure if present. Do not pretend they affect the verdict; they affect the owner's interpretation of the verdict.
+
+## Failure modes
+
+- **Search returns no candidates.** Verdict is "cannot be confirmed". Report the search terms tried.
+- **Multiple candidate papers.** Surface the top three and ask the owner to confirm which is the source.
+- **Search returns a retraction watch entry but no journal page.** Use the retraction watch entry as the primary source; the verdict is "retracted".
+
+## What this skill does not do
+
+It does not evaluate the paper's methodology or replicate the analysis. It checks whether the claim matches the source, not whether the source is correct. A flawed paper that is correctly cited returns "verified"; the owner is the one who decides whether the paper itself is sound.

package/payload/platform/plugins/deep-research/skills/book-mirror/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: book-mirror
+description: "Reads a book the owner provides (PDF, ePub, web link, or text), walks it chapter by chapter, and produces a personalised mirror that maps each chapter's claims to the owner's known context. Triggers when the owner says 'mirror this book', 'two-column analysis', 'how does this book apply to me', 'personalise this book against my business'."
+---
+
+# Book mirror
+
+This skill turns a book into a usable document by walking the chapters one at a time and asking, for each: "what does this say, and how does it apply to this specific owner". The output is a personalised pack the owner can read once and act on. It is grounded in the graph; the right-hand column is always specific to what the graph already knows about the owner.
+
+## When to run
+
+Run when the owner asks for a book to be applied to their situation. The trigger phrases are above. Do not run when the owner asks for a simple summary; a summary is what `deep-research` produces, and that is the right skill for that intent.
+
+## Inputs
+
+| Input | Meaning |
+|---|---|
+| `source` | The book. A path to a file in `$ACCOUNT_DIR`, a web URL, or pasted text. |
+| `anchor` | A node in the graph the book is being mirrored against. Usually the `LocalBusiness` node; can also be a named `Project` or `Goal`. |
+
+If the anchor is missing, ask for it in one sentence: "Mirror against the business, or a specific project?".
+
+## Method
+
+1. **Confirm the source.** If `source` is a file path, read it. If it is a URL, fetch it. If it is pasted text, work from the text directly. Reject sources that cannot be read; do not paraphrase a book the skill has not seen.
+2. **Identify the chapters.** Look for chapter headings in the text. If the book has none, segment by first-level headings or by every 2000 to 4000 words. Tell the owner the chapter count before starting.
+3. **For each chapter, build the two columns.**
+   - **Left.** A two-to-three-sentence summary of the chapter's actual claim. Quote verbatim only when the wording matters; otherwise paraphrase tightly.
+   - **Right.** A two-to-three-sentence note on how the claim applies to the anchor, grounded in graph specifics. Pull from `memory-search` against the anchor: the owner's business stage, recent obstacles, named projects, the LocalBusiness `businessType` schema. Name specific entities. Do not write "this applies to your business in general": that is jargon for "I have nothing specific to say".
+   - **Actions.** End each chapter with one or two concrete steps the owner could take this week. Use the imperative ("Call the photographer to confirm the brief for 14 Garth Road" rather than "Consider arranging photography").
+4. **Save the result.** Compose the whole pack as one `:KnowledgeDocument` with `:Section:Chapter` children per chapter. Link the document to the anchor node via `MIRRORS` (or `REFERENCES` if `MIRRORS` is not in the live ontology: call `maxy-graph-get_neo4j_schema` first).
+
+## Output format
+
+```
+# Mirror: <book title> against <anchor name>
+
+## Chapter 1: <chapter title>
+
+**The chapter.** <2-3 sentence summary>
+
+**For <anchor>.** <2-3 sentence application, grounded in graph specifics>
+
+**This week.** 
+- <one concrete action>
+- <one concrete action>
+
+---
+
+## Chapter 2: ...
+```
+
+Present the assembled pack as a single fenced markdown block in chat for owner review before saving. The owner reads the pack inline and can ask for chapter-level edits in their next message. Once the owner approves, write to the graph.
+
+## Length discipline
+
+Each chapter must fit on one screen (roughly 30 lines). If a chapter's claims need more, split the application across two or three chapter mirrors; do not pad. The whole pack should be readable in one sitting; a 20-chapter book becomes a 60-page pack only if every chapter genuinely earns its application.
+
+## Failure modes
+
+- **No chapters detectable and no headings.** Ask the owner to confirm the chunk size or to provide a chapter list.
+- **Anchor has thin graph context** (LocalBusiness with no recent activity, Project with no Tasks). Surface the gap: "the graph has limited context for <anchor>. The right column will be general where it should be specific. Continue?". Wait for confirmation.
+- **`memory-search` returns no useful results for the anchor**. Stop. The book cannot be mirrored against an empty anchor; tell the owner and recommend running `business-profile` or naming a different anchor.
+- **Source fetch fails.** Surface the error literally. Do not summarise from training memory.
+
+## What this skill does not do
+
+It does not summarise a book without an anchor; that is generic content, which `deep-research` can produce. It does not produce a study guide, a literature review, or a comparative essay. It produces one specific output: a personalised application of one book to one named entity in the graph.

package/payload/platform/plugins/deep-research/skills/data-research/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: data-research
+description: "Recipe-driven structured-data extraction. Takes a named recipe and a set of sources (emails, reports, web pages, forms, PDFs) and writes typed entities to the graph per the recipe's schema. Triggers when the owner says 'extract X from these emails', 'track investor updates', 'pull donation amounts', 'build a table of Y from these documents'."
+---
+
+# Data research
+
+This skill turns unstructured-looking sources (emails, reports, forms, web pages) into structured graph entities. The transformation is always recipe-driven: a named YAML recipe declares what fields to extract, what validations to apply, and what graph nodes to write. The skill runs a named recipe; it never invents a schema on the fly.
+
+**Default parent.** Every recipe declares its hierarchy parent via `graph_target.parent` — either `Project` (the run-time recipe argument names which Project elementId to attach to) or `LocalBusiness` (the account root, for cross-project recipes like investor-updates). The skill refuses to run a recipe whose `parent` field is missing or whose named Project does not exist. Per-row writes attach to that parent via the canonical containment edge; the recipe's `relationships:` block describes cross-hierarchy edges (e.g. `ROUND_FOR → Organization`) which are written separately and do not substitute for the parent.
+
+## When to run
+
+Run when the owner wants the same extraction repeated across many sources. The trigger phrases are above. Do not run for one-off extractions; a one-off is what `document-ingest` does.
+
+## Inputs
+
+| Input | Meaning |
+|---|---|
+| `recipe` | The name of an existing recipe at `plugins/deep-research/recipes/<name>.yaml`. |
+| `sources` | One or more source paths or URLs. Email thread paths, PDF paths, web URLs, or a folder. |
+| `parent` | The Project elementId (or `LocalBusiness` for cross-project recipes) the writes anchor to. Required when the recipe's `parent` field is `Project`; ignored when the recipe's parent is `LocalBusiness` (the account root resolves automatically). |
+
+If `recipe` does not match any file in the recipes directory, refuse. List the available recipe names. Do not invent a recipe.
+
+If the owner asks for an extraction shape that no existing recipe covers, the answer is "no recipe exists for that yet. Want me to draft one?". The skill never extracts data without a recipe; that is the point of the recipe layer.
+
+## Recipe shape
+
+A recipe is a YAML file with this shape:
+
+```yaml
+name: investor-updates
+description: One-line description of what this recipe extracts.
+source_kinds:
+  - email-thread
+  - web-page
+  - pdf
+fields:
+  - name: company_name
+    type: string
+    required: true
+  - name: round
+    type: string
+    required: false
+  - name: amount_gbp
+    type: number
+    required: false
+    validation:
+      min: 0
+  - name: date_announced
+    type: date
+    required: true
+graph_target:
+  label: FundingRound
+  parent: LocalBusiness   # or `Project` — names the hierarchy anchor for every row
+  identity:
+    - company_name
+    - date_announced
+  relationships:
+    - type: ROUND_FOR
+      target_label: Organization
+      target_match: company_name
+```
+
+## Method
+
+1. **Load and validate the recipe.** Read the recipe file. Check that every field declared has a `name` and `type`. Check that `graph_target.label` is a label in the live ontology (`maxy-graph-get_neo4j_schema`). Check that `graph_target.parent` is present and resolves (Project elementId supplied at call time, or `LocalBusiness` resolved from the account root). If anything fails, refuse and report the recipe's defect.
+2. **Iterate sources.** For each source: classify by kind against `source_kinds`. Skip sources whose kind is not in the recipe's allowed list, list them in the report.
+3. **Extract per source.** Fetch the source. Use Haiku-driven classification (`memory-classify` with a recipe-specific prompt) to extract each declared field. Apply each field's validation. Reject rows that fail required-field checks; capture them in a rejected list.
+4. **Write to the graph.** For each accepted row, `memory-write` a node with the declared label and the extracted properties. Attach it to the resolved hierarchy parent via the canonical containment edge. Stamp `createdByAgent: data-research`, `createdByRecipe: <recipe name>`, `sourceDocumentId: <source>`. Write the declared cross-hierarchy relationships, resolving target nodes via `memory-search` on the named match property.
+5. **Report.** Return one line per source (accepted count, rejected count) and one summary line: total rows written, total rejected, total relationships created.
+
+## Output format
+
+```
+**Recipe.** <name>
+**Sources.** <N> processed.
+
+| Source | Accepted | Rejected | Reason |
+|---|---|---|---|
+| <source path or URL> | 3 | 1 | "amount_gbp negative" |
+| ... | | | |
+
+**Total.** 12 rows written as :<Label>, 9 relationships created via <RelType>.
+**Rejections.** 3 rows rejected (full list below).
+```
+
+## Why recipes
+
+A recipe is a contract. The owner reads the recipe and knows what will be written. The recipe is version-controlled and auditable. Without recipes, the skill would extract whatever the LLM thinks is interesting, which means the graph schema drifts with every run and the owner cannot trust what arrives. The recipe layer is the difference between a controlled pipeline and a junk shop.
+
+## Failure modes
+
+- **Recipe file is malformed.** Surface the YAML error literally and refuse.
+- **Recipe declares a `graph_target.label` not in the ontology.** Refuse. Tell the owner the label is missing and recommend either adjusting the recipe or extending the ontology.
+- **Recipe's `graph_target.parent` is missing or unresolvable.** Refuse. The hierarchy parent is mandatory; without it, every row would land as an orphan.
+- **No sources match the recipe's allowed kinds.** Refuse. List what the recipe accepts.
+- **Target-match relationship cannot resolve** (the recipe wants `ROUND_FOR -> Organization` and the named company is not in the graph). Capture in the rejected list with the reason "target organisation not found"; do not create a placeholder organisation.
+- **Embedding service unavailable mid-batch.** Stop. Report which sources completed and which did not.
+
+## Where recipes live
+
+Recipes live at `platform/plugins/deep-research/recipes/<name>.yaml`. The directory is part of the plugin and ships with the platform. To author a new recipe, the owner names the extraction they want; the skill can scaffold the YAML and the owner reviews and saves it. Recipe authoring is a separate path; this skill consumes recipes, it does not write them inline.
+
+## What this skill does not do
+
+It does not run free-form extractions. It does not write to the graph without an approved recipe. It does not modify recipes during a run; if the recipe needs changing, the run aborts, the owner edits the recipe, and the run is re-issued.

package/payload/platform/plugins/deep-research/skills/deep-research/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: deep-research
+description: >
+  Activate this skill when the user asks Claude to research a topic, find current information,
+  compare competitors, review literature, fact-check a claim, or answer any question that
+  benefits from live web sources. Trigger phrases include: "research", "find out", "what's
+  the latest on", "compare X and Y", "who is", "look into", "fact-check", "deep dive",
+  "what do we know about", "literature review", or any question where Claude's training
+  data may be stale or insufficient. This skill replicates Perplexity-style agentic web
+  research using only Claude models and Claude Code's native tooling — no external API keys
+  required.
+
+config:
+  citation_style: "inline"   # Options: inline | footnotes | cards | minimal
+  max_sources: 8             # Maximum sources to synthesise per query (4–12 recommended)
+  search_depth: "standard"   # Options: standard (3–5 searches) | deep (6–12 searches)
+  show_confidence: true      # Append confidence note (High / Medium / Low)
+  follow_up_questions: true  # Suggest 3 follow-up questions
+---
+
+# Deep Research Skill
+
+You are a research agent. Answer questions using live web sources, synthesise findings across multiple sources, and present results with full attribution. You do not guess. You search, read, extract, and cite.
+
+## Workflow
+
+**Phase 1 — Decompose.** Before searching, break the question into: core question, temporal dimension (breaking / recent / evergreen), perspective breadth, and 2–5 sub-questions. State your decomposition in 1–3 lines, then proceed without asking permission. After decomposition, read `references/research-modes.md` to select the appropriate research mode.
+
+**Phase 2 — Search.** Map sub-questions to targeted search queries. Read `references/search-strategy.md` for query crafting rules and source evaluation criteria.
+
+**Phase 3 — Fetch and extract.** For each source, fetch full page content, extract only what is relevant to the sub-question, note publication dates. See `references/search-strategy.md` for source quality hierarchy and staleness rules.
+
+**Phase 4 — Synthesise.** Write a structured response that directly answers the original question. Read `references/citation-styles.md` and apply the citation style from `config.citation_style`.
+
+**Phase 5 — Confidence.** If `show_confidence: true`, append a confidence assessment. See `references/citation-styles.md` for the High / Medium / Low criteria.
+
+**Phase 6 — Follow-ups.** If `follow_up_questions: true`, suggest 3 genuinely useful next questions. See `references/citation-styles.md`.
+
+## Hard Rules
+
+1. **Never fabricate citations.** If you cannot find a source for a claim, say so explicitly.
+2. **Never quote more than 15 words verbatim** from any single source.
+3. **One direct quote per source maximum.** Paraphrase everything else.
+4. **Do not recite training data as search results.** If relying on training knowledge, say: "(from training data, not verified live)".
+5. **Stale is worse than honest.** If you cannot find current information, state the most recent date you found and invite the user to check for updates.
+6. **No padding.** Every sentence must carry information. No filler, generic caveats, or restated conclusions.

package/payload/platform/plugins/deep-research/skills/deep-research/references/citation-styles.md

@@ -0,0 +1,52 @@
+# Citation Styles, Confidence, and Follow-ups
+
+## Citation Styles (Phase 4)
+
+Apply the style set in `config.citation_style`:
+
+### inline (default)
+> The company raised $120M in Series B funding [1], led by Andreessen Horowitz [2].
+> Sources: [1] techcrunch.com/... [2] a16z.com/...
+
+### footnotes
+> Prose with no inline markers. Full source list at end:
+> ---
+> **Sources**
+> 1. Title — domain.com/path (Date if known)
+> 2. Title — domain.com/path
+
+### cards
+> Each source rendered as a mini card:
+> ┌─────────────────────────────────────────┐
+> │ [1] Title of article                    │
+> │ Source: domain.com · Date: YYYY-MM-DD   │
+> │ Relevant finding: one-line summary      │
+> └─────────────────────────────────────────┘
+
+### minimal
+> The company raised $120M (techcrunch.com/...), led by a16z (a16z.com/...).
+
+## Confidence Assessment (Phase 5)
+
+If `show_confidence: true`, append a brief confidence assessment after the main answer:
+
+**Confidence: High / Medium / Low**
+- High: multiple independent sources agree, sources are recent and authoritative
+- Medium: sources partially agree, or primary sources are thin
+- Low: limited sources, conflicting information, or significant recency gaps
+
+Always flag explicitly if:
+- A key sub-question could not be answered from available sources
+- Important information may exist behind paywalls or login walls
+- The topic is moving fast and this answer may be stale within days/weeks
+
+## Follow-up Questions (Phase 6)
+
+If `follow_up_questions: true`, end with:
+
+**You might also want to ask:**
+1. [Specific follow-up question 1]
+2. [Specific follow-up question 2]
+3. [Specific follow-up question 3]
+
+Make these genuinely useful — the next natural step in the research, not generic variations of the original question.

package/payload/platform/plugins/deep-research/skills/deep-research/references/research-modes.md

@@ -0,0 +1,22 @@
+# Research Modes
+
+Adjust behaviour based on query type. Select the appropriate mode after Phase 1 decomposition.
+
+## General Research / Fact-finding
+
+- 3–5 sources is usually sufficient
+- Prioritise recency and source authority
+- Lead with the direct answer, then supporting evidence
+
+## Competitive / Market Intelligence
+
+- Always cover: (a) the company's own claims, (b) independent analyst or press coverage, (c) user sentiment (G2, Reddit, Trustpilot where relevant)
+- Structure output as: Overview → Key differentiators → Weaknesses/risks → Pricing (if findable) → Verdict
+- Flag if pricing is not publicly listed
+
+## Academic / Deep Literature Review
+
+- Prioritise peer-reviewed sources, preprints (arXiv, bioRxiv), and institutional reports
+- Note study size, methodology, and date for each source
+- Distinguish between consensus findings and contested/emerging claims
+- Use deep search depth — do not stop at 3 sources for academic queries

package/payload/platform/plugins/deep-research/skills/deep-research/references/search-strategy.md

@@ -0,0 +1,24 @@
+# Search Strategy and Source Evaluation
+
+## Query Crafting (Phase 2)
+
+Map each sub-question to one or more targeted search queries:
+
+- Keep queries short (3–6 words). Specific nouns beat vague phrases.
+- Vary query framing: try the direct question, a "site:domain" form, and a comparison form where relevant.
+- For competitive intelligence: always search the target company directly AND search for independent reviews/comparisons.
+- For literature/academic queries: search for primary papers, then for secondary summaries.
+- For fast-changing topics (pricing, funding, personnel): append the current year to queries.
+- Never repeat the same query twice. If a search returns poor results, rephrase — don't retry identical terms.
+
+## Source Fetching and Extraction (Phase 3)
+
+For each source returned:
+
+1. Fetch the full page content where possible, not just the snippet.
+2. Extract only what is relevant to the sub-question that drove this search.
+3. Note the publication date if visible.
+4. Flag sources older than 18 months as `[possibly outdated]`.
+5. Prefer: official docs, primary research, reputable press. Deprioritise: forums, SEO farms, undated pages.
+
+Do not quote large blocks verbatim. Paraphrase and extract the key claim or data point.

package/payload/platform/plugins/deep-research/skills/strategic-reading/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: strategic-reading
+description: "Reads a source (article, book, report, document) through a specific lens the owner names, and produces both a faithful summary and an applied playbook. Triggers when the owner says 'read this through the lens of X', 'apply this to my problem', 'extract a playbook for Y from this', 'what can I learn from this about Z'."
+---
+
+# Strategic reading
+
+This skill reads a document with a specific question in mind. The owner names the lens (a project, a problem, a goal). The skill summarises what the source actually says, then translates each section into how it applies to the named lens, and closes with a playbook of three to seven concrete steps. Both halves are grounded: the left half in the source text, the right half in the graph.
+
+## When to run
+
+Run when the owner has a specific problem and wants to test what a particular source teaches them about it. Not for general reading; for applied reading. The trigger phrases are above.
+
+## Inputs
+
+| Input | Meaning |
+|---|---|
+| `source` | The text to read. Path to a file, a URL, or pasted text. |
+| `lens` | The named focus. A `:Project`, a `:Goal`, a problem statement in the owner's words, or an entity in the graph the owner wants to apply the source to. |
+
+If `lens` is missing, ask once: "Through which lens: a project, a goal, or a problem statement?".
+
+## Method
+
+1. **Confirm the source.** Read or fetch it. If it cannot be read, refuse; do not paraphrase from training memory.
+2. **Resolve the lens.** If the lens is a named entity, `memory-search` for it and pull its current state, recent obstacles, related entities. If the lens is a free-text problem, capture it verbatim; it is the question every section will be tested against.
+3. **Walk the source in sections.** Section boundaries are the source's own headings. For each section, two paragraphs:
+   - **The section.** One paragraph: what it claims and what its evidence is. Quote verbatim only when the wording matters.
+   - **Applied to <lens>.** One paragraph: how the section's claim helps or hurts the lens. Use graph specifics. Name entities. Do not write "this could apply" or "consider how this might"; write the specific implication for the specific lens.
+4. **Produce the playbook.** After the last section, compose a single list of three to seven concrete actions the owner could take. Each action is imperative, names a specific next step, and (where possible) names the entity it touches.
+5. **Save the result.** Compose the whole pack as one `:KnowledgeDocument` linked to the lens's underlying entity via `INFORMS` (or `REFERENCES` if `INFORMS` is not in the live ontology).
+
+## Output format
+
+```
+# Strategic reading: <source title> for <lens>
+
+## Lens
+<one-paragraph restatement of the lens, including the graph context the skill loaded>
+
+## Section 1: <section heading>
+
+**The section.** <one paragraph on the source's claim>
+
+**Applied to <lens>.** <one paragraph on the implication for this owner>
+
+## Section 2: ...
+
+## Playbook
+1. <imperative action, names entity>
+2. <imperative action, names entity>
+... (three to seven items)
+```
+
+Present the assembled pack as a single fenced markdown block in chat for owner review before save. The owner reads it inline and can ask for section-level edits in their next message. On approval, write to the graph.
+
+## Difference from book-mirror
+
+Book mirror walks every chapter and produces a chapter-by-chapter application: the unit of work is the chapter. Strategic reading uses the source's own sections and is filtered by a specific question: the unit of work is the section, and the filter is the lens. A book mirrored is a personalised version of the whole book. A source read strategically is the answer to one question about that source.
+
+## Failure modes
+
+- **Lens resolves to an entity with no graph context.** Surface the gap and ask whether to proceed with the lens as a free-text problem instead.
+- **Source covers a topic the lens does not touch.** Each section's right-hand column will read as "this section does not apply directly to <lens>". Surface this pattern after section 3; the owner may want to abandon the read or change the lens.
+- **Source is shorter than three sections** (a short blog post, a one-page memo). Use paragraph boundaries instead of section boundaries. If the source is fewer than 200 words, do not run; the owner can read it themselves faster than the skill can mirror it.
+
+## What this skill does not do
+
+It does not produce a critical review of the source. It does not score the source. It does not compare it against other sources. It produces one specific output: one source read with one lens, ending in one playbook.

package/payload/platform/plugins/docs/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "docs",
+  "description": "Comprehensive user guide and platform documentation for Maxy. Load references when users ask how-to, setup, or troubleshooting questions. Also contains platform architecture references for admin use.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

package/payload/platform/plugins/docs/PLUGIN.md

@@ -0,0 +1,58 @@
+---
+name: docs
+surface: platform
+description: "Comprehensive user guide and platform documentation for Maxy. Load references when users ask how-to, setup, or troubleshooting questions. Also contains platform architecture references for admin use."
+metadata: {"platform":{"always":true,"embed":["public","admin"],"pluginKey":"docs"}}
+---
+
+# Maxy Documentation
+
+This plugin is the single source of truth for Maxy documentation. It ships with every install and is always the version the user has installed.
+
+Load the relevant reference when the user asks a how-to question, requests help with setup, reports an issue, or wants to understand how something works.
+
+## User Guide
+
+Load these when users ask about Maxy features or need guidance:
+
+- **Getting started** → `references/getting-started.md` — first run, what Maxy is, how to use it
+- **Plugins** → `references/plugins-guide.md` — what plugins are, how to install/remove them, the marketplace
+- **Memory** → `references/memory-guide.md` — how Maxy remembers things, what is stored, privacy
+- **Graph view** → `references/graph.md` — the admin `/graph` page: node/edge display, zoom-adaptive Conversation labels, filter chips, trashed nodes
+- **Contacts** → `references/contacts-guide.md` — adding, looking up, and managing contacts
+- **Telegram** → `references/telegram-guide.md` — Telegram setup, the bot, daily use
+- **Settings** → `references/settings.md` — output style, effort level, account preferences
+- **Access Control** → `references/access-control.md` — who can chat with your public agent, invitations, authentication
+- **Projects** → `references/projects-guide.md` — creating projects, tracking health, phase transitions, completing
+- **Slides** → `references/slides.md` — generating, theming, and reviewing HTML slide decks with `/slides`
+- **Troubleshooting** → `references/troubleshooting.md` — common issues and how to resolve them
+
+## Platform Reference
+
+Load these when performing admin tasks or diagnosing platform behaviour:
+
+- **Platform architecture** → `references/platform.md` — how the platform works, agent types, the plugin model
+- **Platform internals** → `references/internals.md` — retrieval pipeline, embedding infrastructure, guard layers, graph expansion, keyword subscriptions, context assembly, tool call audit trail, programmatic spawn entry point and end-turn auto-close lifecycle. Load when answering architecture questions, assessing whether a capability exists, diagnosing retrieval behaviour, or reviewing security and privacy features.
+- **Admin UI** → `references/admin-ui.md` — compact map of every `/api/admin/*` mount, every sidebar surface, the system-stats widget (CPU/RAM thresholds), the artefact pane, and the health-vs-version split. Load when diagnosing an admin route, explaining the CPU/RAM widget, or onboarding a new admin endpoint.
+- **Admin session** → `references/admin-session.md` — signed sessionKey + PIN-rebind survival contract, SDK-resume across `systemctl restart`, and the single-entry `POST /api/admin/claude-sessions` wrapper that owns every programmatic admin spawn-with-initialMessage. Load when diagnosing admin session continuity, designing a programmatic admin spawn.
+- **Cloudflare** → `references/cloudflare.md` — dashboard-first tunnel setup, the `cloudflared`-CLI-only tool surface, single-recovery-path (re-login) for every wrong-account failure.
+- **Deployment** → `references/deployment.md` — Pi setup, Cloudflare tunnel, start script
+
+## References
+
+- references/getting-started.md
+- references/plugins-guide.md
+- references/memory-guide.md
+- references/graph.md
+- references/contacts-guide.md
+- references/telegram-guide.md
+- references/settings.md
+- references/access-control.md
+- references/projects-guide.md
+- references/troubleshooting.md
+- references/platform.md
+- references/internals.md
+- references/admin-ui.md
+- references/admin-session.md
+- references/cloudflare.md
+- references/deployment.md