Priorwork guide

Literature reviews for the social sciences and clinical research, handed to your AI agent — no terminal needed

Priorwork is a toolkit for having an AI agent (Claude Code, Antigravity, …) write topic-based reviews of the prior work in economics, sociology, political science, public administration, management, psychology and neighbouring fields. Give it the topic: the agent sets the scope, finds and selects the literature, fills in a card for each paper, writes the review, checks it and exports a version for reading. You read the result, then check and correct it in the VS Code sidebar.

This guide is for people using VS Code: everything here is a button, a menu or something you say to the agent.

• Not installed yet: Installing Priorwork
• In a hurry: the quick guide
• From your own manuscript, and with Octavo: Starting from a manuscript
• Everything else, every command the agent runs, is in the reference, written for AI agents. Ask the agent for anything without a button here.

日本語の手引き

1. Introduction

1.1 What it does

• Hand it over. Ask “review the literature on X” and the agent carries on from the scope to the export. You choose where it stops for you to check (standard, full auto, manual). There are no commands or skill names to learn.
• Start from your manuscript. Give it a manuscript in any format, finished or not, and get one report: what to add and where, a check of its citations, the literature it does not mention, comments on the argument (more).
• Find the literature. English keyword search in Semantic Scholar (by relevance, or a boolean bulk search), with DOIs, journals and ISSNs checked against OpenAlex. The references and citing papers of the included papers are followed to catch what keyword search misses.
• Make paper cards. For each included paper, a card with the research question, the explanatory variable, the outcome, the data, the identification strategy, the findings and the limitations. A comparison matrix is built from the cards.
• Catch fabrications. Every “Author (year)” in the text must match a registered paper, and every DOI the right paper; this is checked mechanically.
• Export for reading. HTML (or Word or Markdown) without the markers and empty fields, viewable inside VS Code — on a server over SSH too.
• Check and correct. Every decision and its reason, every card and every search is recorded. On each paper’s page in the sidebar you can overturn decisions and correct cards.

1.2 Hand it over, then check

The agent decides the scope and each paper on its own, but always leaves the reason, and writes the scope into the report. Cards hold only what the abstract or the full text says, with the evidence it was checked against. You read them and correct whatever you disagree with; the agent follows your corrections in the next round.

You choose where it stops for you to check. In the standard mode it stops twice: once the scope is set, and before writing the cards (so that you can collect the papers in Zotero). Full auto never stops, and manual stops after every step (3.6). You can also search and screen from the sidebar yourself (4).

The extension never calls an AI service itself. AI help comes only through the agent you already use.

1.3 What you need

2. Create a workspace

A workspace is the folder that holds the reports of your surveys and their state. One workspace holds any number of surveys. It is kept in a private GitHub repository.

2.1 Create it

1. Open an empty folder (or nothing at all) and press Create a Workspace in the sidebar.
2. Choose where, and the language of the reports (English or Japanese). The language cannot be changed later: it is the language of the report headings and of the instructions for the agent (AGENTS.md and the skills).
3. The extension creates a .venv, installs priorwork from PyPI and sets the workspace up (including git init).

2.2 Set it up

Open the gear in the sidebar (Settings).

1. Enter a Semantic Scholar API key. Request one for free.
2. If you use Zotero, fill in the Zotero fields (7.2).
3. If you have the SSCI journal list, import it with Import the SSCI List (CSV)… (7.3).
4. Save and Check the Connections shows the diagnosis at the bottom of the page.
5. So that your agent does not ask before every ./priorwork command, allow ./priorwork in the agent:
   • When it is needed: when you hand work to the agent (ask in the chat). The agent runs ./priorwork … in the terminal for every search, decision and card, tens to hundreds of times per survey; without the permission it asks each time. The sidebar’s buttons and the ./priorwork you type yourself do not need it (they do not go through the agent).
   • What it allows: only commands starting with ./priorwork. Priorwork touches only the workspace (reports/, .priorwork/) and the literature APIs; it never runs Git, and it writes to Zotero only if you allow it (7.2). Other commands are still checked.
   • Claude Code: automatic. Making the workspace (and every priorwork sync) adds Bash(./priorwork:*) to the allowed rules in .claude/settings.json, keeping your other settings. To stop it, move the rule from allow to deny (just removing it, the next sync adds it back; it is not added while it is under deny).
   • Antigravity: it has no settings file in the workspace, so this cannot be automatic. Add ./priorwork once to the terminal commands allowed to run without review in its settings (the allow list; the menu names differ between versions). Other commands are still checked.

