erdos-problems 0.2.10 → 0.3.1

package/README.md

@@ -33,21 +33,24 @@ A short example from the first minute:
 
 ## What It Includes
 
-- a bundled snapshot of the Erdős problem atlas
+- a bundled external atlas import snapshot for provenance and seeding
 - local dossiers and workspace bundles
 - separate surfaces for public status, local route state, and verification records
 - pack-specific views where this repo already has enough structure to support them
 - an ORP-based workflow for claims, checkpoints, and run artifacts
+- a paper writer bundle mode for public-safe, citation-safe, agent-friendly drafting
 
-## Repo, npm, and Upstream
+## Repo, npm, and External Imports
 
-- the npm package is the installable CLI plus the bundled atlas snapshot, packaged dossiers, and pack assets
-- the GitHub repo is the central collaboration space for dossiers, pack packets, docs, issues, discussions, and pull requests
-- `.erdos/` is local workspace state created by the CLI; it is not the canonical public collaboration surface
-- `erdos upstream show` tells you whether you are currently using the bundled package snapshot or a workspace-local refreshed snapshot
-- `erdos upstream sync` refreshes a workspace-local snapshot from `teorth/erdosproblems` without mutating the packaged bundle
-- `erdos upstream sync --write-package-snapshot` is the maintainer path for intentionally updating the bundled snapshot in this repo
-- repo-only collaboration files can live in the public repo without shipping in the npm tarball; see the GitHub contribution guide: https://github.com/SproutSeeds/erdos-problems/blob/main/CONTRIBUTING.md
+- `SproutSeeds/erdos-problems` is the canonical public home for this project's atlas, dossiers, packs, and contribution workflow
+- the npm package is the installable CLI plus the bundled import snapshot, packaged dossiers, and packaged pack assets
+- the GitHub repo is the broader public collaboration space for dossiers, pack packets, docs, issues, discussions, PRs, and future deep research bundles
+- `.erdos/` is local workspace state created by the CLI; it is not canonical repo truth
+- `erdos import show` reports whether you are using the bundled import snapshot or a workspace-local refreshed import snapshot
+- `erdos import sync` currently refreshes an external atlas import snapshot from `teorth/erdosproblems` without mutating the canonical local dossier layer
+- `erdos import sync --write-package-snapshot` is the maintainer path for intentionally updating the bundled import snapshot in this repo
+- repo-only deep-research directories such as `research/`, `formal/`, `paper/`, `imports/`, and `analysis/` are intentionally kept out of npm by staying outside the `package.json` `files` list
+- repo-only public research can live in this GitHub repo without shipping in the npm tarball; see the contribution guide: https://github.com/SproutSeeds/erdos-problems/blob/main/CONTRIBUTING.md
 
 ## Start In 60 Seconds
 
@@ -57,7 +60,7 @@ Install:
 npm install -g erdos-problems
 ```
 
-Bootstrap a seeded problem:
+If you already know the problem you want, the fastest path is:
 
 ```bash
 erdos bootstrap problem 857
@@ -66,7 +69,7 @@ erdos sunflower ready 857
 erdos workspace show --json
 ```
 
-Seed a new problem into the current workspace:
+If you want to start from a new local seed:
 
 ```bash
 erdos seed problem 25 --cluster number-theory
