init: AFS Scawful baseline (config helpers)

AGENTS.md

@@ -0,0 +1,22 @@
+# Agent Instructions (AFS Scawful Plugin)
+
+## Do not invent or market
+- No marketing language or product claims.
+- If something is unknown, state "Unknown / needs verification" and propose a test.
+
+## Truth policy
+- Only claim what is evidenced in this repo or cited notes.
+- Do not guess roadmap, compatibility, or performance.
+
+## Scope control
+- Research-only plugin scope; keep to Scawful-specific tooling.
+
+## Provenance / separation
+- Do not use employer or internal material.
+- If provenance is unclear, leave it out.
+
+## Output style
+- Concise, engineering notebook tone.
+
+## How to verify (tests/commands)
+- Unknown / needs verification (no test harness yet).

LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2025 scawful
+
+All rights reserved.
+
+This repository is research-only and is not licensed for redistribution,
+modification, or commercial use without explicit permission.

README.md

@@ -0,0 +1,12 @@
+# AFS Scawful Plugin
+
+Research-only. Not a product.
+
+Scope: Scawful-specific plugin utilities, generators, and validators.
+
+Provenance: avoid employer/internal sources; skip unclear origins.
+
+Docs:
+- `docs/STATUS.md`
+- `docs/ROADMAP.md`
+- `docs/REPO_FACTS.json`

docs/REPO_FACTS.json

@@ -0,0 +1,18 @@
+{
+  "name": "afs-scawful",
+  "stage": "prototype",
+  "is_product": false,
+  "commercial_intent": "none",
+  "verified_features": [],
+  "hard_no": [
+    "enterprise",
+    "production-ready",
+    "platform",
+    "seamless",
+    "scalable",
+    "best-in-class",
+    "state-of-the-art",
+    "robust",
+    "official"
+  ]
+}

docs/ROADMAP.md

@@ -0,0 +1,13 @@
+# ROADMAP
+
+## Committed
+- Minimal module layout + package stubs
+- One small utility
+
+## Planned
+- Local config template
+- Example generator
+
+## Ideas
+- Idea: Local validation hooks for training data
+- Idea: Minimal dataset manifest generator

docs/STATUS.md

@@ -0,0 +1,7 @@
+# STATUS
+
+Stage: Prototype
+Now: package stub; guardrails; config helpers for training paths/resources.
+Not yet: plugin features; generators.
+Next: minimal plugin layout; one small utility.
+Issues: no runtime yet.

pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "afs_scawful"
+version = "0.0.0"
+description = "AFS Scawful plugin package"
+requires-python = ">=3.11"
+license = {text = "All rights reserved"}
+authors = [
+  {name = "scawful"}
+]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

src/afs_scawful/__init__.py

@@ -0,0 +1,7 @@
+"""AFS Scawful package stub."""
+
+__version__ = "0.0.0"
+
+from .config import load_training_paths, load_training_resources
+
+__all__ = ["load_training_paths", "load_training_resources"]

src/afs_scawful/config.py

@@ -0,0 +1,61 @@
+"""AFS Scawful plugin config helpers."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def _expand_path(path: str | Path) -> Path:
+    return Path(path).expanduser().resolve()
+
+
+def _default_config_dirs() -> list[Path]:
+    repo_root = Path(__file__).resolve().parents[2]
+    return [
+        Path.home() / ".config" / "afs" / "afs_scawful",
+        Path.home() / ".config" / "afs" / "plugins" / "afs_scawful" / "config",
+        repo_root / "config",
+    ]
+
+
+def _find_config(filename: str) -> Path | None:
+    for base in _default_config_dirs():
+        candidate = base / filename
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _load_toml(path: Path | None) -> dict[str, Any]:
+    if not path or not path.exists():
+        return {}
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def load_training_paths(config_path: Path | None = None) -> dict[str, dict[str, Path]]:
+    path = config_path or _find_config("training_paths.toml")
+    data = _load_toml(path)
+    expanded: dict[str, dict[str, Path]] = {}
+    for section in ["paths", "knowledge_bases"]:
+        if section in data and isinstance(data[section], dict):
+            expanded[section] = {
+                key: _expand_path(value)
+                for key, value in data[section].items()
+                if isinstance(value, str)
+            }
+    return expanded
+
+
+def load_training_resources(config_path: Path | None = None) -> dict[str, Any]:
+    path = config_path or _find_config("training_resources.toml")
+    data = _load_toml(path)
+    if "resource_discovery" in data and isinstance(data["resource_discovery"], dict):
+        resource = data["resource_discovery"]
+        if "resource_roots" in resource:
+            resource["resource_roots"] = [
+                _expand_path(p) for p in resource["resource_roots"] if isinstance(p, str)
+            ]
+    return data