Upload 3 files

docs/ARCHITECTURE.md

@@ -0,0 +1,47 @@
+# Architecture
+
+## V2 foundation
+
+This repository is the first safe foundation for a Hugging Face-native Agentic Space Factory.
+
+```text
+User
+  ↓
+Gradio orchestrator Space with HF OAuth
+  ↓
+HF Job launched with the user's OAuth token
+  ↓
+Mounted private Storage Bucket at /output
+  ↓
+Optional private target Space creation
+  ↓
+Live Gradio API validation
+  ↓
+Bucket report + state + events
+```
+
+## Current phases
+
+### Phase 1 — Hello Job
+
+Validates:
+
+```text
+OAuth → Jobs scope → HF Job → mounted Bucket → readback UI
+```
+
+### Phase 2 — Private target Space
+
+Validates:
+
+```text
+OAuth → HF Job → create private Gradio Space → upload files → live API test → report
+```
+
+The target Space is private by default and must be created in the signed-in user's namespace.
+
+## Why Phase 2 is intentionally simple
+
+Before adding Pi, model-card analysis, or ZeroGPU, we need to prove that the system can safely create a target Space and validate it through the live API.
+
+That live API validation gate will later remain the core success criterion.

docs/NEXT_STEPS.md

@@ -0,0 +1,57 @@
+# Next steps
+
+## Current milestone
+
+V2 validates private Space creation and live Gradio API validation.
+
+## Phase 3 — Pi inside the Job
+
+Add Pi as the first agentic runtime:
+
+```text
+HF Job
+→ install Pi
+→ configure HF Inference Providers
+→ give Pi a simple goal
+→ let Pi modify the generated hello Space
+→ upload files
+→ validate live API
+→ collect Pi traces from ~/.pi/agent/sessions
+→ copy raw/private traces into the Bucket
+```
+
+The first Pi task should be deliberately small:
+
+```text
+Improve the title/description/examples of the generated Gradio app.
+Do not change the function signature.
+Do not mark success until the live Gradio API test passes.
+```
+
+## Phase 4 — Apply the gist recipe
+
+Give Pi a goal close to the article:
+
+```text
+Read the HF Spaces Agent Quickstart gist.
+The deployed Space is your AI lab.
+Use hf CLI / Hub API.
+Read logs before patching.
+Verify through gradio_client.
+Do not declare success until live API validation passes.
+```
+
+## Phase 5 — First model-card template
+
+Add one narrow model family, ideally a simple Transformers pipeline or a standard Diffusers text-to-image model.
+
+## Phase 6 — ZeroGPU
+
+Add a ZeroGPU-specific Gradio template with `@spaces.GPU` only around inference.
+
+## Phase 2.1 fix
+
+This version fixes private Space validation with `gradio_client>=2.0.0`, whose
+`Client` constructor uses `token=` instead of `hf_token=`. The worker now uses
+signature introspection so older/newer versions can still work. Bucket events
+are also printed to stdout so HF Job logs are readable while the worker runs.

docs/SECURITY.md

@@ -0,0 +1,40 @@
+# Security notes
+
+## OAuth token handling
+
+The orchestrator uses Gradio + Hugging Face OAuth.
+
+The OAuth token is used in two places:
+
+1. `token=token` when launching/managing the Job.
+2. `secrets={"HF_TOKEN": token}` so the Job can act on behalf of the user.
+
+Workers must never print or persist the token.
+
+## Scope notes
+
+The Space metadata requests:
+
+- `read-repos`
+- `write-repos`
+- `manage-repos`
+- `gated-repos`
+- `inference-api`
+- `jobs`
+
+`jobs` is required for launching HF Jobs. `manage-repos` is currently used for private Space creation. A later hardening pass should test whether a narrower scope can replace it.
+
+## Private by default
+
+- Bucket remains private.
+- Target Spaces are created private.
+- Existing target Spaces are not overwritten.
+- Publishing must be added later as an explicit user action only.
+
+## Trace privacy
+
+Future Pi traces must be stored as raw/private first. A redacted copy may be generated later, but public sharing should require explicit user confirmation.
+
+## Current limitations
+
+The redaction helper is a basic first-pass scanner. It is not a full data-loss prevention system.