@@ -74,6 +77,186 @@ erdos problem show 25
 erdos checkpoints sync
 ```
 
+## Beginner Flow
+
+This is the zero-assumption path for a new user.
+
+### 1. Install the CLI once
+
+```bash
+npm install -g erdos-problems
+```
+
+This gives you a global `erdos` command. The workspace state it creates is local to the folder you are in.
+
+### 2. Make a clean working folder
+
+```bash
+mkdir erdos-work
+cd erdos-work
+```
+
+Later, the CLI will create a local `.erdos/` directory here for workspace state, checkpoints, ORP files, and pulled artifacts.
+
+### 3. Browse everything first
+
+```bash
+erdos problem list
+```
+
+Use this when you do not yet know a problem number or cluster.
+
+### 4. Inspect one problem in plain English
+
+```bash
+erdos problem show 857
+```
+
+This shows the title, status, cluster, short statement, and research-state posture for that problem.
+
+### 5. Learn the families only after that
+
+```bash
+erdos cluster list
+erdos cluster show sunflower
+```
+
+Once you know what a cluster is, you can narrow the atlas:
+
+```bash
+erdos problem list --cluster sunflower
+```
+
+### 6. Start a workspace on a well-packaged problem
+
+```bash
+erdos bootstrap problem 857
+```
+
+What this does:
+- creates `.erdos/` in the current folder
+- activates the problem locally
+- syncs the ORP kit
+- scaffolds the workspace for the next research move
+
+### 7. Orient yourself immediately
+
+```bash
+erdos workspace show
+erdos state show
+erdos problem artifacts 857 --json
+```
+
+Use these to understand the workspace layout, current route/frontier state, and the artifact surface that already exists for the problem.
+
+### 8. Run the first honest-state sync
+
+```bash
+erdos orp sync
+erdos state sync
+erdos preflight
+```
+
+This refreshes the protocol kit, recomputes local research state, and checks whether the workspace is in a sane posture to continue.
+
+### 9. Set your continuation mode
+
+```bash
+erdos continuation show
+erdos continuation use route
+```
+
+For most new users, `route` is the right default. It keeps the loop focused on the current route instead of bouncing between surfaces.
+
+### 10. Sync checkpoints before doing real work
+
+```bash
+erdos checkpoints sync
+```
+
+This writes the checkpoint shelf and keeps the workspace history honest.
+
+### 11. Look at the actual frontier
+
+```bash
+erdos sunflower status 857
+erdos sunflower frontier 857
+erdos sunflower ready 857
+```
+
+This is where the problem becomes actionable instead of just descriptive.
+
+### 12. Drill down to the next unit of work
+
+```bash
+erdos sunflower routes 857
+erdos sunflower ticket 857 T10
+erdos sunflower atom 857 T10.G3.A2
+```
+
+That is the real research loop:
+- inspect route
+- inspect ticket
+- inspect atom
+- do the next honest move
+
+### 13. Close the loop cleanly
+
+```bash
+erdos state sync
+erdos checkpoints sync
+erdos workspace show
+```
+
+If the problem is not already deeply packaged, use one-step local seeding instead of bootstrapping:
+
+```bash
+erdos seed problem 25 --cluster number-theory
+erdos preflight
+erdos continuation use route
+erdos checkpoints sync
+erdos workspace show
+```
+
+In that flow, the seeded dossier is written under `.erdos/seeded-problems/<id>/` and enters the same state/checkpoint loop as packaged dossiers.
+
+## Daily Loop
+
+Once a workspace already exists, this is the main operating loop:
+
+```bash
+erdos state sync
+erdos preflight
+erdos continuation use route
+erdos checkpoints sync
+erdos workspace show
+```
+
+Then inspect the current frontier and active unit of work:
+
+```bash
+erdos sunflower frontier 857
+erdos sunflower atom 857 T10.G3.A2
+```
+
+After a real step, sync checkpoints again:
+
+```bash
+erdos checkpoints sync
+```
+
+The guiding rule is simple:
+- inspect frontier
+- work the next honest move
+- checkpoint at honest boundaries
+
+Initialize or resume a paper bundle:
+
+```bash
+erdos paper init 857
+erdos paper show 857
+```
+
 Archive a solved problem:
 
 ```bash
@@ -85,7 +268,7 @@ erdos archive scaffold 1008 --json
 
 | Surface | Coverage |
 | --- | --- |
-| Bundled upstream atlas | `1183` problems |
+| Bundled external atlas snapshot | `1183` problems |
 | Native packaged dossiers | `18` |
 | Sunflower pack | `20`, `536`, `856`, `857` |
 | Number-theory pack | `1`, `2` |
@@ -140,7 +323,7 @@ erdos seed problem 25 --cluster number-theory
 ```
 
 What this does:
-- pulls upstream public metadata into a workspace bundle
+- pulls external public metadata into a workspace bundle
 - includes live site review and an agent websearch brief by default
 - seeds a local dossier into `.erdos/seeded-problems/<id>/`
 - syncs state, checkpoints, and ORP automatically
@@ -161,6 +344,19 @@ erdos maintainer review problem 25 --from-pull .erdos/pulls/25
 erdos maintainer seed problem 25 --from-pull .erdos/pulls/25 --cluster number-theory
 ```
 
