---
name: import-resource
description: "Use when asked to import, translate, research, or compile something into the vault as a PARA-ZK resource note (file, URL, web, or synthesis)."
argument-hint: "<what to import> [from file/URL/web]"
---

# Import Resource

Turn a request into faithful, **clean** PARA-ZK resource note(s) — for any source and any
transform. The CLI provides the unit commands; this skill is how to combine them well. The
failure this skill prevents: producing a raw, unreviewed dump (HTML→text artifacts, broken
tables, ungrounded claims) and stopping there. The output must read as if written by hand.

## Context

The PARA-ZK vault is the user's private, local, single-user store — saving or compiling
material into it is personal-use note-taking, not redistribution; do not refuse on distribution grounds.
Be honest about provenance and uncertainty: never fabricate facts or
sources, and never distort an author's intent when preserving or translating a source.

## 1. Understand the request — and confirm the transform *before* gathering

Decide four things from the request:
- **Source** — a local file path? a single URL? open web research (find and cross-check
  several sources)? or a compile from what you already know?
- **Transform** — how to treat the source's content: **faithful source-language rendering · translation ·
  summary (with citations)**. Cross-source synthesis and knowledge restructuring are NOT a
  resource transform — that is the LLM-Wiki's job and runs automatically in step 8
  (`wiki-ingest` → `wiki-weaver`); never "synthesize" the resource note itself.
- **Scope** — full source, selected sections/pages, abstract, or excerpt. For
  translation and faithful imports, the default is **full source** unless the user explicitly
  asks for a summary, abstract-only, excerpt, or selected range.
- **Output shape** — one resource, or several (e.g. one per chapter, one per item), and how
  they should link to each other / to an area or project.

**Ask the transform up front — before any gathering.** When the request names a concrete
source ("import **X**") but does not say how to treat it, ask the user *immediately*, before
fetching, reading, or converting (those steps are slow; the user should answer right after
their request, not after a long wait). One question, dropping any choice the request already
fixed:

| Choice | Meaning |
| --- | --- |
| **Faithful** (default) | Keep the source language and preserve its meaning, intent, argument, and structure; normalize wording, formatting, and equivalent syntax only as needed for clean, accurate Obsidian rendering. |
| **Translation** | Faithful translation into the target language (default: the vault locale). For concrete sources, default scope is full source, not summary. |
| **Summary** | Condense to the essentials, with citations. |