The settings are saved in the workspace’s .env, which is kept out of Git. The page never shows the values of the keys.

2.3 Put it on GitHub

The reports and state files contain abstracts, so keep the workspace in a private repository.

1. Press Not on GitHub yet — publish it as a private repository in the sidebar.
2. When VS Code asks, choose Publish to GitHub private repository and include all the files it suggests (.env is left out by .gitignore).

The agent makes a branch named after the survey (e.g. 20261015_statutory_text_analysis), commits and pushes at each step, and opens a pull request once the report is exported. It never merges: review the pull request and merge it on GitHub. In Claude Code, pushing to main, force-pushing and merging are also denied in .claude/settings.json. To keep the agent away from Git, say so in AGENTS.local.md.

2.4 Continue on another machine

1. Clone the repository in VS Code and open it.
2. Run Set Up the Python Environment (.venv) from the sidebar’s menu (…).
3. Enter your keys in the Settings again (.env is not in Git), and import the SSCI list again.

3. Hand it to the agent

3.1 Ask

With the workspace folder open, ask in your agent’s chat, in either of two ways:

• Ask in your own words in the chat. For example: “Do a full review of how government organisations staff up when demand for their services changes, from a make-or-buy angle.” There is no need to type commands or skill names (typing /priorwork works too).
• Ask from the sidebar. New Survey → Ask your agent to do it, give the topic in your own words and choose the depth and the mode; a request is copied. Open the chat with Open Claude Code (or similar) in the notification and paste it.

If you already have a research question, a period or criteria, add them to the request. Otherwise the agent decides them from the topic; in the standard mode it shows you the scope it decided and waits (in full auto it says what it decided in its final report).

3.2 What the agent does

The agent follows the workspace’s AGENTS.md and skills, in this order. ⏸ marks where the standard mode stops for you to check (3.6):

① scope ⏸ → ② search → ③ screen → ④ chase citations → ⏸ collect in Zotero
  → ⑤ fill in the cards → ⑥ write → ⑦ check and export

1. Scope: decides the research question, period, fields, inclusion and exclusion criteria and depth, and creates the survey.
2. Search: splits the topic into subtopics and searches with English queries, rephrasing those that find nothing.
3. Screen: sorts the candidates into included, maybe and excluded against the criteria, with a reason for each.
4. Chase citations: picks up papers missed by keyword search from the references and citing papers of the included ones, and screens them. In the standard mode it then stops and shows the DOIs to add to Zotero (3.7). Collect the papers and their PDFs in Zotero and say “carry on”: the cards can then be written from the full texts.
5. Cards: fills in the cards of the included papers from the full text (a PDF in Zotero or an open-access version) or the abstract.
6. Text: writes the background, the literature’s theories, methods, debates and gaps (citing the included papers for each claim), and, kept apart from them, the hypotheses and implications for your study, from the cards.
7. Check and export: checks citations, DOIs, empty fields and whether the cards match the full texts, fixes them, and exports the version for reading (HTML). At the end it reports the numbers searched and included, the parts of the scope it decided itself, what is left to look at, how many included papers are not in Zotero yet, and how to view the report. It names papers as “Goldschlag & Tabarrok (2018)”, not by numbers such as #232. Since this takes a while, it may tell you where it is in one line along the way (except at the stops, without waiting for an answer).

Audit (optional). To have another model check the survey too, ask that model (e.g. Claude if Gemini wrote it) in its chat to “audit the survey ” (Ask Your Agent… → Audit as another model copies the request), since a model rarely catches its own misreadings. The auditor compares every card with the full text, checks the direction of each citation, hypotheses passed off as the literature and the excluded papers, fixes them and records the audit (the model that wrote the survey cannot audit it). Without an audit, a survey is not left unfinished.