+### 5. Initialize a paper writer bundle
+
+```bash
+erdos paper init 857
+erdos paper show 857
+```
+
+What this does:
+- creates or resumes a paper bundle for the problem
+- writes machine-readable public evidence and section indexes
+- scaffolds claim-safe section drafts, a citation ledger, and a privacy review
+- defaults to `paper/problems/<id>/` when run inside this repo and to `.erdos/papers/<id>/` elsewhere
+
 ## Packs
 
 ### Sunflower Pack
@@ -233,7 +429,7 @@ Design rule:
 
 If you are using Codex, Claude Code, or another coding agent, the package provides:
 - canonical dossier files
-- upstream provenance
+- external import provenance when available
 - pack-aware context where it exists
 - `.erdos/` workspace state
 - ORP templates and protocol guidance
@@ -247,7 +443,7 @@ Useful commands for agent workflows:
 erdos problem artifacts 857 --json
 erdos workspace show --json
 erdos pull literature 857 --include-crossref --include-openalex --json
-erdos upstream drift 857 --json
+erdos import drift 857 --json
 ```
 
 ## ORP And Truth Hygiene
@@ -260,8 +456,8 @@ erdos upstream drift 857 --json
 - `templates/FAILED_TOPIC.md`
 
 The package keeps these layers separate:
-- upstream public truth
-- local canonical dossier truth
+- canonical repo truth
+- external imported public truth
 - workspace bundle truth
 - pack-specific route / checkpoint / run truth
 
@@ -294,13 +490,14 @@ erdos maintainer review problem 25 --from-pull .erdos/pulls/25
 erdos archive scaffold 1008 --json
 ```
 
-## Canonical Sources
+## Canonical Home And External Inputs
 
+- canonical repo: <https://github.com/SproutSeeds/erdos-problems>
 - local dossier truth: `problems/<id>/problem.yaml`
-- bundled upstream snapshot: `data/upstream/erdosproblems/`
-- workspace upstream snapshot: `.erdos/upstream/erdosproblems/`
-- live upstream repo: <https://github.com/teorth/erdosproblems>
-- live public site: <https://www.erdosproblems.com/>
+- bundled external import snapshot: `data/upstream/erdosproblems/`
+- workspace external import snapshot: `.erdos/upstream/erdosproblems/`
+- external atlas import repo: <https://github.com/teorth/erdosproblems>
+- external public site: <https://www.erdosproblems.com/>
 
 ## Docs
 
@@ -321,7 +518,7 @@ If you are preparing a public post, start here:
 
 ### What is the difference between this and erdosproblems.com?
 
-`erdosproblems.com` is a public problem atlas. `erdos-problems` uses that public record, but adds local dossiers, workspace scaffolding, checkpoints, and pack-specific views for the problems that already have more structure here.
+`erdosproblems.com` is an external public problem source. `erdos-problems` imports from public sources when helpful, but keeps its canonical dossiers, packs, workflow, and contribution surface in this repo.
 
 ### Can I use this with Codex, Claude Code, or another agent?
 

package/data/upstream/erdosproblems/SYNC_MANIFEST.json

@@ -1,9 +1,9 @@
 {
-  "upstream_repo": "https://github.com/teorth/erdosproblems",
-  "source_url": "https://raw.githubusercontent.com/teorth/erdosproblems/master/data/problems.yaml",
-  "source_file": "data/problems.yaml",
+  "external_repo": "https://github.com/teorth/erdosproblems",
+  "external_source_url": "https://raw.githubusercontent.com/teorth/erdosproblems/master/data/problems.yaml",
+  "external_source_file": "data/problems.yaml",
+  "imported_commit": "cd91711d143184e090e5336e3165be50abfaaaf3",
   "fetched_at": "2026-03-25T19:24:57.377Z",
-  "upstream_commit": "cd91711d143184e090e5336e3165be50abfaaaf3",
   "raw_sha256": "e2d161ffe3866275704bb18a268f9417f32d8a92a0af19fa119a856445cd2021",
   "entry_count": 1183
 }

package/docs/CANONICAL_REPO_MIGRATION_PLAN.md