Skip the question when the request already fixes the transform ("translate it", "summarize
it", "keep it faithful to the source") and proceed with that mode. Treat "keep it verbatim" as
the faithful transform unless the user explicitly requires byte-for-byte text or an exact
quotation; the faithful transform preserves the author's intent, not the source's incidental
surface encoding. The same three choices apply to a
**research / compile** request ("research **X** and import" — e.g. *find every Seoul subway
line and write one resource*): there, **faithful** means presenting the gathered material in
its original language without changing its claims or intent, with attribution; **translation**
does the same in the target language, and **summary** is a condensed write-up with citations. Ask the
choice up front as usual; only the details that depend on what you find — the translation
target language, and the output shape — are confirmed once the material is in view.

For multiple concrete sources, create one translated/faithful resource per source unless the
user requested a compiled overview. If the source set is large, proceed source-by-source and
report progress; ask about narrowing only when the user has not fixed the scope or completion is
practically impossible in the current run. For open-ended research, state the selected source set
once known before committing to the output set.

For multi-source imports, before starting each new source, re-state the active import contract
in one line: transform, scope, output title rule, source-language preservation rule, and
verification target. Do not reread this whole skill unless the source type changes or the
previous source revealed an ambiguity; when the type changes, read only the relevant reference
(for example PDF conversion).

If the **output shape** is ambiguous (e.g. "10 cases" — one compiled note or ten notes?), pick
a sensible default and state it; ask only if the choice materially changes the result.

## 2. Orient

The `para-zk:*` commands below are the PARA-ZK CLI, run through whichever Obsidian CLI is on
`PATH`: `optsidian para-zk:…` when `optsidian` is installed (preferred), or `obsidian para-zk:…`
on the native CLI when it is not — the two are interchangeable. The examples in this skill use
the `optsidian` prefix; substitute `obsidian` if that is what your environment has, and keep the
same prefix for every call.

Run `para-zk:conventions` ONCE first for this task, then call `para-zk:describe` /
`para-zk:describe type=resource` as reference for the create command + inputs. Use the returned
invocation style for every call. Identify the note(s) to link from (area / project / resource).

## 3. Gather

- **Local file** → read it.
- **Single URL** → fetch it.
- **Web research** → search authoritative sources, cross-check facts, collect citations
  (prefer primary/official sources; for papers, arXiv/DOI).

**Prefer a clean HTML/source rendering when one exists** — no extraction step, and exact
text, math, and citations. For arXiv papers, try the HTML view (`https://arxiv.org/html/<id>`
or `https://ar5iv.org/abs/<id>`) first; if citations/bibliography come through unresolved
(`\cite{...}`, keys like `[zhang2022kinematic]`, `\printbibliography`, missing References),
fetch the arXiv source bundle and use its `.tex`/`.bbl`/`.bib` to restore numbered citations
and the bibliography.

If the source itself is a PDF, or no clean HTML/source rendering exists, read
[references/pdf.md](references/pdf.md) before converting. Convert PDFs with marker via the
bundled script, then treat marker Markdown as a **draft**: repair residual extraction glitches,
attach useful extracted figures, and drop duplicate/debug images before applying the transform.

If the source, converter output, or draft contains LaTeX, read
[references/latex.md](references/latex.md) before drafting. Its compatibility rewrites and
renderer checks are mandatory even for a faithful import: equivalent LaTeX may change in order
to preserve the mathematics as Obsidian actually renders it.

Record source provenance for everything (URL, file path, identifier, date, license/permission
where relevant). The four core fields go in the resource **frontmatter** at create time (see step 6):
`url`, `first_author`, `license`, `kind` — `license` as an SPDX identifier (short recognizable
token like `arXiv` when none fits, never a long sentence), `kind` as a concise free-form source
classification. Keep any extra detail
(DOI, version, other URLs) in a short body provenance section only when useful. Do not add routine
transform notes such as "translated", "converted", or "cleaned" unless the user explicitly asks for
that metadata or it is needed to avoid ambiguity. For images:
- A **web** image → embed it by its source URL with `![alt](https://…)`; Obsidian renders
  remote images inline, so do **not** download or attach it. For HTML/web sources, preserve or
  absolutize the image URL; do not rewrite it into a vault wikilink such as
  `![[assets/<slug>/figure.png]]` unless the user explicitly asked for offline/local assets.
- A **local** image — from a local-file source, or a figure `marker` extracted from a PDF →
  `optsidian para-zk:attach-file source=<abs-path> folder=assets/<slug>`, then embed only the
  returned `![[…]]`. Never invent an `assets/...` path by hand.

## 4. Produce clean Markdown — never a raw dump

Apply the transform faithfully, and always make the form tidy:
- **Faithful import** → preserve the source language, meaning, intent, argument, and structure.
  Do not summarize or introduce new claims. Normalize surface wording, Markdown, and equivalent
  notation where necessary to remove conversion artifacts or make the intended content render
  correctly in Obsidian; exact bytes and incidental source syntax are not the preservation target.
- **Translation** → faithful full-source translation, same structure; cite the original source.
  Do not summarize, abridge, or omit sections unless the user explicitly asked for that. Do not
  add a visible translation label, title postfix, or transform note unless the user asks for one.
- **Research / compile** → gather across sources and organize into clear sections, applying
  the chosen transform to the content (faithful source-language rendering, translation, or summary); attribute
  facts to their sources; mark anything uncertain or unverified; do not invent. (This compiles
  a resource from research; cross-source knowledge synthesis is still the LLM-Wiki's job in
  step 8.)

For translation requests, do the translation **yourself**, in context — never route the text
through an external machine-translation engine or tool (Google Translate, DeepL, a translation
API or `trans`-style CLI); only your own translation can apply the rules below, and a generic MT
pass yields translationese and mangles terminology, math, and citations.

Preserve the source's structure, argument flow, and domain precision, but write natural
target-language technical prose. A translation is **not** transliteration, and not source
language with target-language particles attached. Keep the source-language form only for
source titles and identity-bearing technical names: paper/book/article titles,
model/method/architecture names, dataset and benchmark names, standard acronyms/initialisms,
proper nouns, symbols, units, code-/API-facing identifiers, citation keys, URLs, and method
names (e.g. *Attention Is All You Need*, *Diffusion Policy*, *ResNet*, *ImageNet*, *MMLU*).
Also keep the handful of ordinary terms the field itself conventionally writes in the **source
script** even though a target word exists (for ML, e.g. *epoch*, *gradient*, *baseline*,
*advantage*, *rollout*).

Translate ordinary prose and non-identity terms into the field's settled target-language form:
common nouns, verbs, adjectives, and explanatory phrases should not remain in
the source language just because the topic is technical or near a formula. Use the target
field's standard word (observation, demonstration, learning, policy, action, task, inference,
success rate, manipulation) or, where the field writes a loanword, its standard transliteration
(benchmark, embedding, minibatch). For ordinary prose, **when unsure, translate**. For
identity-bearing names, preserve the source form.

