lectic 0.1.0__py3-none-any.whl

lectic/DESIGN.md

@@ -0,0 +1,143 @@
+# Design: compile expertise, preserve evidence
+
+The canonical product direction is [NORTH_STAR.md](NORTH_STAR.md). The core compiles reusable expertise; an installed skill is one interface, and Agent Skills is one output format. The source collection and IR must outlive any provider, runtime, interface or target.
+
+## Core, target and interface boundaries
+
+Conceptually, `expertise-core/` owns sources, collections, IR, extraction/reconciliation, goals/build intent, selection/compilation, provenance, versioning, validation and evaluation. `targets/` contains consumers of those contracts: skill, agent, workflow, reviewer, coach, eval, knowledge-pack, custom and future targets. `interfaces/` contains Codex/Claude skills and CLI today, with desktop, web, API or MCP as possible later adapters. These are responsibility boundaries, not newly implemented directories or a commitment to ship all of them.
+
+The conceptual pipeline is collection → durable IR → build intent → select/extend relevant expertise → compiled method/capability → target artifact → validate/evaluate → portable output. Selection must leave the original IR intact. New extraction extends a versioned representation; changing a target must not require re-ingesting the corpus. An artifact can be a useful direct result or an exported capability. Validation may precede a later runtime evaluation; portability does not imply effectiveness has been measured.
+
+Build intent ultimately needs independent inclusion/exclusion choices: reasoning without personality, interview techniques without unrelated knowledge, language tendencies without opinions, or a multi-expert reviewer that preserves disagreement without imitating its sources. Current free-text briefs can describe these requests, but structured selection enforcement is future work. Existing intents describe purposes, not all possible artifact types; future targets must be extensible without turning the IR into a list of provider or exporter formats.
+
+| Responsibility | Current implementation | Boundary to preserve |
+| --- | --- | --- |
+| Capture and personal context | scripts/capture_store.py; capture schemas | Saved input and annotations are distinct from source truth |
+| First capture adapter | scripts/capture_input.py; scripts/capture_write.py; docs/iphone-shortcut.md | Synced-folder transport independent of compiler/provider |
+| Sources, IR, validation | schemas and parts of scripts/ec.py | Provider-neutral source and knowledge records |
+| Collections and revisions | scripts/collection_store.py | Durable private archive independent of builds |
+| Storage location and primitives | scripts/home.py; scripts/store.py | One home per user; blobs, staged publish and transactions are the only filesystem-specific operations |
+| Opportunity discovery | scripts/capability_maps.py; discovery prompt | Replaceable, versioned interpretation of IR |
+| Library and next-use guidance | scripts/library_guide.py; use-guide schema; guide-use prompt | Read actual saved state; keep personal applications separate from IR and exports |
+| Goals and compilation | scripts/goal_workflow.py; extraction/reconciliation prompts | Interpret intent, select expertise and preserve evidence |
+| Current text outcome targets | scripts/outcomes.py | Rendering and goal contracts, not an exhaustive expertise taxonomy |
+| Agent Skills target | scripts/scoped_export.py; rendering in scripts/ec.py | Scoped export consuming core records |
+| Evaluation | scripts/evaluate.py and evaluation prompts | Distinguish integrity, meaning and observed behavior |
+| Assistant interfaces | SKILL.md, agents/openai.yaml, operator prompts, installer | Gather intent and operate core; no provider dependence in IR |
+| CLI interface | command dispatch in scripts/ec.py | Invoke core operations; do not define the product |
+| MCP interface | scripts/lectic_mcp.py | Same operations over tools, stdio or Streamable HTTP; every client-produced record enters through one validated write door |
+| Command line for people | cli.py | setup, share, connect, pack, install, status |
+| Knowledge packs | scripts/packs.py; pack schema | One content-addressed file; sources travel as links and are re-verified on install; partial verification is reported, never hidden |
+
+New capture and discovery modules sit alongside the existing compiler without moving its public entry points. The installer includes their contracts, prompts and documentation, including the north-star document, so the distributed interface retains the architecture guidance.
+
+## Remaining structural coupling
+
+The implementation is useful but not yet a fully separated core package:
+
+- `ec.py` mixes core validation/parsing with CLI dispatch and skill rendering; other modules import it. Split responsibilities incrementally while preserving public commands and artifact formats.
+- `goal_workflow.py` coordinates assistant prompt paths and specific renderers/exporters. A later core compilation contract should accept reasoning results independently of the installed interface and dispatch targets through explicit contracts.
+- `outcomes.py`, CLI choices and schemas enumerate eight intents and a closed set of section kinds. They are today's supported contracts, not an extensible target registry. Do not add one new core enum for every future use case.
+- Compiled methods reuse a capability schema with skill-oriented IDs, required steps and examples. This is distinct from the IR, but not yet a neutral representation for every profile, evaluator or custom target.
+- The IR has a closed unit-type enum; conditions, exceptions and some style/reasoning characteristics currently live in statements, scope, derivations and relationships. It does not yet provide typed, independently selectable components for the full north-star taxonomy. Evolve it with versioned compatibility rather than assuming today's labels are exhaustive.
+- Build intent has no structured include/exclude contract or correction revision. User instructions can guide reasoning but exclusions are not deterministically enforced, and corrections do not yet propagate through a durable regression loop.
+- Compiler fingerprints include the installed SKILL.md. This conservatively tracks current instruction changes, but eventually core, reasoning-interface and target versions should be recorded separately in build manifests.
+
+These are explicit follow-up constraints, not implemented features or reasons to rebuild the entire project. Canonical source and IR schemas currently contain no mandatory provider-specific fields, and existing records remain unchanged.
+
+## Storage: one home, cloud-shaped
+
+`home.py` resolves where knowledge lives: `LECTIC_HOME` if set, else a project's existing `.expertise-compiler/` when it actually holds storage (legacy project-local mode), else `~/.lectic`. Collections, captures, builds, exports and legacy runs all live under that home, so every project and every assistant on the machine reads the same library. Per-project state that must stay separate (the legacy numbered-capability session) is keyed by project inside the home. Session pointers written by project-local installs still resolve.
+
+Everything persisted is one of two kinds. Immutable objects: content-addressed blobs (`HOME/blobs/<sha256>`) and validated snapshots (source revisions, builds, maps, packages), written once and never edited. Small mutable indexes: `library.json`, `collection.json`, capture state. `store.py` owns the three operations that need a filesystem: `put_blob`/`get_blob`/`materialize` (a snapshot gets its raw bytes by hard link where possible, by copy otherwise; the blob store stays canonical, so nothing requires hard-link support any more), `stage()` (assemble beside the destination, publish by one rename, discard on error, never merge into an existing snapshot) and `transaction()` (serialize index writers). Nothing above this module links, renames or locks directly. A remote store implements the same three operations with object storage and compare-and-swap; because identities are content hashes, the immutable side needs no merge logic and only the small indexes need CAS.
+
+`lectic_mcp.py` is the second step: the same coordinators over MCP tools, with `lectic_read` limited to the home and the skill and `lectic_write_json` admitting only the record kinds a workflow asks for (checkpoints, drafts, briefs, map and guide drafts, evaluation records), each validated against its schema and, for checkpoints, against the run's sources before it lands. Published snapshots, history, sources, raw bytes, capture records and indexes cannot be written by a client at all. The installed skill still drives the same state machine through the CLI and direct file writes, so `units/`, `history/`, `state/` and similar directories are still enumerated with `glob`; once the skill also routes writes through the server, index files can replace listing. Hosted assistants and phones reach the same server over Streamable HTTP behind one secret link (`lectic share`, or the container in `Dockerfile`); wherever the server runs, that home is the knowledge, so nothing is synchronized. The sequence is: shared home and store seam (done) → tools instead of direct file writes (done for MCP clients) → one server reachable from anywhere (done) → a remote object store behind the seam, so several machines can share one home without one of them being the server.
+
+## Capture layer before the compiler
+
+The architecture now includes capture → sources/collections → expertise compiler → builds/outcomes. `capture_store.py` owns immutable envelopes, attachment blobs, annotation events and mutable membership/processing state. `capture_write.py` is a reference producer for the generic folder contract. The iPhone Shortcut is a first adapter described in `docs/iphone-shortcut.md`; there is no iCloud API in the core, native application, hosted backend, watcher or retrieval service.
+
+Capture and annotation schemas are independent of source and IR schemas. A capture preserves original shared value, known URL/title/type, attachment references, timestamp and entry provenance. A separate state record tracks import identity, multiple stable collection IDs, normalized source IDs and processing issues. Notes never enter normalized segments. New build briefs snapshot relevant capture context privately; later notes cannot mutate old builds or become source evidence. Trace operations follow cited result units to historical source IDs and then to captures.
+
+The minimal share adapter only requires original shared content and capture time. `capture_input.py` expands `.capture.json` inputs into the existing canonical schema at import: stable identity, URL detection, type, status and provenance belong on desktop, where they are testable and updateable without rebuilding each phone Shortcut. Capture time must still come from the producer, since sync/import time is not capture time. Personal notes remain separate optional fields. The four-action phone recipe and full legacy records feed the same core; the core never assumes that a file's adapter label authenticates its originating device. See the [minimal input contract](docs/CAPTURE.md#minimal-share-input-adapter) for timestamp/identity and same-time duplicate semantics.
+
+Import is idempotent by capture ID and envelope fingerprint. Attachment blobs are content-addressed; different intentional captures may retain separate notes while sharing source content. A repeated ID with different data is an error, not an update. Synced JSON records are commit markers written after attachments. Missing files and early annotation events retry on a later explicit import. Original synced files remain untouched. A local OS writer lock serializes capture CLI mutations and releases on process exit; the project does not merge competing desktop replicas.
+
+Normalized captures live once in a canonical source store, and raw bytes live once in the home's blob store. `Library.attach_shared` records memberships as existing-format immutable source snapshots whose raw files the store materializes from those blobs (hard link where the filesystem allows it, copy otherwise). Thus current source validators, evidence paths and build formats remain compatible, no payload is stored twice where the filesystem can share it, and no filesystem prerequisite remains. Legacy ingestion registers its bytes with the same blob store; earlier snapshots are not rewritten. Private snapshots and canonical source files should be treated as immutable; hashes detect tampering.
+
+Explicit processing normalizes supplied text, eligible transcript attachments and successfully retrieved captions. `linked_sources.py` owns linked-source routing and an immutable, hash-verified acquisition cache; the first retriever is YouTube via an optional local `yt-dlp` executable. `capture_store.py` calls this generic boundary only during processing. It records retrieval separately from normalization and saved IR coverage; successful captions do not automatically mean processed. Exact capture URLs and personal notes survive canonical video identity deduplication. [Acquisition contract](docs/YOUTUBE.md).
+
+Processing reuses verified source-local checkpoints from current or historical collection revisions when evidence, IDs and relations remain compatible. Cross-source synthesis still needs reconciliation. Nothing recompiles on import, and no broad dependency-rebuild system is added. Processing statuses distinguish saved data, unavailable linked content, partial work, a saved IR representation and issues. A validated representation is not truth or proof that all expertise was extracted.
+
+Relationships currently use explicit capture IDs, source IDs, collection IDs, annotation IDs and build/IR evidence links. Graph-style traversal can be introduced later if useful; no graph database is needed. Membership removal preserves historical originals; a capture with no remaining named membership returns to Inbox. Capture state lives in the shared home, and the synced intake is not bidirectional synchronization of compiler state. See [capture contract](docs/CAPTURE.md) for exact storage and failure behavior.
+
+## Capability Maps: derived opportunity discovery
+
+The optional exploration path is collection → durable IR → Capability Map → selected build intent → compiled method → result/asset. A known goal bypasses discovery. `scripts/capability_maps.py` owns binding, validation, qualitative ranking, immutable map persistence, comparison and selection. The skill and CLI are interfaces to it; assistant reasoning follows `prompts/opportunity-discovery.md`. No model SDK, domain-specific branch or source recommendation field is added.
+
+`capability-map-draft.schema.json` records semantic assessments of ten universal transformation categories and up to eight distinct candidates, including useful weak gaps. `capability-map.schema.json` binds the reviewed draft to collection/source revision, full IR hash, compiler version/fingerprint and discovery method version. Canonical content hashes identify map revisions. A collection's `maps/` directory stores JSON and readable Markdown; `maps/index.json` preserves history and the last shown map. Drafts are resumable. Original IR and its history stay separate and unchanged by map generation.
+
+Ranking is qualitative and lexicographic: support, reuse, actionability, saved work, judgment, differentiation from Q&A; stable ID resolves ties. Up to five non-weak opportunities are shown. Exact source counts are derived from evidence, not confidence scores. Validators require known evidence IDs, typed procedural/criteria support, examples and conditions for strong actionable opportunities, all recorded contradictions touching a selection, current delivery forms and complete internal category assessment. These checks cannot establish entailment: the assistant must assess whether examples, criteria and conditions actually support the proposed job. A misleading title or prose claim is not reliably rejected by type checks alone. Live discovery quality remains unmeasured.
+
+Comparison uses stable job IDs and reports new, removed/invalidated, stronger/weaker, newly supported, conflict-affected and evidence-changed entries. Support changes reflect assistant judgments, not measured improvements. Source changes require preparation and regeneration; stale selection is rejected. Historical maps validate against historical IR. Identical regeneration is idempotent; changed interpretations create new map IDs without overwriting old maps.
+
+Selecting a shown number or title stores the full opportunity and map ID in a private build brief, including evidence, input/transformation/output, future use categories, boundaries, conflicts and targets. The normal pipeline then assesses coverage and builds a reusable text method through its existing CREATE contract, without needing a sample user draft or technical artifact choice. This is intentionally distinct from applying that method to an actual review task. Skill export remains explicit. Opportunity categories AUTOMATE and EVALUATE do not add executable workflow or eval-suite targets; portable instructions and rubrics can be produced as text, while unavailable integrations remain marked future.
+
+The existing legacy numbered capability flow remains available. The old `work` missing-goal response remains a compatibility fallback; the updated conversational adapter routes goal-free content to maps. The current map module still calls the goal coordinator for preparation/builds, so the eventual provider-independent core API split remains future work. Correction propagation and behavioral regression evaluation remain the next major quality direction.
+
+## Universal goal compilation
+
+The architecture separates collection, durable IR, user brief, compiled method, result and optional exported asset. A collection can support CREATE, REVIEW, IMPROVE, DECIDE, PLAN, DO, LEARN and REFERENCE. These are internal outcome contracts, not product niches or a user menu. The host assistant interprets natural language and records intent plus reasoning in the brief. Python validates and routes this decision; it has no domain classifier or domain-specific branches.
+
+New outcomes use schema version 1.1. Typed sections carry useful work and epistemic labels. Source-derived sections cite selected units; original creations and user context remain separate. Minimal intent contracts require, for example, options plus recommendation for DECIDE or lesson plus exercise for LEARN. These checks detect missing structure, not meaningful analysis or learner mastery. The assistant supplies and reviews semantics.
+
+Legacy 1.0 review/checklist results retain their schemas, rendering and package validation. New intent-bearing briefs produce outcome builds with a readable method and relevant evidence; a skill package is generated only on explicit export. The method retains the existing evidence-linked capability structure. Compiler fingerprints include root SKILL.md, scripts, prompts and schemas.
+
+Collections support preparation without a goal, summaries, addition/replacement/removal, history comparison, archive/restore and reuse. Removing the final active source creates an empty source revision and preserves history. Missing evidence invalidates knowledge and its transitive relationships; valid partial knowledge is retained for a targeted pass. Earlier builds validate against their historical IR and originals. Explicit knowledge hashes permit comparisons within a source revision.
+
+Archive is a reversible lifecycle flag, not deletion. Explicit named use restores an archived collection. “Just save for later” preserves originals; “Save these as NAME” can prepare knowledge without inventing a goal, result or skill. Later goals, from any project on the machine, do not need source re-upload. This iteration adds no accounts, hosted storage, networking, model APIs, agent teams or ingestion integrations.
+
+## Current conversational interface
+
+The installed skill is an interface/adapter to the core compiler, not the canonical product surface or architecture. Users supply sources and explain what they want to accomplish. The assistant saves a brief, applies relevant methods and presents a useful result or artifact. Exploration and archiving are valid alternatives. Internal phase results are tasks for the interface's reasoning engine, never a user checklist.
+
+`goal_workflow.py` layers named collections and saved work over the original compiler. `collection_store.py` preserves additive source revisions and can copy an existing run without changing it. A brief stores the user's context separately from evidence. Each goal explicitly assesses extraction sufficiency; targeted source passes can extend knowledge. Builds bind source/IR revisions, brief, method, result, target and compiler fingerprint. Earlier builds remain reproducible after updates. Deterministic validation runs before a staged build becomes complete.
+
+A coordinator now keeps per-project session state inside the home, separate from the installed skill, snapshots changed inputs automatically, validates complete checkpoints, and binds a reconciliation acknowledgement to their exact content. It assembles reviewed knowledge, validates proposals, binds displayed numbers to an IR/proposal revision, and creates or reuses checked exports. Review acknowledgements prove only that the agent signaled review; they do not establish semantic correctness. Explicit low-level tools remain available to contributors.
+
+Capability reuse and comparisons resolve the selected/last-built option in the current corpus. Evaluation tasks/rubrics are frozen separately from exported skills. The same coordinator supports unrelated domains. Transcript-file and optional YouTube adapters supply raw bytes and metadata without IR coupling. YouTube acquisition uses network access only on requested processing (or explicit direct ingestion); no video/audio fallback exists. No natural-language parser in Python or external model call substitutes for the assistant's reasoning.
+
+The value proposition is a maintained transformation between source material and useful actions. A transcript chat can answer excellent questions, but its method, scope limits, and source reconciliation are often implicit in a session. This compiler makes those choices durable and inspectable, then reuses them across tasks and assistants.
+
+## What creates value
+
+1. **Evidence-preserving transformation.** Every reusable unit retains exact source spans and attribution. Users can audit advice without searching a long conversation.
+2. **Reconciliation.** Related and contradictory units remain linked. Export cannot quietly drop a recorded contradiction or prerequisite. Conflicts need an operating policy rather than a false consensus.
+3. **Abstraction with disclosure.** Explicit source statements remain separate from inference and synthesized frameworks. Derivation explains how an abstraction was formed; no fake confidence number disguises that step.
+4. **Proceduralization.** Capabilities specify inputs, branches, outputs, boundaries, examples, and checks. They aim to produce repeatable work on new inputs, not just summaries.
+5. **Reusable assets.** A portable skill can be checked and used in a new session; the IR survives that target. Future knowledge packs, MCP tools, or agents can compile from the same representation.
+6. **Evaluation and maintenance.** Held-out tasks, auditable citations, revision hashes, and deterministic failures make changes reviewable. Measured improvement, corpus quality, and reliable transformation workflows could become a defensible advantage. A folder format or prompt alone is not a moat.
+
+## Architecture
+
+Python owns parsing, canonical serialization, hashing, cross-reference checks, artifact assembly, and packaging. The user's assistant owns semantic extraction, reconciliation, capability discovery, and procedure design. There is no hidden paid API and no keyword extractor pretending to perform those semantic operations.
+
+Source IDs bind relative filename and raw byte hash. Identical text from different filenames remains separate evidence; repeated content is not silently deduplicated. A corpus ID binds ordered source IDs and canonical document hashes, including metadata. IR hashes bind knowledge and coverage. Capabilities bind an IR hash. Package manifests bind every exported file except the manifest itself.
+
+Sources and IR retain schema version `1.0`; new general outcomes use `1.1` and older builds remain readable. Incompatible versions fail closed. Arrays have deterministic order when assembled; canonical hashes use UTF-8 sorted-key JSON, while disk JSON is readable and indented. Source segment IDs are stable within an unchanged source snapshot. Editing a source creates a new identity rather than disguising changed evidence under an old ID.
+
+Input snapshots and exports are staged and published only after validation. Source-level checkpoints enable resume without redoing complete sources. Assembly saves IR revisions and replaces the current IR atomically. Two writers should not edit the same run concurrently; distributed locking and merge resolution are outside the MVP.
+
+Ordinary exports contain only the method, selected knowledge and relevant quotations. Closure checks preserve recorded prerequisites and contradictions. Export validators establish internal consistency, while private build validation links the export back to full originals and historical IR. Full private audit bundles and scoped portable exports are deliberately separate. Legacy full-corpus packages remain readable by the validator. Semantic review is still needed to detect private context paraphrased into a method.
+
+## What this does not establish
+
+Exact quotations and hashes establish identity and location, not truth, entailment, completeness, legality of reuse, or usefulness. The assistant can still misunderstand a source or design a weak capability. Instructions treat transcript content as untrusted data, but prompt wording is not a complete defense against adversarial content. Human review and realistic held-out evaluation remain part of quality assurance.
+
+The demo includes unrelated domains to test the representation, plus an intentionally conflicting opinion to expose reconciliation behavior. It uses authored reference outputs, so it proves the deterministic pipeline can carry meaningful assets; it does not measure model extraction quality. The paired harness tests a separate hypothesis: whether reuse yields more actionable, faithful, traceable answers for comparable effort. Equal scores or higher upfront compilation costs are valid outcomes.
+
+## Next investments after observing real use
+
+The next highest-leverage feature is versioned, evidence-anchored interpretation corrections with regression cases: preserve the old interpretation, record the correction and rationale, create a new IR revision, identify affected builds, and verify the correction survives future compilation. Never overwrite raw evidence or attribute a correction to the source. Source changes must trigger reconsideration of dependent corrections. This is documented future work, not a new platform implemented here.
+
+Use that quality loop to reveal which decomposition and selection contracts need stronger structure. Keep target/interface separation and backward compatibility explicit as those changes arrive. Additional ingestion integrations, exporters and hosted surfaces should follow demonstrated need rather than define the product. See the north star's twenty use cases and architectural review guardrails before extending scope.