@@ -0,0 +1,279 @@
+# Canonical Repo Migration Plan
+
+Last updated: 2026-03-30
+
+## Decision
+
+`SproutSeeds/erdos-problems` becomes the canonical public home for:
+
+- the Erdős problem atlas as presented by this project
+- canonical seeded dossiers
+- pack-specific route, board, and compute packets
+- formal artifacts, papers, and deeper research files that are intentionally public
+- contribution, issue, and pull-request workflow
+
+External sources remain valuable, but they are inputs, not authorities:
+
+- `erdosproblems.com` remains a public source surface
+- `teorth/erdosproblems` remains an import and comparison source when useful
+- `sunflower-coda` is treated as a migration source and lab origin, not the long-term public home
+
+## Why
+
+The current architecture mixes two different ownership stories:
+
+- the package, CLI, and curated public harness live in `SproutSeeds/erdos-problems`
+- the bundled atlas snapshot and several provenance fields still point at `teorth/erdosproblems` as "upstream truth"
+
+That split is workable for importing data, but confusing for users. It leaves the project with two competing authority stories:
+
+- "this repo is the home"
+- "another repo is the truth"
+
+The migration resolves that by keeping one canonical owner and treating outside sources as import feeds with explicit provenance.
+
+## Product Model After Migration
+
+### Canonical public home
+
+- GitHub repo: `SproutSeeds/erdos-problems`
+- npm package: installable CLI and packaged public harness assets
+- canonical problem records: `problems/<id>/`
+- canonical pack context: `packs/<family>/`
+- canonical public docs: `docs/`
+
+### External imports
+
+- imported public site snapshots
+- imported external atlas snapshots
+- imported public literature adapters
+
+These stay visible as provenance, but never outrank the canonical local record.
+
+### Packaging split
+
+The GitHub repo may contain much more than the npm tarball.
+
+GitHub can hold:
+
+- deep research notes
+- paper drafts and public reference bundles
+- Lean and formalization source
+- board JSON exports
+- long-form analysis artifacts
+
+The npm package should ship only what is needed for:
+
+- the CLI
+- canonical dossiers
+- pack packets
+- packaged compute packets
+- essential docs and templates
+
+## Current State
+
+Today the repo already behaves partly like the canonical home:
+
+- `erdos problem list` and `erdos problem show` are driven by local seeded dossiers under `problems/`
+- the public deep harness for `20` and `857` is already expressed in local pack files under `packs/sunflower/`
+- the GitHub repo is already the collaboration surface for issues and PRs
+
+But these parts still reflect the old authority model:
+
+- `src/upstream/sync.js` fetches and labels `teorth/erdosproblems` as the upstream repo
+- bundled manifest files record that external repo as the source of truth
+- dossier `upstream.repo` fields and references point at `teorth/erdosproblems`
+- docs describe that external repo as the upstream truth layer
+- package shipping boundaries are still broad enough that repo-only deep research would accidentally ship if dropped into currently published directories
+
+## Migration Principles
+
+1. One canonical owner
+   `SproutSeeds/erdos-problems` is the only authority users should need to trust.
+
+2. Provenance without ambiguity
+   External records stay cited, but only as imported evidence.
+
+3. Fast install, deep repo
+   npm stays lean enough for CLI installs, while GitHub can hold the full public research archive.
+
+4. Public handoff first
+   A new user should be able to pick up `20` or `857` and immediately see the live route posture, active files, and next honest move.
+
+5. Deep material on demand
+   Users should be able to pull or inspect fuller problem bundles from the repo without shipping all of that by default in npm.
+
+## Rollout Phases
+
+## Phase 1: Ownership And Provenance Cleanup
+
+Goal:
+- make the docs and metadata say what the product now means
+
+Changes:
+- rewrite docs so `SproutSeeds/erdos-problems` is described as canonical
+- replace "upstream truth" wording with "external import source" wording
+- update dossier schema language to distinguish:
+  - canonical local record
+  - imported external sources
+  - public site snapshots
+- update any visible README/help text that suggests the external repo is authoritative
+
+Acceptance:
+- a user reading the README should understand there is one canonical repo
+- no user-facing docs should describe `teorth/erdosproblems` as the authoritative owner of this package's atlas
+
+## Phase 2: Package Boundary Split
+
+Goal:
+- let GitHub hold the full public archive without forcing it into npm
+
+Changes:
+- define repo-only directories for deep research
+- tighten `package.json` `files` handling or segregate content so deep research is excluded from the tarball
+- document which directories are:
+  - canonical and shipped
+  - canonical but repo-only
+  - generated workspace state
+
+Candidate repo-only directories:
+- `research/`
+- `formal/lean/`
+- `paper/`
+- `imports/`
+- `analysis/`
+
+Acceptance:
+- `npm pack --dry-run` excludes repo-only deep research
+- GitHub still exposes the full public archive
+
+## Phase 3: Repo Structure For Full Public Research
+
+Goal:
+- move the public-facing deep material into this repo in an orderly way
+
+Changes:
+- create canonical directories for:
+  - problem-deep research bundles
+  - Lean / formal source
+  - paper drafts and publication support
+  - imported external snapshots and reconciliations
+- preserve a clear distinction between:
+  - concise user-facing handoff packets
+  - deeper research inventory
+
+Suggested layout:
+
+```text
+erdos-problems/
+  problems/<id>/
+  packs/<family>/
+  research/problems/<id>/
+  formal/lean/
+  paper/
+  imports/
+```
+
+Acceptance:
+- the repo can absorb public material from `sunflower-coda` without collapsing the package structure
+
+## Phase 4: CLI Surface For Deep Problem Bundles
+
+Goal:
+- let users access the deeper repo-held material intentionally
+
+Changes:
+- add documented repo-backed bundle concepts, for example:
+  - deep research bundle
+  - formalization bundle
+  - paper/reference bundle
+- expose them either as:
+  - repo file paths in scaffold outputs
+  - new CLI commands
+  - both
+
+Possible commands:
+- `erdos problem deep 857`
+- `erdos problem formal 857`
+- `erdos pull repo-bundle 857`
+
+Acceptance:
+- a user can start with the lightweight public packet
+- then intentionally step into the deeper public archive without guessing where things live
+
+## Phase 5: External Import And Reconciliation Workflow
+
+Goal:
+- retain harmony with outside sources without giving away canonical ownership
+
+Changes:
+- rename the current "upstream" semantics toward import/reconcile language
+- preserve diff tooling, but point it at external comparisons rather than canonical truth
+- store imported manifests under an explicitly non-canonical namespace
+
+Possible wording shift:
+- current: "upstream snapshot"
+- target: "import snapshot" or "external atlas snapshot"
+
+Acceptance:
+- a mismatch between an external source and the canonical local record is legible as a reconciliation task, not a contradiction in authority
+
+## Phase 6: Flagship Problem Migration
+
+Goal:
+- make `20` and `857` the model examples of the full system
+
+Changes:
+- migrate the public `sunflower-coda` materials for those problems into this repo
+- replace `sunflower-coda/repo/...` path references with repo-local paths
+- ensure the public packet plus deep bundle plus formal bundle line up cleanly
+
+Acceptance:
+- a new user can pick up `20` or `857` from this repo alone
+- no crucial public handoff step depends on another repo existing
+
+## Risks
+
+### Risk: accidental npm bloat
+
+If deep research lands under currently shipped directories, npm installs become heavier and noisier.
+
+Mitigation:
+- separate repo-only directories
+- verify with `npm pack --dry-run`
+
+### Risk: provenance confusion
+
+If external import fields disappear entirely, users may lose track of where records originated.
+
+Mitigation:
+- keep provenance blocks, but label them as imported or external
+
+### Risk: partial migration
+
+If docs are updated before structure and commands are ready, users may expect deeper repo-backed pulls that do not exist yet.
+
+Mitigation:
+- roll out phase by phase
+- clearly document what exists now versus what is planned
+
+## Initial Implementation Slice
+
+This change series should start with the smallest durable slice:
+
+1. store this migration plan in the repo
+2. update ownership/provenance docs so the repo is described as canonical
+3. create the repo-only directory contract and npm boundary rules
+4. add minimal scaffolding docs for deep research bundles
+
+That gives the project a correct public model before the larger content migration begins.
+
+## Definition Of Done
+
+The migration is complete when:
+
+- `SproutSeeds/erdos-problems` is clearly the canonical public home in docs, metadata, and CLI wording
+- external sources are treated as imports and reconciliation inputs
+- the repo can hold public Lean, paper, and deep research artifacts without shipping all of them to npm
+- flagship problems like `20` and `857` can be followed from this repo alone
+- contributors can update dossiers, packs, and deep research in one place