**Decide each recurring term once and apply it uniformly**; never alternate between the source
word and its translation for the same concept. Inflect the sentence naturally around any kept
source term rather than producing translationese. Do not invent terminology, over-localize,
simplify beyond what was asked, or add bilingual glosses. Preserve equations, symbols, citations,
tables, and figure references unless instructed otherwise. Keep citation markers in the body
(`[27]`); resolve bare citation keys back to the paper's numbered form, and do not rewrite
`introduced in [27]` as "Zhang et al." unless the source itself does.

Preserve the full source title in the H1, alias, or provenance as requested. When a heading
contains an identity-bearing source title, model/method/architecture name, dataset/benchmark
name, acronym, proper noun, symbol, or code/API identifier, preserve that named object in source
form. Do not infer translation style from existing vault notes unless the user explicitly names
a note as the style reference; use these rules and the source text as the standard.

Across all of them: real headings (`#`/`##`), valid Markdown tables (no empty cells, no
equations trapped in cells), LaTeX normalized according to
[references/latex.md](references/latex.md), figures embedded (web images by URL, local images
attached), boilerplate dropped, and any dead intra-document **page-anchor scaffolding** stripped.
Empty `<span id="page-N-M"></span>` anchors and the `[text](#page-N-M)` links that point at them do
NOT resolve in Obsidian (the link renders as a dead "page-N-M not found" link), so strip every such
anchor and delink every `[text](#page-N-M)` to its plain visible text
(`그림 [1](#page-0-0)a` → `그림 1a`; a `[Author et al.](#page-13-0)` citation →
`Author et al.`); a heading-embedded anchor also breaks PARA-ZK's `#heading` citation matching.
Source provenance lives in the frontmatter (step 6);
only when there is useful overflow detail beyond `url`/`first_author`/`license`/`kind` (DOI,
version, extra URLs) add a short **Source / provenance** section at the top — otherwise omit it.