lectic/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Expertise Compiler (now Lectic) contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lectic/NORTH_STAR.md

@@ -0,0 +1,173 @@
+# Lectic: product north star
+
+Lectic takes trusted human content and compiles its useful expertise into a durable, structured, evidence-preserving representation. People building with AI can select and rebuild that expertise toward different goals, capabilities and runtimes.
+
+The assistant interface should actively explain what has been saved and suggest concrete, supported applications before asking users to invent a goal. A readable library and private next-use guides expose the value of durable expertise. Relevant context actually available from the user or host may personalize those guides; it is not source truth, a global identity profile or an assumed connection to platform memory. These presentation artifacts remain separate from IR and portable build targets.
+
+**Delphi digitizes the expert. Lectic compiles the expertise.**
+
+This is product-direction shorthand, not a verified comparison of another company's features. The architectural distinction is: **digital person platforms package the person; Lectic packages reusable pieces of the expertise.** Recreating a person is neither required nor the default.
+
+## What the product is for
+
+The primary users are people building with AI: AI engineers, developers, architects, consultants, agencies, creators building AI products, internal AI teams, technical operators and advanced individuals assembling custom workflows. Consumers can also use the resulting expertise directly.
+
+The product is not primarily a document chatbot, a digital-person or fan-conversation destination, a competitor defined by persona replication, a Codex skill product, a YouTube-to-SKILL.md generator, or a knowledge base limited to one output. Chat, transcript ingestion and skill installation are useful interfaces or implementation choices, not its identity.
+
+## The durable asset
+
+Compiled expertise may include knowledge, concepts, reasoning patterns, mental models, procedures, heuristics, decision rules, conditions and exceptions, communication patterns, vocabulary tendencies, creative methods, examples and counterexamples, disagreements, evaluation criteria, style characteristics and their source evidence.
+
+These dimensions can be selected independently. Knowledge does not imply personality; communication style does not imply opinions; reasoning patterns do not require impersonation. Observed patterns must remain distinct from interpretations of those patterns and from newly synthesized methods. A source-backed statement is not automatically true.
+
+**One corpus can be compiled multiple ways for different goals without re-ingesting or destroying the original expertise representation.**
+
+The corpus can emerge during normal life. A provider-independent capture layer sits before sources and collections: encounter useful material → capture immediately → optional personal context → Inbox or multiple collections → process when useful → durable expertise → Capability Map or goal → build → reuse. A user need not prepare a corpus in advance. Capture exists to feed reusable expertise, not to reposition the product as a bookmarking destination.
+
+Capture records, source content, personal reasons for saving, and compiled methods are distinct records. Saving does not imply retrieval, understanding, agreement, endorsement or policy authority. One canonical source can have several collection memberships. Saving should remain cheap; never repeatedly pay to understand the same available content unnecessarily. Reuse verified representations and perform incremental work when a goal needs it, not on every share.
+
+Deferred acquisition fills the gap between saving a link and possessing usable source content. YouTube caption retrieval is the first supported linked-source adapter, invoked when a user requests processing or useful work. Its cached original bytes feed the existing source contracts; retrieval never substitutes for extraction, reconciliation or evaluation. Other platforms can add adapters without changing the Expertise IR or making ingestion the product's identity.
+
+Compiled knowledge belongs to the person, not to the folder they happened to be working in or the assistant they happened to be using. One Lectic home per user holds every collection; a project is a working context and a filter, never a silo. The same home should eventually be reachable from a phone capture, a web chat, Codex and Claude Code, with local storage as the offline/private mode rather than the only mode. ChatGPT-style project memory is context for an interface; the IR stays explicit and inspectable and is never delegated to a model remembering correctly.
+
+The first capture interface is an iPhone Shortcut using a synced folder; iCloud is an adapter, not a core dependency. Future share extensions, web clippers, email, Android or API adapters can implement the same contract. No native app, hosted account system or background processing service is required for this proof. Explicit IDs and relationships support future traversal; a graph database is an option only if demonstrated relational complexity justifies it.
+
+Users do not need to invent a goal first. Capability Maps provide a core exploration experience: derive the strongest supported opportunities from saved expertise, explain input → transformation → output and limits, then carry the selected opportunity directly into a build. Maps are versioned interpretations, separate from source truth and regeneratable without changing IR. A known goal bypasses the map; archive-only requests still preserve content without forcing discovery.
+
+Selection creates a build-specific view of expertise, not a destructive filter on the collection. If a new goal needs something not extracted before, revisit archived sources and extend the IR with a new revision. Do not assume the first extraction was exhaustive.
+
+For example, the same collection of 50 expert videos could independently support:
+
+1. A decision framework using reasoning but none of the experts' personality.
+2. A questioning skill based only on interview techniques.
+3. A writing-style guide using language tendencies while excluding opinions.
+4. A reviewer applying evaluation criteria.
+5. A teaching coach based on instructional methods.
+6. An evaluation suite testing whether another AI follows the extracted principles.
+
+These are independent builds from shared sources and expertise, not successive conversions that replace one another. This example describes the intended architecture, not a claim that all six exporters exist today.
+
+## Compilation model
+
+```text
+DISCOVER CONTENT DURING NORMAL LIFE
+        ↓
+CAPTURE + OPTIONAL PERSONAL CONTEXT
+        ↓
+SOURCE COLLECTION
+        ↓
+DURABLE EXPERTISE IR
+        ↓
+CAPABILITY MAP / USER BUILD INTENT
+        ↓
+SELECT / EXTEND RELEVANT EXPERTISE
+        ↓
+COMPILED METHOD / CAPABILITY
+        ↓
+TARGET ARTIFACT
+        ↓
+VALIDATE / EVALUATE
+        ↓
+PORTABLE OUTPUT
+```
+
+Build intent includes the goal, context, requested result, relevant dimensions to include, dimensions to exclude, and behavior to assess. A user can name an extraction focus, an exclusion, or a custom desired capability:
+
+> Extract only how these people make decisions.
+
+> Use their knowledge but none of their personality.
+
+> Build a reviewer that applies these five experts' positioning principles, preserves where they disagree, and does not imitate any of them.
+
+The compiler should interpret these intentions rather than require a fixed artifact menu. Intent classes describe the work to accomplish; targets describe representations or runtimes. Neither is the taxonomy of expertise itself. Today's eight intent classes and section types are implemented conventions, not an exhaustive ontology or permanent restriction on custom builds.
+
+## Targets are extensible
+
+Potential targets include a knowledge collection or pack, agent skill, agent, workflow, reviewer, coach, tutor, decision framework, SOP, troubleshooting capability, evaluator, evaluation suite, creative-method profile, reasoning profile, communication-style profile, portable prompt/config package, future MCP/API representation and user-defined capabilities.
+
+This is an open set of examples, not a backlog commitment to build every exporter or a list of separate products. A new target should consume a selected, versioned view of expertise and declare its own validation and runtime requirements. It should not require provider-specific fields in the canonical source or IR models. Portability means preserving the representation and its dependencies while making runtime assumptions explicit, not promising execution in every environment.
+
+## Canonical responsibilities
+
+The following is a conceptual architecture, not a claim that these directories or all modules exist today:
+
+```text
+capture-layer/
+  immutable captures, optional annotations
+  Inbox, source membership, processing state
+  generic adapter contract
+
+expertise-core/
+  sources, collections, expertise IR
+  extraction / reconciliation
+  goals / build intent, compilation
+  provenance, versioning, validation, evaluation
+
+targets/
+  skill, agent, workflow, reviewer, coach
+  eval, knowledge-pack, custom, future targets
+
+interfaces/
+  iPhone Shortcut / synced-folder capture adapter
+  Codex skill, Claude Code skill, CLI
+  future desktop, web, API, MCP
+```
+
+Interfaces gather intent, obtain authorized inputs, supply or coordinate reasoning, invoke core operations and present results. Targets render or adapt compiled capabilities. The core owns durable records, selection, evidence, versions and validation contracts. Core schemas must remain independent of AI provider, assistant, output target and runtime. Dependency direction should flow from interfaces and targets toward core contracts; core records must not require a particular installed skill.
+
+The installed Codex/Claude skill is one interface to the compiler. It currently bundles utilities for convenient local execution. That packaging does not define the core architecture. See [DESIGN.md](DESIGN.md) for the actual code mapping and remaining coupling.
+
+## Twenty use cases that preserve the breadth
+
+These are architecture checks, not twenty products or hard-coded workflows:
+
+1. Build reusable AI expertise from favorite experts.
+2. Preserve company tribal knowledge.
+3. Learn from curated corpora.
+4. Review real work using trusted methods.
+5. Turn courses into ongoing AI coaches.
+6. Provide decision support from trusted thinkers.
+7. Generate reusable agent skills.
+8. Process internal training libraries.
+9. Create creator-owned knowledge products.
+10. Build personal knowledge operating systems.
+11. Compile sales methodologies.
+12. Build technical troubleshooting capabilities.
+13. Generate SOPs from demonstrations and training.
+14. Build role-onboarding systems.
+15. Compile creative and style methods.
+16. Synthesize and reconcile multiple experts.
+17. Build best-practice evaluators.
+18. Turn meeting archives into organizational capability.
+19. Extract persona, reasoning and communication components independently.
+20. Generate domain-specific AI evaluation suites.
+
+## Where the value must compound
+
+Ingestion and asset generation are necessary plumbing, not sufficient differentiation. The harder value is faithful decomposition, exact source evidence, explicit separation of source statements and compiler inference, conditions and exceptions, preserved disagreements, user correction, reuse across targets, versioning and evaluation of whether a capability behaves as intended.
+
+Keep attribution, derivations, explicit/inferred/synthesized status, limits and dissent through every transformation. Do not invent numerical confidence or collapse disagreement into consensus. Separate structural validity, evidence linkage, semantic review and observed effectiveness. Evidence that an artifact is well formed does not prove that its behavior is right.
+
+Private source archives retain full originals and audit records. Outputs and exports carry only what is relevant to their use and provenance, respecting sharing intent. Source attribution does not grant redistribution rights. No automatic publishing or global installation follows from compilation.
+
+## Next major quality direction: correct once, improve future builds
+
+A user should be able to correct an interpretation once and have future builds and tests reflect that correction. The highest-leverage next technical feature is **versioned, evidence-anchored interpretation corrections with regression cases**.
+
+The intended small first slice records a correction against a unit and source revision, preserves the prior interpretation and rationale, produces a new knowledge revision, identifies affected builds, and carries a concrete regression case into subsequent validation/evaluation. It must not rewrite raw sources or present a user correction as an original source statement. Changed source evidence should trigger reconsideration rather than blindly reapplying an old correction. Conflicting corrections need explicit scope and history.
+
+This feature is not implemented by this alignment pass. It is a quality loop within the compiler, not a correction dashboard, hosted platform, or broad evaluation product.
+
+## Change-review guardrails
+
+For future architectural changes, reviewers should ask:
+
+- Can the same collection and IR still serve independent builds, including different inclusion/exclusion choices?
+- Are new provider/runtime/target details isolated from canonical source and expertise records?
+- Is an intent class being mistaken for a fixed list of all possible target artifacts?
+- Do selected views and corrections preserve originals, prior interpretations and independent build history?
+- Can we trace behavior to source evidence and distinguish inference, synthesis, user context and original work?
+- What test would reveal that the compiled capability does not behave as intended?
+- Does this strengthen expertise compilation for AI builders, or drift toward a digital-person destination or ingestion-only utility?
+
+A hosted store, an API or an MCP server are interfaces to the core, and are welcome when they carry the same immutable, content-addressed records and the same validators; they must not become a marketplace, billing, multi-tenant accounts or a reason to weaken the IR. Do not add agent teams or a large catalog of interfaces/targets simply to illustrate this architecture. Extend real boundaries incrementally, keep older artifacts readable, and label future direction separately from implemented capability.

