Add research sources catalog and CLI plan

.gitignore

@@ -1,3 +1,6 @@
 /.vscode/
 /build/
+__pycache__/
+*.pyc
+.pytest_cache/
 .DS_Store

README.md

@@ -11,6 +11,8 @@ Docs:
 - `docs/ROADMAP.md`
 - `docs/REPO_FACTS.json`
 - `docs/NARRATIVE.md`
+- `docs/RESEARCH_SOURCES.md`
+- `docs/CLI_PLAN.md`
 - `docs/PORTING_MAP.md`
 
 Quickstart:

docs/CLI_PLAN.md

@@ -0,0 +1,35 @@
+# CLI Plan (AFS)
+
+Scope: improve AFS CLI ergonomics for agent workflows. Research-only; no product
+claims. See `docs/RESEARCH_SOURCES.md` for citations.
+
+## Principles (with citations)
+- Prefer a minimal, execution-aware tool surface over large ad hoc command sets. [R3]
+- Make context flow explicit (state + errors + async boundaries). [R4]
+- Treat context as a persistent filesystem surface, not transient prompt state. [R1]
+- Add observability hooks as systems scale (logs, summaries, eval hooks). [R2]
+
+## Phase 0 (now)
+- Document existing commands and config defaults in `README.md`.
+- Add `--json` output for `status`, `context validate`, `context discover`, and `graph export`.
+- Add `afs config show` (effective config + defaults).
+
+## Phase 1 (near-term)
+- `afs context report` to emit a single summary JSON (roots, missing dirs, counts).
+- `afs graph export --format dot|json` (JSON already present; define schema version).
+- `afs services render --format` and `--output` for integration with runbooks.
+
+## Phase 2 (later)
+- `afs workspace lint` to catch missing `workspaces.toml` entries.
+- `afs context diff` (two roots) to compare catalog drift.
+- Optional: plugin registry summary to surface installed plugins and version pins.
+
+## Unknown / needs verification
+- Which commands agents actually use most in production flows.
+- Whether a TUI is needed beyond `afs_studio`.
+
+## Citations
+- [R1] `docs/RESEARCH_SOURCES.md`
+- [R2] `docs/RESEARCH_SOURCES.md`
+- [R3] `docs/RESEARCH_SOURCES.md`
+- [R4] `docs/RESEARCH_SOURCES.md`

docs/NARRATIVE.md

@@ -4,6 +4,8 @@ AFS is a research-only internal system focused on structuring context and workfl
 for agentic tools. This repo tracks experiments and implementations; claims should
 map to code or docs.
 
+Full research catalog: `docs/RESEARCH_SOURCES.md`.
+
 ## Source papers (in `~/Documents/Research`)
 - `2512.05470v1.pdf` — "Everything is Context: Agentic File System Abstraction for Context Engineering"
 - `2512.08296.pdf` — "Towards a Science of Scaling Agent Systems"

docs/RESEARCH_SOURCES.md

