docs: prepare Hugging Face paper materials

PHASE5D_HUGGINGFACE_PAPER_PREP_SNAPSHOT.md

@@ -0,0 +1,110 @@
+# Phase 5D Hugging Face Paper Preparation Snapshot
+
+## 1. Scope Accomplished
+
+Created preparation materials for later arXiv and Hugging Face publication of the `sparkctl` project.
+
+Branch:
+
+```text
+paper-hf-prep
+```
+
+Created files:
+
+```text
+paper/sparkctl-paper.md
+paper/related-work-notes.md
+huggingface/README-space.md
+huggingface/README-dataset.md
+PHASE5D_HUGGINGFACE_PAPER_PREP_SNAPSHOT.md
+```
+
+## 2. Paper Draft
+
+`paper/sparkctl-paper.md` defines a short technical project report with:
+
+- abstract
+- introduction
+- motivation
+- system overview
+- package core
+- schema sidecar
+- operational context layer
+- sparkctl command surface
+- validation scope
+- limitations
+- Hugging Face publication plan
+- arXiv metadata draft
+- Hugging Face README snippet
+
+## 3. Hugging Face Preparation
+
+Prepared two Hugging Face README templates:
+
+```text
+huggingface/README-space.md
+huggingface/README-dataset.md
+```
+
+Recommended future Hugging Face repos:
+
+```text
+ProfRandom92/sparkctl-demo
+ProfRandom92/sparkctl-context-artifacts
+```
+
+Paper Page placeholder:
+
+```text
+https://huggingface.co/papers/TODO
+```
+
+This must be replaced after arXiv publication or HF paper indexing.
+
+## 4. Research Notes
+
+`paper/related-work-notes.md` records candidate topic clusters and Hugging Face paper-search starting points for manual review.
+
+Formal bibliography creation was not completed in this phase. Candidate metadata must be manually verified before arXiv submission.
+
+## 5. Claim Hygiene Result
+
+Prepared text avoids:
+
+- official SPARK compatibility claims
+- EU AI Act compliance claims
+- fully deterministic claims
+- 100% safe claims
+- no-risk claims
+
+Approved wording retained:
+
+- Offline behavior was deterministic in the validated test scope.
+- Configured leak checks passed in the validated scope.
+- No blocking risks found in the validated scope.
+
+## 6. Validation
+
+Documentation-only change. No Rust source code, schemas, examples, artifacts, or cargo files were modified.
+
+No local cargo validation was run from the connector context.
+
+## 7. Known Limitations
+
+- arXiv upload was not performed.
+- Hugging Face Space/Dataset repos were not created from this connector context.
+- Paper Page cannot be finalized until an arXiv identifier or indexed paper page exists.
+- Related-work citations require manual metadata verification.
+
+## 8. Next
+
+Recommended next actions:
+
+1. Review `paper/sparkctl-paper.md`.
+2. Convert Markdown paper to LaTeX or arXiv-compatible PDF.
+3. Submit to arXiv if desired.
+4. Create Hugging Face Space `ProfRandom92/sparkctl-demo`.
+5. Create Hugging Face Dataset `ProfRandom92/sparkctl-context-artifacts` if artifacts should be hosted.
+6. Replace `TODO` paper links after arXiv/HF indexing.
+7. Open or merge the `paper-hf-prep` branch after review.

huggingface/DEPLOY_TO_HF.md

@@ -0,0 +1,100 @@
+# Deploy to Hugging Face
+
+The Hugging Face connector is authenticated as `Profrandom`, but HF Jobs upload failed because the account currently has insufficient prepaid credits. Use this file to deploy manually or from a local shell.
+
+## Target repos
+
+```text
+https://huggingface.co/spaces/Profrandom/sparkctl-demo
+https://huggingface.co/datasets/Profrandom/sparkctl-context-artifacts
+```
+
+## Option A — Hugging Face web UI
+
+1. Create a new Space:
+   - Owner: `Profrandom`
+   - Name: `sparkctl-demo`
+   - SDK: `Gradio`
+   - Visibility: public
+   - License: MIT
+2. Upload the contents of:
+
+```text
+huggingface/space/
+```
+
+3. Create a new Dataset:
+   - Owner: `Profrandom`
+   - Name: `sparkctl-context-artifacts`
+   - Visibility: public
+   - License: MIT
+4. Upload:
+
+```text
+huggingface/dataset/README.md
+```
+
+5. Add reviewed artifacts only after confirming they contain no secrets or private trace data.
+
+## Option B — local CLI
+
+Install dependencies:
+
+```bash
+pip install -U huggingface_hub
+huggingface-cli login
+```
+
+Create repos:
+
+```bash
+python - <<'PY'
+from huggingface_hub import create_repo
+create_repo('Profrandom/sparkctl-demo', repo_type='space', space_sdk='gradio', exist_ok=True, private=False)
+create_repo('Profrandom/sparkctl-context-artifacts', repo_type='dataset', exist_ok=True, private=False)
+PY
+```
+
+Upload files:
+
+```bash
+python - <<'PY'
+from huggingface_hub import HfApi
+api = HfApi()
+api.upload_folder(
+    repo_id='Profrandom/sparkctl-demo',
+    repo_type='space',
+    folder_path='huggingface/space',
+    commit_message='Prepare sparkctl demo Space placeholder',
+)
+api.upload_folder(
+    repo_id='Profrandom/sparkctl-context-artifacts',
+    repo_type='dataset',
+    folder_path='huggingface/dataset',
+    commit_message='Prepare sparkctl context artifacts dataset placeholder',
+)
+PY
+```
+
+## Option C — GitHub Actions sync later
+
+A future workflow can sync `huggingface/space` to the Space using `huggingface/hub-sync` once an `HF_TOKEN` repository secret is configured.
+
+Do not commit tokens or secrets.
+
+## Claim hygiene
+
+Use only fixture-bound wording:
+
+- Agent trace replay consistency: `1.000000`
+- Agent operational drift: `0.000000`
+- Agent average compression ratio: `1.773954`
+- MCP replay evaluation: deterministic, no LLM judges, no external APIs
+
+Avoid:
+
+- compliance claims
+- official SPARK compatibility claims
+- production-readiness claims
+- unrestricted safety claims
+- universal compression performance claims