3.3 Depth

The depth is a guide to the size of the survey. If the request says “quick”, “an overview”, “full” or “thorough”, the agent follows it; otherwise it decides from how broad the topic is.

When a full survey has too few searches, Search more appears in the Next steps in the sidebar. The agent sees it too and adds searches.

3.4 View the report

Open the version for reading (HTML) inside VS Code. It works the same on a server reached over SSH.

• Right-click the survey in the sidebar → Export and View the Report.
• Right-click reports/<name>.html in the Explorer → View the Report in Priorwork.
• When the agent exports it, click View in the notification.

You can select and copy the text, and search the page with Ctrl+F (Cmd+F on a Mac).

While cards are unchecked or empty, or the check reports ERRORs, it is marked Draft at the top. On a local machine you can also open it in the browser and print it to PDF.

3.5 Check and correct

Under each survey in the sidebar are its included, maybe, excluded and unscreened papers. Click a paper to open its page.

• Decisions: read the abstract and the reason the agent left. To overturn it, press I include, M maybe or X exclude (with a reason). Select several papers in the sidebar and right-click to change them at once.
• Cards: on an included paper’s page, compare the card with the abstract, correct it and press Ctrl+S to save.
• Scope: change the research question, the criteria or the depth with Edit the Scope (right-click the survey).

The agent never overturns your decisions or corrections. After correcting, ask it to “carry on” and it works from there.

3.6 Choose the mode, ask for more

The mode decides where the agent stops and waits for you to check.

Standard is the default because when the included papers and their PDFs are in Zotero before the cards are written, more cards are checked against the full texts, which saves work in the end. Between the stops, the agent decides on its own and records its reasons.

The mode is recorded in the survey, so the next conversation carries on in the same mode. To always use one mode, write it in the workspace’s AGENTS.local.md (e.g. “Mode: full auto”). New Survey → Ask your agent to do it in the sidebar lets you choose it too.

• More: ask in the chat — “carry on”, “search more”, “fill in the cards”. Saying “carry on” where it stopped tells it you are done checking. Ask Your Agent… (right-click the survey) also copies requests for the common jobs: carry on, carry on to the end, search more, screen, chase citations, fill in the cards, write the text, check and fix, and audit as another model.

• Redo: ask “redo this survey” and the agent makes a new one with the same slug; Priorwork numbers it right after the date (20261012_v2_<slug>) and the sidebar shows v2. When surveys share a topic, the sidebar also shows their names and dates side by side. Once you no longer need the old one, right-click it → Archive the Survey… (or ask the agent). It leaves the list for the Archived group at the bottom; nothing is deleted, and the button on it brings it back.

When you come back to a conversation, “let’s continue” is enough: the agent checks the state and takes the next step.

3.7 Collect the papers in Zotero

You add the papers, unless you let Priorwork do it (below). Two things make it easier (for setting up Zotero, see 7.2).

Add the included papers’ DOIs to Zotero at once.

1. In Zotero, select the collection (folder) the papers should go into.
2. Click Add … to Zotero in the next steps of the sidebar and Copy the DOIs (or ask the agent for “the list of DOIs to add to Zotero”).
3. Paste them into Zotero’s Add Item by Identifier (the magic wand) and press Enter. They go into the selected collection.
4. Click Reload from Zotero to update the status.

In the standard mode, the agent stops before writing the cards and shows you this list of DOIs. The next steps in the sidebar show Stop here and wait for the user too; click it to copy the DOIs, and the request asking the agent to carry on. The list of DOIs works without the Zotero link too (it then lists every included paper).

Or let Priorwork add them. If you allow it in the settings (7.2) and link a collection to the survey (below), Priorwork puts the included papers into that collection itself:

• An item already in your library (same DOI, or the same title) is added to the collection; otherwise a new item is made from the bibliographic data. Priorwork never changes or deletes your items, never touches other collections and does not make collections.
• Add … to the Zotero collection in the next steps shows the list first and adds it once you confirm. The agent does the same: in the standard mode it shows you the list at the stop before the cards and adds it when you agree; in full auto it adds without stopping; in manual it asks each time.
• No PDFs come with the items: select them in Zotero, right-click → Find Full Text.
• Undo What Priorwork Added… (or asking the agent to undo it) takes back only what Priorwork wrote. Items it made go to the Zotero trash, except those you changed or attached a file to since; items that were already in your library only leave the collection.

Link a Zotero collection to the survey. Under each survey in the sidebar, click Link a Zotero collection… and choose a collection you made in Zotero (without the Zotero link it reads Zotero: not set up and opens the settings page). Priorwork does not make collections, so make a new one in Zotero (right-click “My Library” → New Collection…) and bring it in with Reload the list. The list is the same tree as in Zotero, and papers in a collection under it count as in it (when the same name is under two parents, the path parent / child tells them apart). Then choose it (or tell the agent “use my Zotero collection X”). The row then reads Zotero: ; click it to change or unlink it. Once linked:

• “In Zotero” means in that collection.
• Papers you put into the collection yourself can be registered as candidates (Register … papers from the Zotero collection in the next steps). The agent includes them unless they are clearly out of scope.
• Full texts come from the PDFs in that collection first.

3.8 Short texts from a survey

You can also ask for a short text based on a survey: a lecture handout, reading notes, a summary of the main points (“a lecture handout from this survey, in three parts, about 2,000 characters”, say). The agent records its purpose, length and structure and writes it in reports/<name>.<text name>.md. It sits beside the survey’s files, so it goes into Git with them.

• It cites included papers whose cards were checked against the full text, and checks numbers and the direction of findings against the cards.
• The length leaves out citations in parentheses (“(Dell 2010)”) unless you say otherwise.
• The references at the end are made from the papers it cites.
• Check the Survey reports citations that are not included papers (ERROR), citations from cards not checked against the full text and numbers that are not in the card (WARN), and a length off the target (INFO).
• Its version for reading is reports/<name>.<text name>.html (Word too, if you ask).

3.9 Medical surveys

For clinical research, say so when you ask (“a review of the clinical evidence on …”), or choose Medicine (clinical research) in New Survey. The survey then:

• searches PubMed as well as Semantic Scholar, and leaves out letters, editorials and comments;
• shows each paper’s study design, and whether PubMed has indexed it for MEDLINE;
• has cards for the clinical question, population, intervention or exposure, outcomes, study design and effect sizes;
• has a report with sections on the evidence by study design, effects, and safety and harms;
• marks retracted papers, and will not pass the check with one included;
• reads open full texts from PMC.

It is a narrative review. One agent’s screening does not meet the standard of a systematic review or PRISMA, and the report says so. It is not clinical guidance. Ichushi-Web (医中誌), Embase and CENTRAL are not searched.

Optional, in Settings: a free NCBI key makes PubMed faster, and the SCIE list from the Master Journal List adds ✅ SCIE. The two kinds of survey can live in one workspace.

3.10 Several surveys at once

To start a survey while another is in progress, say so: “start this in its own folder, another survey is in progress”. The agent makes a folder under worktrees/ on the survey’s own branch, without touching the survey you have open. Your keys, journal lists and fetched full texts are shared.

The sidebar lists such surveys. Click one to open its folder in a new window, and carry on there. When its pull request is merged, ask the agent to remove the folder; it refuses while anything is not committed and pushed.

4. Doing it yourself

You can also work from the sidebar yourself instead of handing it to the agent. Next steps, under each survey in the sidebar, says what to do now; click an item to start it.

4.1 Set the scope

New Survey → Set it up myself asks for the topic, an English slug (the file name, e.g. minimum_wage_employment), the depth and the research question. Add the period, the fields and the inclusion and exclusion criteria later with Edit the Scope (right-click the survey). The criteria are shown at the top of each paper’s page.

4.2 Search

