alc

# Agentic Learning Copilot (ALC) ALC turns local source material into verified text, translations, interactive readers, and source-anchored learning companions. It does not own academic paper discovery or research judgment. ## Select one capability - OCR proofreading against a PDF: read `workflows/ocr-proofread.md` and `manuals/alc-ocr-proofread.md`. - Standalone translation: read `manuals/alc-translate.md`. - Rich-document or standalone HTML rendering: read `manuals/ac-document.md` and `manuals/alc-render.md`. - Companion build, resume, revision, or render: read `workflows/companion.md` and `manuals/alc-companion.md`. When the requested result includes a reading guide, paragraph companion, visible glossary, or a complete learning Reader, select the Companion workflow. Standalone translation owns source-plus-translation delivery; it does not substitute for Companion merely because it builds a glossary prerequisite. Read `rules/interaction.md` for user-choice and automation behavior and `rules/operating.md` for shared local-state rules. Do not preload unrelated manuals. ## CLI resolution Use `alc-ocr-proofread`, `alc-translate`, `alc-render`, or `alc-companion` directly when exposed by the host. Shared Foundation commands such as `ac-document`, `ac-jobs`, `ac-llm`, and `ac-proposer-reviewer` are intentionally not separate plugin wrappers; invoke them through the product launcher: ```bash <skill-dir>/scripts/alc-runtime ac-document <command> [args...] ``` For an ALC command unavailable on `PATH`, use the same launcher: ```bash <skill-dir>/scripts/alc-runtime alc-translate <command> [args...] ``` For Companion, use `<skill-dir>/../../bin/alc-companion` when the command is not on PATH. This plugin entrypoint supplies the optional research host; do not bypass it with the generic runtime launcher for Companion builds. In DeepSeek Harness, use `$DSH_ALC_RUNTIME` in place of the launcher path. Prewarm with `alc-runtime setup`; inspect source identity and readiness with `alc-runtime doctor`. Runtime locks pin full Git SHAs for both ALC and AC Foundation. Generic document cache defaults to `.ac/cache/ac-document` under the launch directory. Durable learning state stays under the selected project's `.alc/` directory. Never treat durable runs as shared cache. ## Optional academic enrichment `alc-companion` itself does not import or invoke ARC. Chapter workers may request research through a host adapter. The plugin launcher exposes `scripts/companion-research-host`, automatically checking `arc-paper` on PATH, enabled installed Codex/Claude user ARC plugins, and standalone ARC skills. Probe the runtime with `doctor` and required commands with `--help`; never run `setup`. Only ready, capable runtimes are used. Missing or failed discovery exposes no ARC tools and the build continues using available model search. Do not ask the user to configure paths. `ALC_ARC_PAPER` remains an optional advanced override. Do not install ARC to satisfy an internal worker request. An empty `ALC_COMPANION_RESEARCH_HOST` disables it. For separately prepared enrichment, if a Companion would materially benefit from paper discovery or literature review, the Skill may suggest using ARC first and passing reviewed local supplements into ALC. If ARC is unavailable, continue with available host research or original evidence without requiring installation or path configuration. Never install ARC automatically and never make it a Python or runtime dependency of ALC. ## Direct HTML sources For a URL or paper identifier supplied for translation or Companion, use the same Foundation acquisition route as Local Web. Convert a bare arXiv ID (including its explicit vN suffix) or arXiv: identifier to https://arxiv.org/html/<id>. Convert a DOI to https://doi.org/<doi>. Preserve an existing public HTTPS URL. Do not choose an alternate acquisition route merely because ARC is installed. ARC remains optional for explicitly requested discovery or enrichment. ```bash <skill-dir>/scripts/alc-runtime ac-document acquire-html-bundle <html-url> \ --output-dir <bundle-dir> ``` Retain source.html, manifest.json and local resources together. Pass `--html-source-manifest <bundle-dir>/manifest.json` to Companion. If a URL returns PDF or another format, identify that format and use its supported explicit input workflow; do not silently replace the requested source with a different edition. Acquisition warnings and source identity remain attached to the result. ## PDF sources For PDF translation, rendering or Companion, read the PDF input section of `manuals/ac-document.md` first. It routes through the project's configured MinerU and preserves the PDF manifest throughout the learning workflow. Local Web and this plugin share that project configuration; remote upload still requires authorization for the selected destination. OCR extraction alone must not be labeled proofreading. For optional native PDF proofreading, read `manuals/alc-ocr-proofread.md`: use `proofread-bundle`, retain all page mappings and assets, and obtain explicit user approval of the candidate before adopting the revised bundle. ## Completion Validate the owning workflow before delivery. Publish visible HTML or native source artifacts; hidden state is not the final deliverable. Preserve exact source identity, returned run IDs, assumptions, and warnings. Keep following a model-backed command until its execution session returns a terminal result. A yielded tool session or a period without stdout is not a completed command. Do not end the task with "still running" while that session remains active; poll the session and use the workflow's public status command for progress. A run snapshot's timestamp alone does not measure live progress. Never infer that no work was saved from an absent final Layer or HTML file. After successful standalone translation, compose and validate the Reader as documented in manuals/alc-translate.md; a Layer JSON is not the requested HTML delivery. Stop or defer only when the user requests it or a concrete blocker requires user input, and describe the verified state at that point. ## Workflow and resource policy Use the shared Local Web processing defaults for new translation and Companion: `--execution-profile local-app`, 2 workers, and `--review-rounds 1`. Specify the same provider/model/language chosen by the user; do not silently substitute a model. Use the medium-tier default when no model is requested. The local-app profile uses the official CLI login and isolated execution; custom API routes must be configured explicitly rather than inherited from host CLI settings. Presets: fast draft = 4 workers / 0 reviews; standard = 2 / 1; strengthened review = 2 / 2. User-chosen combinations are custom. Accept 1–8 workers and review rounds 0, 1 or 2. Zero skips model content review while retaining programmatic source and output validation. Two stops early when no correction is needed. Pass `--workers N` to Companion and `--window-workers N` to translation. Companion preloads complete original and frozen translated chapter inputs before guide generation. Do not silently fall back to incomplete agent-directed reads. Treat unavailable input as retryable preparation failure and oversized input as an explicit capacity limit. Resume keeps the frozen review and evidence policy; use `--execution-profile local-app` and the task's saved worker count on resume. Do not rewrite old requests to upgrade them in place. Do not add a separate cross-chapter review flag to new explicit-policy tasks; review_rounds governs it. Concurrency is a per-task upper limit. Independent tasks do not divide one user-wide pool: two tasks configured for eight can issue sixteen requests in total. Hardware, network and provider limits can reduce actual throughput. Local Web separately limits the number of simultaneous document jobs. ## Local history discovery The installed learning CLIs register their `--project-dir` in a local catalog, independently of LocalWeb. Keep project directories durable so users can open those records in LocalWeb later. Do not put persistent results in temporary folders. Existing projects can be registered by running their normal status command or through LocalWeb's “导入插件项目”. LocalWeb currently exposes these records and results read-only; use the original Agent command to resume them.