huggingface/README-dataset.md

@@ -0,0 +1,51 @@
+---
+pretty_name: sparkctl Context Artifacts
+license: mit
+task_categories:
+- text-generation
+language:
+- en
+tags:
+- agents
+- context-compression
+- deterministic-replay
+- rust
+- validation
+---
+
+# sparkctl Context Artifacts
+
+This dataset repository is intended to host example artifacts for the Antigravity-CompText v7 / SPARK Context Layer project.
+
+Primary GitHub repository:
+
+https://github.com/ProfRandom92/Antigravity-Comptextv7
+
+Paper placeholder:
+
+https://arxiv.org/abs/TODO
+
+Hugging Face Paper Page placeholder:
+
+https://huggingface.co/papers/TODO
+
+## Suggested uploaded files
+
+```text
+examples/spark/extraction.json
+schemas/genehmigung_v1.json
+artifacts/spark/context.json
+artifacts/spark/context_render.txt
+```
+
+Do not upload private traces, secrets, raw credentials, proprietary customer data, or unreviewed local files.
+
+## Scope
+
+These artifacts are examples for local tooling and documentation. They are not a benchmark claim, compliance artifact, or official SPARK certification.
+
+Approved validation wording:
+
+- Offline behavior was deterministic in the validated test scope.
+- Configured leak checks passed in the validated scope.
+- No blocking risks found in the validated scope.

huggingface/README-space.md

@@ -0,0 +1,61 @@
+---
+title: sparkctl Demo
+emoji: ⚡
+colorFrom: yellow
+colorTo: blue
+sdk: gradio
+app_file: app.py
+pinned: false
+---
+
+# sparkctl Demo
+
+`sparkctl` is the local operations controller for the Antigravity-CompText v7 / SPARK Context Layer project.
+
+It bundles local diagnostics, Rust validation, context-pipeline orchestration, demo execution, and repository handoff checks into one command surface.
+
+## Links
+
+- GitHub: https://github.com/ProfRandom92/Antigravity-Comptextv7
+- Paper: https://arxiv.org/abs/TODO
+- Hugging Face Paper Page: https://huggingface.co/papers/TODO
+
+## What the demo should show
+
+The demo should present the local `sparkctl` workflow without claiming hosted execution parity:
+
+```bash
+cargo run --bin sparkctl -- doctor
+cargo run --bin sparkctl -- rust-validate
+cargo run --bin sparkctl -- context-all
+cargo run --bin sparkctl -- spark-demo
+cargo run --bin sparkctl -- handoff-check
+```
+
+## Artifact flow
+
+```text
+examples/spark/extraction.json
+  -> artifacts/spark/extraction.spkg
+  -> artifacts/spark/context.json
+  -> artifacts/spark/context_render.txt
+```
+
+## Scope and boundaries
+
+Offline behavior was deterministic in the validated test scope. Configured leak checks passed in the validated scope. No blocking risks found in the validated scope.
+
+No official SPARK compatibility claim is made. No regulatory compliance claim is made.
+
+## Suggested Space implementation
+
+For a lightweight Hackathon demo, use a Gradio UI that displays:
+
+1. project overview
+2. command surface
+3. artifact flow
+4. rendered example context
+5. safety boundaries
+6. links to GitHub and paper
+
+Avoid executing arbitrary user commands in the Space.

huggingface/dataset/README.md

@@ -0,0 +1,52 @@
+---
+pretty_name: sparkctl Context Artifacts
+license: mit
+language:
+- en
+tags:
+- agents
+- context-compression
+- deterministic-replay
+- rust
+- validation
+- sparkctl
+---
+
+# sparkctl Context Artifacts
+
+Placeholder dataset repository for reviewed example artifacts from the Antigravity-CompText v7 / SPARK Context Layer project.
+
+## Source repositories
+
+- sparkctl / Antigravity integration: https://github.com/ProfRandom92/Antigravity-Comptextv7
+- CompText V7 benchmark artifacts: https://github.com/ProfRandom92/Comptextv7
+
+## Suggested uploaded files after review
+
+```text
+examples/spark/extraction.json
+schemas/genehmigung_v1.json
+artifacts/spark/context.json
+artifacts/spark/context_render.txt
+artifacts/agent_trace_replay_results.json
+artifacts/mcp_trace_replay_results.json
+artifacts/token_latency_results.json
+artifacts/iterative_replay_degradation_results.summary.md
+```
+
+Do not upload private traces, secrets, raw credentials, proprietary customer data, or unreviewed local files.
+
+## Fixture-bound benchmark snapshot
+
+From committed `Comptextv7` artifacts:
+
+- Agent trace replay consistency: `1.000000`
+- Agent operational drift: `0.000000`
+- Agent average compression ratio: `1.773954`
+- MCP replay evaluation: deterministic, no LLM judges, no external APIs
+
+These values are fixture-bound and based on checked-in repository artifacts.
+
+## Non-claims
+
+This dataset placeholder is not a benchmark certification, compliance artifact, production-readiness claim, or official SPARK compatibility claim.