Search asks for an English query and how to search:

• Search: Semantic Scholar’s relevance search (20 results).
• Bulk search: + (and), | (or), - (not) and "phrases", most cited first (25 results). It finds the classics that keyword search buries. AND, OR and NOT are turned into +, | and -.
• SSCI journals only: the relevance search, keeping SSCI journals only.

The results are registered as candidates. When both a working paper and its published version are found, only the published one is kept; books, working papers, preprints and papers with no known venue are left out by default. A paper whose DOI you already know is added with Add Papers by DOI.

To search only certain journals, ask the agent (“search JPART and PAR only”). A search narrowed to journals looks in both Semantic Scholar and OpenAlex: Semantic Scholar often has no journal name for a paper, so a search there alone silently misses it — sometimes the most cited papers of the field. OpenAlex picks the journal by its ID, so it finds them, and what it adds is said in the notice.

4.3 Screen

Screen Candidates opens the page of the first unscreened paper.

• At the top, the survey’s inclusion and exclusion criteria; below, the title, the authors, the journal and its SSCI status, citations, warnings and the abstract.
• I include, M maybe, X exclude (type the reason first), U back to candidate. After a decision it moves on to the next unscreened paper (setting priorwork.autoAdvance).
• N next unscreened, J / K next / previous, O open the DOI in the browser.
• Reasons you used before are offered as buttons.

Check papers with a warning (⚠️) before including them.

When Semantic Scholar gives a journal paper the DOI of its preprint or working paper, Priorwork looks the title up in OpenAlex and, if the journal version matches (the same title, the year within two years), takes its DOI and details. The paper then shows a note (ℹ️) with the old DOI instead of a warning.

4.4 Chase citations

Chase Citations collects the references and citing papers of the included papers from OpenAlex and registers them as candidates, ordered by how many included papers each is linked to. With three or more included papers, only those linked to at least two are taken by default. Screen them as in 5.3.

4.5 Fill in the paper cards

Each included paper gets a card in the section “The papers” of the report. Write it on the paper’s page and press Ctrl+S to save. Get the Full Text brings in the full text (5.3). To hand only the cards to the agent, use Ask Your Agent… → Fill in the paper cards. Section 5 describes the cards.

4.6 Write the text