For faithful imports and translations, include the source's own References/Bibliography section
in the body unless the user asks to omit it. Preserve bibliography entries in their original
bibliographic form, including paper/book titles; do not translate cited work titles inside
References. Numbered in-text citations and bibliography entries (`[1]`, `[2]`, …) stay plain text
— keep each entry as its own plain line `[1] …`. Never write them as a `- [1]` list item:
Obsidian renders `- [x]` whose bracket holds a single character (so `- [0]` through `- [9]`) as a
task checkbox, silently turning a bibliography into a to-do list. These are the source's content,
not the note's reference registry — do **not** copy them into PARA-ZK `references`. That registry
holds only the connections the vault owner deliberately curates (the area/project it belongs to,
related vault notes); leave it to them to register the few they want, as `[[wiki]]` links to notes
they actually keep.

## 5. Correction & verification pass — DO NOT SKIP

Before storing, re-read each draft and repair conversion artifacts, broken/empty table cells,
stray HTML, duplicated headers, dangling markers, bad math delimiters, and broken figure embeds.
The note must read as hand-written, not auto-generated.

For translations, do not treat artifact checks as quality checks. Compare the source and
translated draft for coverage: title, authors, abstract, every section/subsection, tables,
equations, figures/captions, appendices, acknowledgments, and references. Confirm that ordinary
prose is target-language, identity-bearing names are preserved, and References titles remain in
the source language. If the result reads like source-language sentences with target-language
particles, rewrite it before storing.

For long translations, quality-sample the **beginning, middle, and end** before storing. The
translation quality must be consistent across the whole source; a polished abstract/introduction
does not compensate for later sections reverting to source-language phrasing. If a sampled later
section is weaker than the opening, continue the revision pass from that point onward and sample
again.

Run a source-language residue scan on the translated draft before storing. Search for common
ordinary terms that agents often over-preserve in technical prose (for ML papers, terms such as
`model`, `layer`, `network`, `input`, `output`, `position`, `sequence`, `training`, `task`,
`dataset`, `performance`, `method`, `approach`, `result`, `experiment`, `figure`, `table`,
`section`, `sentence`, `token`, `feature`, `fine-tuning`, `pre-training`, `learning rate`, and
`batch size`). Each hit must be either an identity-bearing name, code/API identifier, table label
that is intentionally preserved, or a field-conventional source-script term; otherwise translate
it into natural target-language technical prose. This scan is a whitelist-or-translate check, not
a blanket ban on source-language terms.

For drafts containing LaTeX, run the complete automated compatibility preflight in
[references/latex.md](references/latex.md) and resolve every non-exempt match before storing.

## 6. Store (shell-safe) and link

For each resource, write the cleaned body to a temp file and create it with a file-backed body
(avoids shell-mangling of long/multiline content; use an absolute path), recording provenance in
the structured frontmatter:

For a paper resource title / filename, use the source's full title by default. Use a short title
only when the source is widely identified by the model, method, dataset, benchmark, standard, or
acronym it introduced (`Transformer`, `BERT`, `GPT-3`, `T5`, `DPO`, `RAG`), or when the source
title itself names the work in a `Name: descriptive subtitle` form (then use `Name`). Preserve the
full original source title in the body metadata/provenance. Do not invent a new abbreviation; if
no recognized representative name exists, use the original title.

```
optsidian para-zk:create-resource title="<title>" body=@/tmp/<file>.md \
  url="<source url>" first_author="<first author>" license="<SPDX id>" kind="<source kind>" \
  domain="<subject domain>"
```

Inspect the command result's `created` field. If it is `false`, do not repeat
`create-resource`: the existing note was returned unchanged. Read its
frontmatter and body first. If it represents the same source and the user
requested a refresh, update the body and provenance intentionally with
`para-zk:update-resource` (`key=body`, then `frontmatter/url`,
`frontmatter/first_author`, `frontmatter/license`, or `frontmatter/kind` as
needed). If it is unrelated, choose a distinct title. Never silently overwrite
an unrelated existing note.