lectic/README.md

@@ -0,0 +1,165 @@
+<div align="center">
+
+# Lectic
+
+### Save what you trust. Your AI learns the method, not just the words.
+
+[![Tests](https://github.com/tyreamer/lectic/actions/workflows/tests.yml/badge.svg)](https://github.com/tyreamer/lectic/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/lectic?color=4b8bba)](https://pypi.org/project/lectic/)
+[![Python: 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab)](https://github.com/tyreamer/lectic/blob/main/docs/DEVELOPING.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-4b8bba)](https://github.com/tyreamer/lectic/blob/main/LICENSE)
+[![Status: Alpha](https://img.shields.io/badge/status-alpha-f0b44d)](#current-status)
+
+**[Start](#start)** · **[What it does](#what-it-does)** · **[Examples](#what-you-can-build)** · **[How it works](#how-it-works)** · **[Status](#current-status)**
+
+Works with **Claude Code** · **Codex** · **ChatGPT** · **Claude** · **Gemini CLI** · any MCP client
+
+</div>
+
+You watch a great talk, read a course, keep a transcript from someone who really knows their craft. Lectic turns that material into expertise your assistant can *apply*: reviewers, checklists, decision frameworks, lessons — each one traceable back to the exact words that support it. Save once; every assistant you use can apply it, from any project, on any machine you point at it.
+
+## Start
+
+```bash
+pip install lectic
+lectic setup
+```
+
+`lectic setup` connects Claude Code and Codex if they are installed, verifies the connection, and offers YouTube support. Then open either assistant, in any folder, and talk:
+
+> Save this for later: https://www.youtube.com/watch?v=…
+
+> What could my saved material become?
+
+> Use my Sales Training to review this call transcript.
+
+That's the whole interface. No commands to learn, no goal to invent up front, nothing to re-upload later. `lectic status` shows where your knowledge lives and what is connected.
+
+**Use ChatGPT, Claude on the web, or Gemini?** One more command gives them the same knowledge:
+
+```bash
+lectic share
+```
+
+It prints a private link and where to paste it. Your phone can post captures to the same link. To keep the link up when the laptop is closed, run the same server always-on ([guide](https://github.com/tyreamer/lectic/blob/main/docs/CLOUD.md)). Windows and macOS alike; Python 3.10+ is the only requirement.
+
+<details>
+<summary>Prefer an installed skill?</summary>
+
+The installed skill (`/lectic` in Claude Code, `$lectic` in Codex) drives the same compiler through your assistant's file access and remains supported; see [installation](https://github.com/tyreamer/lectic/blob/main/docs/INSTALLATION.md).
+
+</details>
+
+## What it does
+
+**Saving is free.** Share a link, paste text, or point at a folder of transcripts. Nothing is processed until you want something from it, and your reason for saving stays separate from the source.
+
+**You don't need a plan.** Ask what a collection could become and Lectic returns a ranked map of concrete jobs it can support: what you'd give it, what you'd get back, and where the evidence runs out. Pick one and it builds it.
+
+**Results carry their evidence.** A review, a checklist, a lesson, a decision — every point cites the source passage behind it, and source statements stay distinct from the assistant's inference.
+
+**Build once, reuse everywhere.** A method built from your Sales Training today reviews a different call tomorrow, from ChatGPT, Claude, Gemini, Codex or Claude Code, in any project, with no re-upload. Add sources later and earlier work is preserved.
+
+**Share what you know.** `lectic pack "FC 27"` turns a collection into one file. Anyone runs `lectic install` on it and every assistant they use can apply it. Sources travel as links and are verified on the installer's own network, so nothing is redistributed ([packs →](https://github.com/tyreamer/lectic/blob/main/docs/PACKS.md)).
+
+## What you can build
+
+| Material | Useful capability | Give it → get back |
+| --- | --- | --- |
+| Photography lessons | **Portrait Critic** | Portrait and settings → focus/motion checks and a retake plan |
+| Sales training | **Discovery Call Reviewer** | Call transcript → missed questions and concrete follow-ups |
+| Architecture talks | **Architecture Review Checklist** | Access-control design → scoped issues and verification steps |
+| Business strategy lessons | **Market Decision Framework** | Market hypotheses → conditional comparison and missing evidence |
+
+**Capabilities follow the evidence.** If the material lacks procedures, criteria, examples or conditions, the map says so instead of inventing them. These examples come from small synthetic fixtures and illustrate the kinds of transformation supported, not measured effectiveness. [Explore the fixtures →](https://github.com/tyreamer/lectic/blob/main/fixtures/opportunities/README.md)
+
+## How it works
+
+```mermaid
+flowchart TD
+    A[Capture or import] --> B[Source collection]
+    B --> C[Durable expertise IR]
+    C --> D[Capability Map or user goal]
+    D --> E[Compiled method]
+    E --> F[Text result or skill artifact]
+    F --> G[Structure and evidence validation]
+    G -. Optional facilitated comparison .-> H[Evaluate and refine]
+```
+
+The **Expertise IR** is the durable asset. Capability Maps are versioned interpretations of it; methods and outputs are builds from it. The MCP server and the installed skill are two interfaces to the same compiler, and Agent Skills is one output target. The core remains independent of a particular AI provider.
+
+Knowledge lives in one **Lectic home** per user (`~/.lectic`, or `LECTIC_HOME`): original sources as content-addressed blobs, normalized segments, knowledge revisions, maps, private briefs and saved builds. Interrupted workflows retain checkpoints. Every project and every assistant on the machine sees the same collections. A project that already contains a `.expertise-compiler/` folder keeps using it; ask “Where does Lectic store my knowledge?” to see which applies.
+
+[Architecture and remaining boundaries →](https://github.com/tyreamer/lectic/blob/main/DESIGN.md)
+
+## Capture now, use later
+
+Save things as you meet them, with a reason if you have one, and sort them into collections later or never:
+
+> Save this architecture talk. Great on permission boundaries, but don't treat it as company policy.
+
+> Use my AI Architecture collection to review this design.
+
+Saving stores exactly what you shared and your note, nothing more. Processing happens when a use needs it. YouTube links become English captions on request (through `yt-dlp`, which `lectic setup` offers to install); other links stay saved as links. Lectic does not fetch article bodies, parse PDFs, OCR images, scrape social platforms or transcribe audio, and an unavailable caption stays a visible gap rather than a made-up summary.
+
+From a phone, a two-action Share Sheet Shortcut posts straight to your Lectic link ([guide](https://github.com/tyreamer/lectic/blob/main/docs/CLOUD.md#your-phone)); a [synced-folder Shortcut](https://github.com/tyreamer/lectic/blob/main/docs/iphone-shortcut.md) remains for phones that cannot reach it.
+
+[Capture contract, states and sync details →](https://github.com/tyreamer/lectic/blob/main/docs/CAPTURE.md)
+
+## Current status
+
+| Area | Available today | Boundary |
+| --- | --- | --- |
+| Processing | Text/transcript files and deferred YouTube English-caption retrieval | Optional `yt-dlp` required for YouTube; no arbitrary URL or audio/video acquisition |
+| Discovery | Grounded, ranked Capability Maps with version history | Quality depends on source support and assistant interpretation |
+| Outputs | Reusable text methods, work products, optional skill exports, shareable knowledge packs | No standalone agent runtime or persistent coaching service |
+| Capture | Phone or assistant posts to `/capture`; synced-folder import; annotations and multiple memberships | Saving stores what was shared; only YouTube captions are retrieved, on request |
+| Validation | Schemas, hashes, evidence references and artifact structure | Does not establish sound judgment or effectiveness |
+| Evaluation | Matched prompts, structured checks and effort records | Independent runs, human review and refinement need coordination |
+
+**Your knowledge, your server, any assistant.** Lectic is a single-user server you run wherever you like: a laptop, a container, a home box. Your assistant does the reasoning; Lectic keeps the results evidence-linked, reusable and yours. Nothing leaves your machine except through the private link you choose to hand out.
+
+### Toward portable knowledge
+
+One knowledge store reachable from a phone, ChatGPT, Claude, Gemini, Codex and Claude Code alike, with local storage as the offline/private mode rather than the only mode. In place: one home per user behind a storage seam built for object storage ([design →](https://github.com/tyreamer/lectic/blob/main/DESIGN.md#storage-one-home-cloud-shaped)); an [MCP server](https://github.com/tyreamer/lectic/blob/main/docs/MCP.md) over stdio and Streamable HTTP so any client operates the compiler through validated tools; `lectic share`, an always-on container and phone capture over one private link ([guide →](https://github.com/tyreamer/lectic/blob/main/docs/CLOUD.md)). Still ahead: a remote object store behind the seam, so several machines can share one home without one of them being the server.
+
+## Test the idea with us
+
+The automated suite covers provenance, revisions, capture, discovery, builds and reuse across unrelated fixtures. Semantic fixture answers are authored test data; they are not evidence that the compiler outperforms ordinary chat.
+
+We are testing with **AI builders, consultants, creators and knowledge-heavy professionals**. The study includes fair baseline comparisons, fresh-session reuse, source changes and refinement on unseen tasks.
+
+**[Start with the concept-validation guide →](https://github.com/tyreamer/lectic/blob/main/docs/testing-guide.md)**
+
+## Documentation
+
+| Guide | Purpose |
+| --- | --- |
+| [Installation](https://github.com/tyreamer/lectic/blob/main/docs/INSTALLATION.md) | Setup, updates and troubleshooting |
+| [MCP server](https://github.com/tyreamer/lectic/blob/main/docs/MCP.md) | Connect Claude Code, Codex or any MCP client; tools and write policy |
+| [Anywhere](https://github.com/tyreamer/lectic/blob/main/docs/CLOUD.md) | ChatGPT, Claude, Gemini, your phone, a second computer: one private link |
+| [Packs](https://github.com/tyreamer/lectic/blob/main/docs/PACKS.md) | Share a collection as one file; install someone else's |
+| [YouTube retrieval](https://github.com/tyreamer/lectic/blob/main/docs/YOUTUBE.md) | Paste links, retrieve captions on demand, preserve evidence and reuse it |
+| [Guided use](https://github.com/tyreamer/lectic/blob/main/docs/GUIDED-USE.md) | See what is saved, discover concrete applications and reuse it |
+| [iPhone Shortcut](https://github.com/tyreamer/lectic/blob/main/docs/iphone-shortcut.md) | Capture setup and exact first live test |
+| [Evaluation](https://github.com/tyreamer/lectic/blob/main/docs/EVALUATION.md) | Compare against capable ordinary transcript chat |
+| [Architecture](https://github.com/tyreamer/lectic/blob/main/DESIGN.md) | Current boundaries, storage and limitations |
+| [North star](https://github.com/tyreamer/lectic/blob/main/NORTH_STAR.md) | Product direction and extensible build targets |
+| [Development](https://github.com/tyreamer/lectic/blob/main/docs/DEVELOPING.md) | Code structure, tests and contribution workflow |
+| [CLI reference](https://github.com/tyreamer/lectic/blob/main/docs/CLI.md) | Deterministic utilities operated by the assistant |
+
+## Contributing
+
+Useful contributions include reproducible failures, evidence-quality improvements and observations from real tasks. Follow the [development guide](https://github.com/tyreamer/lectic/blob/main/docs/DEVELOPING.md) and preserve the separation between source content, personal context, expertise and builds.
+
+Run the existing suite from a checkout:
+
+```sh
+python -m unittest discover -s tests -v
+```
+
+[Report an issue](https://github.com/tyreamer/lectic/issues) with a minimal, sanitized example. Keep private corpora and client work out of public reports.
+
+## License
+
+[MIT](https://github.com/tyreamer/lectic/blob/main/LICENSE). Imported content retains its original ownership and licensing; a citation does not grant redistribution rights.