The report puts the synthesis first: the background (section 1); the literature’s theoretical traditions, methods, consensus and debates, and gaps (sections 2–5, each claim citing included papers); and the hypotheses and implications for your study (section 6, kept apart from the literature). The comparison matrix, the paper cards and the references follow. These sections are text written from the cards, and each says under its heading what to write (reports made up to 0.1.5 keep their older order). Mermaid diagrams (```mermaid) are drawn in the HTML. Open the report with Open the Working Report (Markdown) on the survey and write it, or ask the agent with Ask Your Agent… → Write the text of the report.

4.7 Check and export

1. Check the Survey lists the problems in VS Code’s Problems panel (6).
2. Export and View the Report opens the version for reading (HTML) (3.4).

5. Paper cards

5.1 The fields

### #1 Acemoglu et al. (2001): The Colonial Origins of Comparative Development
- Source: American Economic Review 91(5) | ✅ SSCI | cited by 8534 | DOI   ← automatic
- Evidence: unchecked / abstract only / full text checked
- RQ: Do institutions cause the differences in income between countries?
- X (explanatory variable / treatment): the quality of today's institutions
- Y (outcome): GDP per capita in 1995
- Data / sample: 64 former colonies
- Identification: 2SLS, with settler mortality as the instrument
- Main findings: better institutions raise income substantially
- Limitations: measurement error in the mortality data
- Notes:

• The heading and the source line are generated. You (or the agent) write from the evidence level to the notes.
• The first line of each field goes into the comparison matrix, so keep it to one short sentence; details go on the lines below it, which become bullet points.
• Write only what the abstract or the full text says. If it says nothing, write “not reported”.
• Write the cards in the language of the report, keeping terms in the original in brackets.
• On a card checked against the full text, give the page ((p. 12)) for the data, the identification and the main findings, or “(page not checked)” when the full text has no page breaks.

5.2 The evidence level

Unchecked cards are flagged by the checks, and the export is marked Draft. In a full survey, every included paper is checked in the full text; a card may stay “abstract only” only when no full text could be found, and the checks list those papers so that you can attach their PDFs in Zotero.

5.3 Full texts

Get one with Get the Full Text on an included paper’s page or from the paper’s context menu in the sidebar (the agent gets them the same way). PDFs are never stored in the workspace; only the extracted text is kept, in .priorwork/cache/fulltext/ (outside Git). Priorwork looks in this order:

1. a PDF attached in the local Zotero (matched by DOI)
2. a PDF attached in Zotero found through the Web API (WebDAV or Zotero’s own file sync), preferring the collection linked to the survey
3. the text Zotero indexed (no page breaks; a fallback)
4. an open-access PDF (every location OpenAlex knows; on a landing page, such as an institutional repository’s, the PDF link it gives)

Publishers usually refuse automated downloads, so for papers that are not open access, attach the PDF in Zotero first.

5.4 When a paper is no longer included

Its card is kept, with what was written, in the state file, and comes back if the paper is included again.

6. Checks

Check the Survey looks at:

Citations are found with regular expressions, so not every style is caught. Acemoglu et al. (2001, 2005), Dell (2010, p. 5) and (e.g., Dell 2010; Acemoglu et al., 2001a) are. Organisations such as “World Bank (2010)” or “OECD (2019)” are reported as INFO. Something that is not a citation can be excluded with a comment in the report:

<!-- priorwork:ignore-citation Smith (2015) -->

7. Settings

7.1 API keys

7.2 Zotero

With Zotero set up, Priorwork shows which included papers are in Zotero, links a collection to a survey (3.7) and gets full texts from the PDFs attached there. By default it only reads: it never writes to Zotero or WebDAV.

1. Create an API key at https://www.zotero.org/settings/keys with only “Allow library access” (no notes, no write access). “Your user ID for use in API calls” on the same page is the user ID.
2. Enter the key and the user ID under Zotero in the settings. If Zotero runs on this machine, enter its data folder too (default ~/Zotero).
   • To let Priorwork add the included papers to the survey’s collection (3.7), check Let Priorwork add the included papers to the survey’s collection (ZOTERO_WRITE=1 in .env) and also check Allow write access for the key on the Zotero page. Both are needed; Save and Check the Connections tells you whether the key can write.
3. If Zotero syncs its files through WebDAV (Nextcloud and the like), enter under Zotero file sync through WebDAV the URL of the folder that holds the PDF zips (the URL set in Zotero plus zotero/), the user name and the password. With Nextcloud, share the zotero folder read only with a dedicated user and use that user’s app password.
4. Check with Save and Check the Connections.

If WebDAV reports “folder not found”, check the URL. With Nextcloud under a sub-path, include that path (e.g. https://example.com/nextcloud/remote.php/dav/files/<user>/zotero/).

7.3 The SSCI journal list

Only Clarivate’s Master Journal List settles whether a journal is in the SSCI. Download the SSCI list there as CSV (a free account is needed) and import it with Import the SSCI List (CSV)… in the settings. The list is copied to the workspace’s .priorwork/data/ and stays out of Git under its licence. Without it, the status is guessed from a built-in list of about 100 major journals.

For medical surveys, the SCIE list from the same site can be imported the same way (Import the SCIE List (CSV)…). It adds ✅ SCIE; without it, journals are judged by PubMed’s record of each paper.

7.4 VS Code settings

8. Instructions for the agent

8.1 AGENTS.md and the skills

The workspace carries instructions for agents (AGENTS.md) and a skill for each step (.agent/skills/, also seen through .claude/skills/). The entry point is the priorwork skill: it looks at the state and goes on to the skill of the next step (priorwork-new, priorwork-screen, priorwork-snowball, priorwork-extract, priorwork-check). To start from a manuscript, it uses priorwork-manuscript (Starting from a manuscript). The agent picks them from the words of your request, so there are no names to remember.

Instructions for one workspace only (fields to prefer, writing style, journals to leave out, “Mode: full auto”, …) go in AGENTS.local.md. AGENTS.md and the skills are rewritten to match the engine’s version; do not edit them.

8.2 What the agent keeps to

• It leaves a reason for every decision and for the scope, and never overturns your decisions.
• It stops where the mode says, and decides on its own in between.
• In its reports it names papers as “Author (year)”, not by number.
• Every paper mentioned in the text is registered; it never writes authors, years or DOIs from memory.
• Cards hold only what the abstract or the full text says, with the evidence level updated.
• It replaces papers with ⚠️ by their published versions, or sets them to maybe and tells you. It never calls a 🟡 (guessed) journal “in the SSCI”.
• It runs the checks before calling anything finished.
• It never opens the files of Priorwork itself (inside .venv).
• It writes to Zotero only when you allow it (it adds the included papers to the survey’s collection). In Git, it commits and pushes on a branch named after the survey and opens a pull request; you merge.

9. Inside a workspace

my-surveys/
├── reports/                 # the reports (the working .md, the exported .html, the manuscript drafts .draft.md, …)
├── manuscripts/             # manuscripts to start from, with their tables (one folder per paper; only read)
├── AGENTS.md, CLAUDE.md     # instructions for agents (updated automatically; do not edit)
├── AGENTS.local.md          # instructions for this workspace only (edit freely)
├── .agent/skills/           # the skills for each step (also seen through .claude/skills)
├── priorwork                # ./priorwork (what the agent runs)
├── requirements.txt         # the engine's version (priorwork==X.Y.Z)
├── .env                     # the settings (not in Git)
└── .priorwork/
    ├── config.json          # the workspace's language
    ├── surveys/             # the state of each survey (in Git)
    ├── cache/               # full texts, the Zotero index (not in Git)
    └── data/                # the SSCI list (not in Git)

The references are generated from the included papers, with DOIs, and the appendix records the searches, the counts, the reasons for exclusion and the decisions that were revised.

10. Updating the engine

A workspace pins the engine’s version (the priorwork command) in requirements.txt, so nothing changes behind your back. After the extension is updated, it offers Update the Engine when the workspace’s version is older; that also brings AGENTS.md and the skills up to date. When only AGENTS.md and the skills are out of date, the sidebar shows a row to update them.

11. Troubleshooting

The agent asks you to type commands or skill names. Check whether the sidebar says the skills are out of date; if so, update AGENTS.md and the skills from that row. If it still asks, name Priorwork in the request: “carry on with the survey in Priorwork”.

The agent opens files inside .venv (such as i18n.py). They are part of Priorwork itself and have nothing to do with your survey. Close them, and do not edit them (updates overwrite them). The current AGENTS.md tells the agent not to open them.

Too few papers were found. Check that the depth is full (right-click the survey → Edit the Scope) and ask the agent to “search more”. Search more in the next steps of the sidebar copies a request too.

The HTML report does not open in Live Preview or similar. On a server reached over SSH, browser extensions often cannot open files on the server. View it inside Priorwork as in 3.4.

Searches stop with “rate limited (HTTP 429)”. Without a Semantic Scholar API key, requests share a public pool. Enter a key in the settings. If it still happens, wait a while and try again; Priorwork retries up to five times, waiting longer each time.

A paper cannot be registered. Papers in domestic journals (J-STAGE and the like) are often in neither Semantic Scholar nor OpenAlex. Since the target is international peer-reviewed journals, they are out of scope for now.

The Python environment cannot be set up. The output panel (Show Output in the sidebar’s menu) says why. If uv cannot be installed, install Python 3.10 or later (from python.org, for example) and run Set Up the Python Environment (.venv) again.

The sidebar says the priorwork command was not found. The workspace has no .venv yet. Run Set Up the Python Environment (.venv).

Not sure what is wrong. Diagnose the Setup checks the settings, Git and the connections at once.

Bug reports and suggestions are welcome in Issues.