`license` is an SPDX identifier (`MIT`, `Apache-2.0`, `CC-BY-4.0`, `CC-BY-SA-4.0`, `CC0-1.0`, …); when
no SPDX id fits use a short recognizable token (e.g. `arXiv` for an arXiv-default paper), never a long
descriptive sentence. `kind` accepts any concise string; common values include `paper`, `article`,
`book`, `video`, `web`, `code`, and `guide`, while more specific values such as `repo-fork`, `vault`,
`tool`, or `dataset` are valid. `domain` is the subject group for the identity
tag — reuse an existing domain vocabulary; omit it for a flat resource tag. Omit any field you cannot
determine — don't guess.

Then link as requested. To make an existing note reference a resource — e.g. "add a ref to the
AI area":

```
optsidian para-zk:update-area title="AI" key=references op=insert value_json='{"link":"[[<resource title>]]"}'
```

For a child receiver, use `para-zk:update-child root_type=<project|area> root_title="<root>" relpath='<ancestors>' title="<child>" key=references op=insert value_json='{"link":"[[<resource title>]]"}'`.

For multiple resources (per chapter, per item), create each and link them into the requested
hub — an area, a project, or an index resource — so the set is navigable.

## 7. Verify

Run `para-zk:read-resource title="<title>" key=frontmatter` and `key=body` after creation or an
intentional same-source refresh. Confirm
metadata, body persistence, backlinks/references when linked, and no dead page anchors. For any
note containing LaTeX, complete the final renderer verification in
[references/latex.md](references/latex.md); fix the stored note and repeat that verification if
anything is still broken. Also verify every image embed: web/HTML-origin figures should be remote
`![alt](https://…)` links, and every local `![[…]]` image/PDF must have been produced by
`para-zk:attach-file` and resolve in the vault.

## 8. Hand off to the wiki-ingest skill

`wiki-ingest` is a **skill, not a CLI command** — there is no `optsidian wiki-ingest` or
`obsidian wiki-ingest`. After
every accepted resource in this import has been created or intentionally refreshed, linked, and
verified, **invoke the `para-zk:wiki-ingest` skill** once for the whole accepted set: read its
`SKILL.md` and carry out
its workflow yourself (or run the `/para-zk:wiki-ingest` slash command), background /
session-scoped. The inputs to that skill are:

```text
mode=per-import source_paths='["<accepted resource path>","<accepted resource path>"]'
```

(these are skill inputs, not shell arguments — do not pass them to `optsidian`). Include exactly
one final accepted path per requested resource: newly created notes and intentionally refreshed
same-source notes belong in the list; rejected `created:false` collision results do not. The
wiki-ingest skill itself plans the whole imported set and spawns the `wiki-weaver` subagents; do
**not** spawn `wiki-weaver` yourself, and do **not** invoke wiki-ingest once per file — one
`per-import` hand-off covers the entire set.

## Examples

- `find the paper "Attention Is All You Need", translate it to Korean, and add it as a resource`
  → web research → arXiv → title `Papers/LLM/Transformer` because the paper introduced the
  Transformer architecture and is widely identified by that representative name → full Korean
  translation with source title preserved and References titles left in English.
- `read /path/to/report.html and add it as a resource translated to Korean`
  → local file → translation → one resource (cite the original).
- `add a resource per chapter following a study path for "Principles of Statistics"`
  → research/compile → several per-chapter resources → linked from a study area/index.
- `find every Seoul subway line and write one organized resource`
  → web research → structured write-up with sources → one organized resource.

## Notes

- Prefer `para-zk:describe` / `<command> help=true` for exact argument names over assuming.
- `body=@<file>` is read by the plugin, so it works through optsidian and the native `obsidian`
  CLI alike; pass an **absolute** path.
- Keep `title` stable — links and backlinks address notes by name.
- The final hand-off invokes the `para-zk:wiki-ingest` **skill** (not a CLI command) once,
  background / session-scoped, with `mode=per-import` and all accepted created-or-refreshed
  resource paths in `source_paths`, excluding rejected collision results.