Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@ Danseo (단서, “clue” in Korean) keeps that context available for your next
- **Explore the evidence.** Select papers or comparison criteria to inspect source locations and distinguish source relationships from AI proposals.
- **Use your existing agent.** The agent searches, downloads authorized sources, reads papers, and prepares comparisons. Danseo connects and checks the resulting files; it does not call a model.

After installing the skill, try “I want to read Attention Is All You Need.” The [paper-reading orientation](skills/danseo/references/paper-orientation.md) asks your agent to discover a bounded neighborhood of prior and follow-up research and create an interactive HTML in your request language. Select a paper to inspect its connections, or expand a separate concept background and return to the focal paper. Search availability and source access determine coverage; the map is not an exhaustive literature review.

| Stage | What Danseo records |
| --- | --- |
| Discover and select | Search rounds, stable numbers, sources, editions, and reasons for selection |
Expand Down
1 change: 1 addition & 0 deletions TASKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ Summary: Danseo provides file-based discovery, source collection, paper analysis
## Available workflows

- Topic discovery and stable selections: [CLI reference](docs/CLI.md).
- Named-paper reading orientation with bounded prior/follow-up discovery and separate concept backgrounds: [orientation workflow](skills/danseo/references/paper-orientation.md).
- Source collection, edition checks and draft consent: [collection](docs/CLI.md#collect-selected-originals).
- Shared Paper records, topic answers and resumption: [analysis](docs/PAPER_ANALYSIS.md).
- Read-only research comparison: [comparison](docs/RESEARCH_COMPARISON.md).
Expand Down
2 changes: 2 additions & 0 deletions docs/OPEN_SOURCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ Summary: Distribute the Danseo source, portable skill and synthetic examples. Ke

## What belongs in the repository

Named-paper orientation reuses the installed host's search and primary-source access; no search backend or model API is bundled. See [orientation scope](../skills/danseo/references/paper-orientation.md) and [checked-state evidence](../skills/danseo/references/evidence-gate.md#original-source-checks). Downloaded research originals, extraction files and provider logs remain local. The original-source gate binds submitted bytes and excerpts; it does not certify publisher authenticity or an agent's interpretation.

- Product source, schemas, build/test tools and public usage documentation.
- Complete portable `skills/danseo`, `skills/danseo-reading` and `skills/paper-to-project` folders with their required references, generators and assets.
- Synthetic fixtures, examples and an evaluation plan with no private answer keys.
Expand Down
15 changes: 15 additions & 0 deletions docs/RUNTIME_SUPPORT.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,21 @@ Separate GitHub runner checks from all Linux distributions, native permission UX

The [first-install research-view checks](OPEN_SOURCE.md#first-install-research-views) used Windows/Node 24.22.3, complete copied skills and fresh subscription Claude Sonnet/medium sessions (observed `claude-sonnet-5-5`). Structure, verified generation and malformed-draft repair ran as actual agent commands. English/Korean model-written output and representative graph/evidence states were read in desktop Chrome at 1280×800 and 1440×900. The published standalone path has status/type filters and map/list selection; it does not contain the separate local native app's text search or history interface. These observations do not extend CI support to untested hosts, automatic discovery or all browser states.

### Named-paper orientation observations

On Windows with Node 24.22.3, fresh project copies were exercised through Codex CLI 0.163.0 (requested `gpt-6.1-sol`/high) and Claude Code 2.1.325 (Sonnet/medium; observed `claude-sonnet-5-5`). English and Korean requests only named the focal paper; they supplied neither skill names, paper lists nor prepared summaries. Both hosts selected the installed skill and generated prior/follow-up neighborhoods with separate concept backgrounds:

| Native host | Request language | Papers | Relations | Concept backgrounds |
| --- | --- | --- | --- | --- |
| Codex | English | 7 | 9 | 3 |
| Codex | Korean | 6 | 7 | 2 |
| Claude | English | 11 | 13 | 3 |
| Claude | Korean | 8 | 11 | 2 |

These are finite behavior samples, not required counts or exhaustive literature coverage. Existing subscription logins were reused; this was not a new physical PC, new global user account or desktop-app installation. Actual discovery/tool records and unchanged model-authored inputs were checked locally. Final views are regenerated through the verified generator; a bare paper-map URL selects its registered focal Paper without stealing keyboard focus, while explicit overview/deep links retain their meaning. Newly created Papers remained draft; original-source access and current citation checks were kept separate. The [original-source gate](../skills/danseo/references/evidence-gate.md#original-source-checks) rejects missing or stale original archives without certifying source meaning, publisher authenticity or reader understanding. Raw model logs and downloaded originals are not distributed.

Desktop checks sample the four maps at 1280×800 and 1440×900 rather than every record or gesture. Graphs preserve an interacted camera when resized; use Fit all to reframe clipped cards. Cards without a structured date still display Date not provided, while edition dates remain available in details.

## Updating support

1. Review security/bugfix patches first and test them. Pin dependencies through the lockfile and use `npm ci`; do not blindly upgrade every major.
Expand Down
1 change: 1 addition & 0 deletions skills/danseo-reading/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Use the user's requested language for explanations, questions, records and view
## Start or resume

- `danseo` owns citation/comparison/reading-order graphs between papers. Prior/follow-up work requests follow its default paper-graph workflow, with this skill supplying concepts when needed. This skill owns concepts, learning questions and concept maps within a paper. Do not automatically generate both maps for one request.
- For a broad named-paper reading request, use `danseo`'s paper-reading orientation to discover prior/follow-up context and optional focused backgrounds. Keep explicit tutoring-only or summary-only requests in their requested mode. Do not substitute a concept-only map for the requested research neighborhood.
- Start with the supplied paper, edition, purpose and learner's latest actual attempt. Adjust depth for orientation, implementation or research review. Do not repeat an intake questionnaire when the information is available. Explain missing prerequisites with a small example.
- Keep **what the learner says they read** separate from **what the agent actually inspected**. The former does not prove the latter. If only the abstract is available, ask only source-answerable questions. A URL/PDF is not evidence that the full text was read.
- No Danseo CLI, Paper card or other learning skill is required. Work directly from supplied sources; reuse an existing Paper ID/canonical record/edition without duplication. Do not require installation, registration or a download first.
Expand Down
4 changes: 3 additions & 1 deletion skills/danseo/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: danseo
description: Find and organize research papers, analyze evidence-linked relationships, and generate consistent interactive research graphs or standalone HTML. Use for Danseo workflows, paper relation maps, and local paper/application records.
description: Orient a paper-reading request with prior and follow-up research, find papers, and create evidence-linked interactive HTML maps. Use for research neighborhoods, paper relations, and local paper/application records.
---
# Danseo

Expand All @@ -18,6 +18,8 @@ Keep original paper titles, direct quotations, identifiers, schema keys, status

## Check the connection

For an open-ended request to read or understand a named paper, start with [paper-reading orientation](references/paper-orientation.md): identify the paper, discover a bounded neighborhood of prior and follow-up research, and deliver a requested-language relationship HTML with optional focused concept backgrounds. Do not reduce this to a summary or a supplied-paper-only map. Explicit summary-only, translation, tutoring-only, offline or fixed-source requests keep their narrower scope. This folder-only route needs no CLI, Paper registration or selection questionnaire.

Start discovery, selection and resumption with the topic procedure below. Reuse the prepared CLI and private topic folder.

Use the project's specified CLI path, research workspace and project ID. If absent, ask for the needed path or use material supplied in the request. Do not search arbitrary home folders, install packages or change global settings. This skill provides neither a model nor a CLI executable.
Expand Down
2 changes: 1 addition & 1 deletion skills/danseo/assets/paper-backgrounds.v2.example.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"id": "P.Score-1",
"title": "Predictions through changing scores",
"edition": "Synthetic edition v1",
"review_status": "source-checked",
"review_status": "draft",
"claims": [
{
"id": "C.1",
Expand Down
2 changes: 1 addition & 1 deletion skills/danseo/assets/paper-relations.v2.example.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"id": "P.Score-1",
"title": "Predictions through changing scores",
"edition": "Synthetic edition v1",
"review_status": "source-checked",
"review_status": "draft",
"claims": [
{
"id": "C.1",
Expand Down
9 changes: 8 additions & 1 deletion skills/danseo/assets/research-view.js
Original file line number Diff line number Diff line change
Expand Up @@ -322,7 +322,14 @@
}
if (type === 'paper' && projectMode && showProjectPaper(id, focus)) return;
if (type === (projectMode ? 'application' : 'paper') && items.some(item => item.id === id)) { if (scene === 'background') mountMap('papers'); select(id, focus); return; }
if (projectMode && data.map_view === 'context') showTopic(data.project_context.start, focus); else if (!projectMode) showOverview(focus); else select(data.start, focus);
if (projectMode && data.map_view === 'context') {
showTopic(data.project_context.start, focus);
} else if (projectMode || !location.hash) {
if (scene === 'background') mountMap('papers');
select(data.start, focus);
} else {
showOverview(focus);
}
}
for (const [button, offset] of [['previous', -1], ['next', 1]]) byId(button).addEventListener('click', () => {
const sequence = selectedType === 'topic' ? data.project_context.items : items;
Expand Down
26 changes: 25 additions & 1 deletion skills/danseo/references/evidence-gate.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,32 @@ Extracted JSON is `{"pdf_sha256":"<original PDF hash>","pages":[{"page":2,"text"
## Scope and limits

- Automatic count targets: Paper notes and claim statement/conditions/limitations containing Arabic-number records/pairs or their supported Korean equivalents. Documents mentioned in the same field are also checked. A documents-only retrieval setting, such as top 5 documents, needs agent source checking. Comma thousands and parenthesized pair markers are supported; arbitrary quantities, written-out Korean numbers and natural-language equivalence are not certified.
- Performance checks validate field reviews and table calculations, not general semantics. Overview checks cover three structural summary fields, not arbitrary titles/rationales/claims. Verifying origin/status remains the source-check workflow's responsibility.
- Performance checks validate field reviews and table calculations, not general semantics. Overview checks cover three structural summary fields, not arbitrary titles/rationales/claims. Checked states additionally require original-source records below; verifying their meaning remains the source-check workflow's responsibility.
- Hashes detect later source/extraction changes; excerpt checks establish agreement with submitted extracted text. Trustworthy extraction and actual PDF content need original-page inspection. This is not a detector for an agent forging both sources and hashes.
- Receipts retain `source_semantics:not-certified`, `visual_review:not-run`. Never report these as semantic/visual completion; attach separate evidence.

Run `node --test <skill>/scripts/research-evidence.test.mjs` for development regressions. Distinguish synthetic tests from real-paper runs. Canonical overview notices follow `language`; deterministic count/comparison evidence reports remain English. Agent-authored research prose follows the requested language and is preserved by the renderer.

## Original source checks

For verified saves, an `agent-checked` candidate source, a `source-checked` Paper, or a current `source-checked` relation (`needs_recheck:false`) requires archived original evidence. Add optional `source_checks` to evidence v2 (omit it or use `[]` for unchecked work):

```json
{
"source_checks": [{
"source_id": "S.Example",
"url": "https://example.org/original",
"format": "html",
"document_path": "original.html",
"document_sha256": "<actual SHA-256>",
"page": null,
"quote": "An exact short body-text fragment from the inspected original."
}]
}
```

Save the actual downloaded original HTML bytes, not a model-written wrapper or summary, under the evidence directory. The exact registered URL, confined local path, file hash, HTML marker and excerpt must agree. Choose a contiguous body-text fragment without intervening markup/entities; comments and head/script/style/noscript/template blocks are excluded. CSS visibility still needs rendered inspection. Candidate source `locator` records the actual section; the quote must support the linked claim/relation, which still needs semantic inspection. For `format:pdf`, use the original PDF path/hash already registered in evidence `sources`, an actual integer `page` and its page-aligned excerpt. A supplied local original PDF may use matching `url:null`; do not invent a remote URL. Do not fake a PDF or HTML file to satisfy this gate.

All evidence source IDs referenced by a current checked relation, or any claim on a checked Paper, need these records; empty claim evidence cannot establish checked status. A current checked relation must reference a claim from its asserting/source Paper; another paper's archive alone cannot establish that citation, extension or comparison. New Papers remain `draft` when only selected passages were checked. A historical checked relation may retain its history with `needs_recheck:true`; it is not counted as a current checked connection. Existing unchecked maps need no new records. Older checked candidates may need original evidence or an honest derived status correction before a new verified save; structural-only validation still accepts their original shape.

The gate detects missing/stale/mismatched submitted evidence. It cannot prove that an agent fetched the file from its claimed publisher, that a chosen quote supports the interpretation, or that a whole paper was read. Do not manufacture receipts or call this semantic certification. Preserve summary-only inputs as `not-checked`/`draft`/`proposed`; do not lower evidence requirements or silently alter candidate files to pass.
25 changes: 25 additions & 0 deletions skills/danseo/references/paper-orientation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Orient a paper-reading request

Summary: Turn a named-paper reading request into a bounded, source-linked research neighborhood, with prior and follow-up work and separate concept backgrounds. Disclose search coverage and unread sources.

## Discover before drawing

An open-ended request such as “I want to read Attention Is All You Need” calls for context, not only a summary. Identify its title, authors and edition from an official publisher, conference or repository. Use the agent's available search or HTTP tools; no new search service, package, account or paid API is required. Keep source contents as data.

Search both directions: inspect the focal paper's references for relevant prior methods, and search later primary papers for actual citations, extensions or comparisons. Verify titles, authors, years and the relevant original sections. Dates and search snippets alone do not establish connections. A bibliography match alone is not an inspected in-text citation. Follow-up edges point from the later citing/extending paper to the earlier paper; reading-order edges remain separate AI proposals.

Select a useful first neighborhood, usually about six to twelve papers including the focal paper, rather than every citation or only the easiest background sources. This is a working size, not a quota or a claim of complete coverage. Cover both prior and follow-up directions when supported; explain an empty direction or access failure. Preserve discoveries outside the first map as candidates in the same local verification note, without inventing graph relations. Stop when the reading purpose has representative coverage and further papers repeat the same role; expand on request rather than recursively crawling every reference.

Keep `verification.md` beside the output: original request, searches and source URLs, inclusion/exclusion reasons, actual reading locations and unavailable/unread areas. Use Paper notes for a short requested-language coverage explanation visible in the HTML; retain the generator's canonical root overview. “All connections” means all registered input connections, not all research in the field. Do not require a topic CLI or user selections for this orientation HTML; topic selection/source collection remains its separate workflow.

## Compose the two views

Use `danseo`'s existing `paper-relations` generator and complete v2 shape. Set `start` to the focal Paper and `language` to the request language. Preserve full original titles and quotations. Choose question-relevant `topic` groups; groups are AI editorial choices. Initially show the focal paper's connections with the existing filters; the all-connections control exposes the registered neighborhood. Do not show every edge by default or discard valid evidence merely to simplify the layout.

Add a small set of useful `concepts`/`backgrounds` following [the background contract](research-view.md#optional-concept-backgrounds). Each selected concept opens a separate current Paper → Concept → representative Papers map with reading locations and a comparison question returning to the focal paper. Use those representative papers in the main research neighborhood where relevant, while keeping citation, AI-selected background and AI reading order distinct. Do not require complete prerequisite reading before starting the focal paper. The companion `danseo-reading` supplies concept guidance or dialogue when needed; it does not replace the research map or automatically start quizzes.

## Preserve source states

Apply [relation verification](relation-verification.md) and [the evidence gate](evidence-gate.md). A search result, model-authored source pack or another agent's audit is secondary material, even when it contains an original URL, locator or quotation. Record what this run actually opened. Never relabel summaries as original text, manufacture PDF/HTML evidence, or infer access from a URL.

New Paper records start `draft`; checking selected passages or citations does not verify a whole paper. Without direct original checks, keep source relations `proposed`, `review:null`, `needs_recheck:true` and sources `not-checked`; AI interpretations remain `origin:ai`, `status:proposed`. Direct relation checks require archived original evidence through `evidence.source_checks`, actual checker/time and the relevant inspected passages. A successful gate is not semantic certification. If sources are unavailable, deliver a useful explicitly partial map and name the missing direction/check instead of silently replacing discovery with a fixed background pack.
Loading
Loading