@@ -0,0 +1,53 @@
+# Research Sources
+
+Catalog of PDFs referenced by AFS / AFS Scawful docs. Metadata and abstract
+excerpts are auto-extracted; verify against the PDFs before quoting.
+
+## R1 — Everything is Context: Agentic File System Abstraction for Context Engineering
+- File: `/Users/scawful/Documents/Research/2512.05470v1.pdf`
+- Title (metadata): Everything is Context: Agentic File System Abstraction for Context Engineering
+- Authors (metadata): Xiwei Xu; Robert Mao; Quan Bai; Xuewu Gu; Yechao Li; Liming Zhu
+- Abstract excerpt (auto-extracted, truncated): Generative AI (GenAI) has reshaped software system design by introducing foundation models as pre-trained subsystems that redefine architectures and operations. The emerging challenge is no longer model fine-tuning but context engineering... This paper proposes a file-system abstraction for context engineering, inspired by the Unix notion that "everything is a file." The abstraction offers a persistent, governed infrastructure for managing heterogeneous context...
+- Used in: `docs/NARRATIVE.md`, `docs/CLI_PLAN.md`
+
+## R2 — Towards a Science of Scaling Agent Systems
+- File: `/Users/scawful/Documents/Research/2512.08296.pdf`
+- Title (metadata): Towards a Science of Scaling Agent Systems
+- Authors (metadata): Yubin Kim; Ken Gu; Chanwoo Park; Chunjong Park; Samuel Schmidgall; A. Ali Heydari; Yao Yan; Zhihan Zhang; Yuchen Zhuang; Mark Malhotra; Paul Pu Liang; Hae Won Park; Yuzhe Yang; Xuhai Xu; Yilun Du; Shwetak Patel; Tim Althoff; Daniel McDuff; Xin Liu
+- Abstract excerpt: Unknown / not extracted
+- Used in: `docs/CLI_PLAN.md`
+
+## R3 — One Tool Is Enough: Reinforcement Learning for Repository-Level LLM Agents
+- File: `/Users/scawful/Documents/Research/2512.20957v2.pdf`
+- Title (metadata): One Tool Is Enough: Reinforcement Learning for Repository-Level LLM Agents
+- Authors (metadata): Zhaoxi Zhang; Yitong Duan; Yanzhi Zhang; Yiming Xu; Jiyan He; Yunfang Wu
+- Abstract excerpt (auto-extracted, truncated): Locating the files and functions requiring modification in large open-source software (OSS) repositories is challenging due to their scale and structural complexity. Existing LLM-based methods typically treat this as a repository-level retrieval task and rely on multiple auxiliary tools... We propose RepoNavigator, an LLM agent equipped with a single execution-aware tool... trained end-to-end via Reinforcement Learning (RL)...
+- Used in: `docs/TRAINING_PLAN.md`, `docs/CLI_PLAN.md`
+
+## R4 — Monadic Context Engineering
+- File: `/Users/scawful/Documents/Research/2512.22431.pdf`
+- Title (metadata): Monadic Context Engineering
+- Authors (metadata): Yifan Zhang; Mengdi Wang
+- Abstract excerpt (auto-extracted, truncated): The proliferation of Large Language Models (LLMs) has catalyzed a shift towards autonomous agents capable of complex reasoning and tool use. However, current agent architectures are frequently constructed using imperative, ad hoc patterns... This paper introduces Monadic Context Engineering (MCE), a novel architectural paradigm leveraging the algebraic structures of Functors, Applicative Functors, and Monads...
+- Used in: `docs/TRAINING_PLAN.md`, `docs/CLI_PLAN.md`
+
+## R5 — SonicMoE: Accelerating MoE with IO and Tile-aware Optimizations
+- File: `/Users/scawful/Documents/Research/2512.14080.pdf`
+- Title (metadata): SonicMoE: Accelerating MoE with IO and Tile-aware Optimizations
+- Authors (metadata): Wentao Guo; Mayank Mishra; Xinle Cheng; Ion Stoica; Tri Dao
+- Abstract excerpt (auto-extracted, truncated): Mixture of Experts (MoE) models have emerged as the de facto architecture for scaling up language models without significantly increasing the computational cost... However, fine-grained MoEs suffer from increased activation memory footprint and reduced hardware efficiency due to higher IO costs...
+- Used in: `docs/TRAINING_PLAN.md`
+
+## R6 — 2510.04950v1.pdf (metadata appears generic)
+- File: `/Users/scawful/Documents/Research/2510.04950v1.pdf`
+- Title (metadata): ArXiv
+- Authors (metadata): Om
+- Abstract excerpt (auto-extracted, truncated): The wording of natural language prompts has been shown to influence the performance of large language models (LLMs)... We investigate how varying levels of prompt politeness affect model accuracy on multiple-choice questions... impolite prompts consistently outperformed polite ones...
+- Used in: `docs/TRAINING_PLAN.md`
+
+## R7 — 7799_Quantifying_Human_AI_Syne.pdf (metadata missing)
+- File: `/Users/scawful/Documents/Research/7799_Quantifying_Human_AI_Syne.pdf`
+- Title (metadata): Unknown / not present in PDF metadata
+- Authors (metadata): Unknown / not present in PDF metadata
+- Abstract excerpt (auto-extracted, truncated): We introduce a novel Bayesian Item Response Theory framework to quantify human-AI synergy, separating individual and collaborative ability while controlling for task difficulty in interactive settings... We validate the framework by applying it to human-AI benchmark data and find significant synergy...
+- Used in: `docs/TRAINING_PLAN.md`