From 0d4ee4f1f351c77d32c7ce93604ebf93da83788b Mon Sep 17 00:00:00 2001 From: zrk222 Date: Sat, 8 Aug 2026 23:44:03 -0400 Subject: [PATCH 1/7] docs: improve public discovery surfaces --- README.md | 24 ++++++++++++++++++++---- deploy/huggingface/README.md | 10 +++++++++- deploy/huggingface/index.html | 8 ++++---- docs/GITHUB_DISCOVERY.md | 17 +++++++++++++++++ pyproject.toml | 4 ++++ tests/test_huggingface_surface.py | 12 +++++++++--- tests/test_publication_metadata.py | 14 +++++++++++++- tests/test_release_integrity.py | 2 +- 8 files changed, 77 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a0df9ef..99ceecf 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ -# code-factory +# Code Factory [![CI](https://github.com/zrk222/code-factory/actions/workflows/ci.yml/badge.svg)](https://github.com/zrk222/code-factory/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/factoryline-code-factory.svg)](https://pypi.org/project/factoryline-code-factory/) [![Python](https://img.shields.io/pypi/pyversions/factoryline-code-factory.svg)](https://pypi.org/project/factoryline-code-factory/) [![Hugging Face Space](https://img.shields.io/badge/Hugging%20Face-Space-ffd21e.svg)](https://huggingface.co/spaces/zrk222/code-factory) +[![GitHub stars](https://img.shields.io/github/stars/zrk222/code-factory?style=social)](https://github.com/zrk222/code-factory/stargazers) +[![Latest release](https://img.shields.io/github/v/release/zrk222/code-factory)](https://github.com/zrk222/code-factory/releases/latest) -> One intent, seven software targets, and proof that the gates reject -> deliberately sabotaged builds. +> Turn a plain-language outcome into a reviewable MVP with deterministic proof— +> without pretending generated code is production-ready. > **Why pay for opaque app generators?** Create a reviewable MVP starting state > in minutes—with source-bound receipts, a clear proof path, and an output you @@ -21,7 +23,17 @@ factory studio --root .\my-mvp [Watch the exact shipped UI in 60 seconds](https://github.com/zrk222/code-factory/releases/download/v0.28.0/code-factory-quickstart-v0171.mp4) to see the outcome-to-MVP path, then open **Graph Ops** in the local Studio to -inspect the evidence path and next action. +inspect the evidence path and next action. Prefer a browser preview? Open the +[live Hugging Face Space](https://zrk222-code-factory.static.hf.space). + +**Choose the shortest path:** + +| Goal | Start here | What you get | +| --- | --- | --- | +| Create | `factory mvp "..."` | A contained, app-shaped starting state | +| Inspect | `factory studio --root .` | Graph Ops, receipts, and one next action | +| Connect | [Cursor or OpenCode MCP](docs/AI_CLIENTS.md) | Portable, local proof context | +| Prove | `factory verify --root .` | A fail-closed decision with evidence | ## What Code Factory is @@ -33,6 +45,10 @@ gates; then show what is proven, missing, blocked, or safe to do next. Factory Studio and the editor integrations make the same workflow visible without granting them release, credential, approval, or publishing authority. +It works with the local workflows developers already use—including Codex, +Claude Code, Cursor, OpenCode, VS Code, and JetBrains—through the same +receipt-bound contract rather than a provider-specific lock-in. + It is designed for two speeds: use `factory mvp "..."` to get a novice from idea to an inspectable MVP path, or compose capability packs, signed receipts, proof reuse, Graph Ops impact analysis, and supervised enterprise controls for diff --git a/deploy/huggingface/README.md b/deploy/huggingface/README.md index 01b9654..a95349a 100644 --- a/deploy/huggingface/README.md +++ b/deploy/huggingface/README.md @@ -12,10 +12,13 @@ tags: - devops - software-quality - mcp + - model-context-protocol + - cursor + - opencode - local-first pinned: false license: apache-2.0 -short_description: Reviewable MVPs with verifier, repair, and workspace proof +short_description: Proof-backed AI coding workflows with local MCP context --- # Code Factory @@ -34,6 +37,11 @@ The canonical Python package is Release `v0.28.0` is archived under the repository's stable Zenodo concept DOI at [Zenodo](https://doi.org/10.5281/zenodo.21381405). +Use the same local proof context from Cursor or OpenCode through the documented +[MCP connection](https://github.com/zrk222/code-factory/blob/main/docs/AI_CLIENTS.md). +The client connection is local and read-only; it does not upload source or +grant provider, credential, deployment, or publishing authority. + Before a PRD becomes a scaffold, run `factory prd grill PRD.md --root .` for a capped, source-bound clarification sheet with recommendations and answer stubs. It never rewrites the PRD, invents answers, calls a model, or authorizes a diff --git a/deploy/huggingface/index.html b/deploy/huggingface/index.html index 62a53fb..e6e0abc 100644 --- a/deploy/huggingface/index.html +++ b/deploy/huggingface/index.html @@ -105,7 +105,7 @@
Open source · Local first · Evidence backed

Create your reviewable MVP. See its proof in minutes.

-

Why pay for opaque app generators? Create a reviewable MVP starting state in minutes—with local receipts, a clear proof path, and an output you can extend when you are ready.

+

Why pay for opaque app generators? Create a reviewable MVP starting state in minutes—with local receipts, a clear proof path, and an output you can extend when you are ready. Use the same proof context in Cursor or OpenCode through local MCP.

Start free with pip Watch the exact 60-second UI @@ -232,9 +232,9 @@

Start locally. See the next proof gap immediately.

Free through 2026. Clear before the paid change.

All features are free through December 31, 2026. A $4.95 USD monthly Marketplace price is planned for January 1, 2027, subject to JetBrains paid-plugin approval and a planned 30-day trial. No checkout is live; total price, taxes, fees, and billing terms must be shown before any approved purchase.

- 
Observed Marketplace downloads: 46
-Conversion rate: unavailable without Marketplace views
-Causal uplift: unavailable without attribution
+        
Marketplace count: check the current listing
+Unique installs: not exposed by the listing
+0.8.4 update: pending Marketplace approval
 
 Never substitute CI or repository traffic for installs.
diff --git a/docs/GITHUB_DISCOVERY.md b/docs/GITHUB_DISCOVERY.md index 6aee606..5779615 100644 --- a/docs/GITHUB_DISCOVERY.md +++ b/docs/GITHUB_DISCOVERY.md @@ -25,6 +25,23 @@ The README then shows the shipped UI walkthrough and an optional GitHub-star link. It makes no star-count, download, conversion, productivity, or causal growth claim. +## Client and demo discovery + +Make the first click useful for both novices and experienced AI-tool users: + +- [Live browser preview](https://zrk222-code-factory.static.hf.space) for a + no-install product tour. +- [60-second shipped UI walkthrough](https://github.com/zrk222/code-factory/releases/download/v0.28.0/code-factory-quickstart-v0171.mp4) + for the visual path. +- [Cursor and OpenCode MCP setup](AI_CLIENTS.md) for local, read-only proof + context inside the clients developers already use. +- [PyPI install](https://pypi.org/project/factoryline-code-factory/) for the + shortest executable path. + +Use one of these links per post, with one concrete question or outcome. Do not +paste every channel link into a community thread; the extra links dilute the +action and can look promotional rather than useful. + ## Ethical compounding loop ```mermaid diff --git a/pyproject.toml b/pyproject.toml index 4a2f808..20cbdaa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -25,6 +25,10 @@ keywords = [ "developer-tools", "mvp", "mcp", + "model-context-protocol", + "cursor", + "opencode", + "ai-coding-assistant", "graph-ops", "prd-grill", "independent-verification", diff --git a/tests/test_huggingface_surface.py b/tests/test_huggingface_surface.py index 36be699..4f40116 100644 --- a/tests/test_huggingface_surface.py +++ b/tests/test_huggingface_surface.py @@ -35,6 +35,12 @@ def test_huggingface_space_has_static_metadata_and_canonical_release_links() -> assert "developer-tools" in readme assert "ai-agents" in readme assert "devops" in readme + assert "model-context-protocol" in readme + assert "cursor" in readme + assert "opencode" in readme + assert "Cursor or OpenCode" in readme + assert "Observed Marketplace downloads: 46" not in page + assert "Unique installs: not exposed by the listing" in page assert 'id="first-run"' in page assert "Start free with pip" in page assert "Watch the exact 60-second UI" in page @@ -73,12 +79,12 @@ def test_huggingface_metadata_inspection_rejects_the_remote_api_limit_locally(tm valid_result = inspect(SPACE / "README.md") assert valid_result["ok"] is True assert valid_result["marker"] == "HUGGINGFACE_SPACE_METADATA_VALID" - assert valid_result["short_description_length"] == 58 + assert valid_result["short_description_length"] == 55 invalid_readme = tmp_path / "README.md" invalid_readme.write_text( (SPACE / "README.md").read_text(encoding="utf-8").replace( - "short_description: Reviewable MVPs with verifier, repair, and workspace proof", + "short_description: Proof-backed AI coding workflows with local MCP context", f"short_description: {'x' * 61}", ), encoding="utf-8", @@ -103,7 +109,7 @@ def test_huggingface_metadata_preflight_cli_reports_the_local_result(tmp_path: P invalid_readme = tmp_path / "invalid-README.md" invalid_readme.write_text( (SPACE / "README.md").read_text(encoding="utf-8").replace( - "short_description: Reviewable MVPs with verifier, repair, and workspace proof", + "short_description: Proof-backed AI coding workflows with local MCP context", f"short_description: {'x' * 61}", ), encoding="utf-8", diff --git a/tests/test_publication_metadata.py b/tests/test_publication_metadata.py index 2a03019..364f2ea 100644 --- a/tests/test_publication_metadata.py +++ b/tests/test_publication_metadata.py @@ -44,7 +44,16 @@ def test_pypi_storefront_has_identity_and_canonical_links(): assert project["description"] == ( "Create reviewable MVPs with independent verification, proof review, repair guardrails, and workspace guidance." ) - assert {"mvp", "mcp", "graph-ops", "prd-grill", "verifier-plane"}.issubset(project["keywords"]) + assert { + "mvp", + "mcp", + "model-context-protocol", + "cursor", + "opencode", + "graph-ops", + "prd-grill", + "verifier-plane", + }.issubset(project["keywords"]) def test_python_wheel_data_is_explicit_and_does_not_depend_on_package_discovery(): @@ -66,6 +75,9 @@ def test_public_ctas_are_outcome_led_and_preserve_proof_boundaries(): assert readme.index(value) < readme.index("## What Code Factory is") assert "factory mvp \"Build an approval tracker\" --root ." in readme assert "Watch the exact shipped UI in 60 seconds" in readme + assert "live Hugging Face Space" in readme + assert "Cursor or OpenCode MCP" in readme + assert "deterministic proof" in readme assert "star Code Factory" in readme assert "production-ready before the relevant proof exists" in readme assert "reviewable MVP starting state in minutes" in vscode_package["description"] diff --git a/tests/test_release_integrity.py b/tests/test_release_integrity.py index dd68008..eb4ffdf 100644 --- a/tests/test_release_integrity.py +++ b/tests/test_release_integrity.py @@ -128,7 +128,7 @@ def test_release_integrity_rejects_huggingface_metadata_that_would_fail_remotely readme = root / "deploy" / "huggingface" / "README.md" readme.write_text( readme.read_text(encoding="utf-8").replace( - "short_description: Reviewable MVPs with verifier, repair, and workspace proof", + "short_description: Proof-backed AI coding workflows with local MCP context", f"short_description: {'x' * 61}", ), encoding="utf-8", From c3d8038c350daccb586a6ff5715a8cb4988aad48 Mon Sep 17 00:00:00 2001 From: zrk222 Date: Sun, 9 Aug 2026 00:41:59 -0400 Subject: [PATCH 2/7] Add public proof playground magnets --- deploy/huggingface/README.md | 7 + deploy/huggingface/index.html | 214 +++++++++++++++++++++++++++++- tests/test_huggingface_surface.py | 12 ++ 3 files changed, 231 insertions(+), 2 deletions(-) diff --git a/deploy/huggingface/README.md b/deploy/huggingface/README.md index a95349a..4c31acf 100644 --- a/deploy/huggingface/README.md +++ b/deploy/huggingface/README.md @@ -42,6 +42,13 @@ Use the same local proof context from Cursor or OpenCode through the documented The client connection is local and read-only; it does not upload source or grant provider, credential, deployment, or publishing authority. +Try the public **Proof Playground** before installing: enter an outcome and +watch a deterministic browser-only preview assemble intent, checks, and a +local proof reference. It is deliberately not a production mission, does not +call a model, and never sends the text away. The same page includes copyable +recipes for repository readiness, contained MVPs, Graph Ops, independent +verification, Cursor, and OpenCode. + Before a PRD becomes a scaffold, run `factory prd grill PRD.md --root .` for a capped, source-bound clarification sheet with recommendations and answer stubs. It never rewrites the PRD, invents answers, calls a model, or authorizes a diff --git a/deploy/huggingface/index.html b/deploy/huggingface/index.html index e6e0abc..59b0aab 100644 --- a/deploy/huggingface/index.html +++ b/deploy/huggingface/index.html @@ -67,15 +67,63 @@ pre { overflow-x: auto; margin: 0; padding: 24px; border: 1px solid rgba(255,255,255,.14); border-radius: 18px; background: #0d0d0b; color: #ffd47c; font: 600 .95rem/1.7 ui-monospace, SFMono-Regular, Consolas, monospace; } .gallery { display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; } .gallery img { display: block; width: 100%; border-radius: 18px; border: 1px solid var(--line); background: var(--cream); } + .playground-section { padding-top: 3vw; } + .playground { display: grid; grid-template-columns: .82fr 1.18fr; gap: 20px; padding: clamp(20px, 4vw, 34px); border: 1px solid var(--line); border-radius: var(--radius); background: linear-gradient(135deg, rgba(255,255,255,.88), rgba(255,241,207,.9)); box-shadow: var(--shadow); } + .playground-input { padding: 18px 10px 18px 6px; } + .playground-input h3 { margin: 10px 0 8px; font-size: clamp(1.6rem, 3vw, 2.4rem); letter-spacing: -.045em; line-height: 1.5; } + .bake-action { background: var(--amber); color: var(--ink); border-color: var(--amber); } + .bake-action:hover { background: #ffc65d; } + .playground-input p { color: var(--muted); } + .field-label { display: block; margin: 24px 0 8px; font-size: .9rem; font-weight: 850; letter-spacing: .08em; text-transform: uppercase; } + textarea { display: block; width: 100%; min-height: 116px; resize: vertical; padding: 15px 16px; border: 1px solid var(--line); border-radius: 16px; color: var(--ink); background: rgba(255,255,255,.82); font: inherit; line-height: 1.5; } + textarea:focus { outline: 3px solid rgba(7,95,216,.22); border-color: var(--focus); } + .preset-row { display: flex; flex-wrap: wrap; gap: 8px; margin: 12px 0 20px; } + .preset { min-height: 40px; padding: .55rem .78rem; border: 1px solid var(--line); border-radius: 999px; background: rgba(255,255,255,.68); color: var(--muted); font: 750 .85rem/1.2 inherit; cursor: pointer; } + .preset:hover, .preset:focus-visible { border-color: var(--amber-dark); color: var(--ink); background: white; } + .fine-print { margin: 12px 0 0; color: var(--muted); font-size: .86rem; line-height: 1.5; } + .receipt-panel { min-height: 390px; padding: 24px; border: 1px solid rgba(255,255,255,.18); border-radius: 22px; background: var(--ink); color: white; position: relative; overflow: hidden; } + .receipt-panel::after { content: ""; position: absolute; inset: auto -20% -60% 20%; height: 70%; background: radial-gradient(circle, rgba(244,169,40,.22), transparent 64%); pointer-events: none; } + .receipt-empty { display: grid; min-height: 340px; place-items: center; text-align: center; color: #d9d3c7; position: relative; z-index: 1; } + .receipt-empty .oven { display: grid; place-items: center; width: 78px; height: 78px; margin: 0 auto 16px; border: 1px solid rgba(255,255,255,.25); border-radius: 24px; background: #2a2820; color: var(--amber); font-size: 2.2rem; } + .receipt-result { position: relative; z-index: 1; } + .receipt-top { display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; padding-bottom: 18px; border-bottom: 1px solid rgba(255,255,255,.15); } + .receipt-top h3 { margin: 0; font-size: 1.45rem; letter-spacing: -.03em; } + .receipt-top p { margin: 4px 0 0; color: #cfc7b7; font-size: .9rem; } + .status-badge { display: inline-flex; align-items: center; gap: 6px; padding: 6px 9px; border-radius: 999px; background: rgba(99,208,132,.16); color: #a9efb8; font-size: .78rem; font-weight: 850; white-space: nowrap; } + .receipt-stages { display: grid; gap: 10px; margin: 20px 0; } + .receipt-stage { display: grid; grid-template-columns: 28px 1fr auto; gap: 10px; align-items: center; padding: 10px 12px; border: 1px solid rgba(255,255,255,.11); border-radius: 12px; color: #bdb5a7; transition: background-color .25s ease, color .25s ease, transform .25s ease; } + .receipt-stage.complete { background: rgba(99,208,132,.1); color: white; transform: translateX(3px); } + .stage-dot { display: grid; place-items: center; width: 24px; height: 24px; border-radius: 50%; background: #3b382e; color: #cfc7b7; font-size: .74rem; font-weight: 900; } + .complete .stage-dot { background: #398354; color: white; } + .stage-name { font-weight: 800; } + .stage-detail { color: #aaa294; font-size: .82rem; } + .complete .stage-detail { color: #a9efb8; } + .receipt-foot { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 12px; margin-top: 18px; color: #bdb5a7; font-size: .82rem; } + .copy-button { min-height: 42px; padding: .62rem .84rem; border: 1px solid rgba(255,255,255,.2); border-radius: 11px; background: #2a2820; color: white; font: 800 .85rem/1.2 inherit; cursor: pointer; } + .copy-button:hover, .copy-button:focus-visible { border-color: var(--amber); color: #ffd47c; } + .recipe-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 14px; } + .recipe-card { display: flex; flex-direction: column; gap: 12px; min-height: 250px; padding: 22px; border: 1px solid var(--line); border-radius: 20px; background: rgba(255,255,255,.68); } + .recipe-card h3 { margin: 0; font-size: 1.2rem; letter-spacing: -.02em; } + .recipe-card p { margin: 0; color: var(--muted); font-size: .94rem; line-height: 1.5; } + .recipe-card code { display: block; margin-top: auto; padding: 10px; border-radius: 10px; background: #f2e8d1; color: var(--amber-dark); font: 700 .78rem/1.4 ui-monospace, SFMono-Regular, Consolas, monospace; overflow-wrap: anywhere; } + .recipe-card .copy-button { align-self: flex-start; border-color: var(--line); background: white; color: var(--ink); } + .recipe-card .copy-button:hover, .recipe-card .copy-button:focus-visible { border-color: var(--amber-dark); color: var(--amber-dark); } + .mcp-strip { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; align-items: stretch; } + .mcp-strip .proof { padding: 30px; } + .mcp-note { display: flex; align-items: center; gap: 10px; margin-top: 14px; color: var(--green); font-size: .9rem; font-weight: 750; } + .toast { position: fixed; right: 20px; bottom: 20px; z-index: 30; padding: 12px 16px; border-radius: 12px; background: var(--ink); color: white; box-shadow: var(--shadow); font-weight: 750; opacity: 0; transform: translateY(10px); pointer-events: none; transition: opacity .2s ease, transform .2s ease; } + .toast.visible { opacity: 1; transform: translateY(0); } + @keyframes oven-pulse { 0%, 100% { box-shadow: 0 0 0 0 rgba(244,169,40,.12); } 50% { box-shadow: 0 0 0 12px rgba(244,169,40,0); } } + .is-baking .oven { animation: oven-pulse 1.3s ease-in-out infinite; } .boundary { margin-top: 18px; color: var(--muted); font-size: .95rem; text-align: center; } .final { text-align: center; padding-bottom: 120px; } .final h2 { max-width: 16ch; margin: 0 auto 28px; } footer { display: flex; justify-content: space-between; gap: 20px; padding: 28px 0 42px; border-top: 1px solid var(--line); color: var(--muted); font-size: .95rem; } @media (max-width: 50rem) { nav a:not(.button) { display: none; } - .hero, .section-head, .proof { grid-template-columns: 1fr; } + .hero, .section-head, .proof, .playground, .mcp-strip { grid-template-columns: 1fr; } .hero { padding-top: 48px; } - .grid, .gallery { grid-template-columns: 1fr; } + .grid, .gallery, .recipe-grid { grid-template-columns: 1fr; } h1 { font-size: clamp(3.2rem, 17vw, 5.4rem); } section { padding: 68px 0; } footer { flex-direction: column; } @@ -84,6 +132,9 @@ html { scroll-behavior: auto; } .button { transition: none; } .button:hover { transform: none; } + .receipt-stage { transition: none; } + .is-baking .oven { animation: none; } + .toast { transition: none; } } @@ -93,6 +144,8 @@
CF Code Factory