# Project export: Foldweave This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: OpenAI Build Week - Tagline: Change the structure. Keep the connections. - Devpost: https://devpost.com/software/preflight-8s9awt - GitHub: https://github.com/ModernBlueprints/Foldweave - Video: https://www.youtube.com/embed/JpHIoLa-hZI?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 1 GitHub contributor(s) — ModernBlueprints (75 commits) ## Devpost submission (written by the team) ### Inspiration A shared project folder rarely stays shared in the literal sense. Sofia may keep the final report under approved/, while Martin keeps the same report under ready/. Their notes may link to the same images and documents through different relative paths. Both copies can contain the same underlying project while looking completely different on disk. That creates a practical problem. A good reorganization is hard to repeat safely. Asking an AI model to reorganize both copies independently can produce two different answers. Sending a replacement folder transfers project files. Sending a list of paths only works when everyone already has the same layout. A batch rename can also omit files, collide paths, or break the links that make the folder useful. I built Foldweave to separate the creative decision from the mechanical proof. ### What it does Foldweave lets a person describe a connected-folder reorganization in plain English, review the complete proposed structure before execution, refine it, and create a separate verified copy only after accepting the exact proposal. The result can include a Foldweave Change File. It contains no project payload bytes. Instead, it carries a verified structural transformation plus the hashes, sizes, supported link relationships, lineage, and proof identifiers needed to recognize a strictly equivalent project. That is the central idea: the same project does not need to start with the same paths. Sofia can create and verify a new structure. Martin can combine Sofia's Change File with his differently arranged equivalent copy. Foldweave matches the underlying members deterministically, shows Martin his own current folder against Sofia's shared proposal, and lets him either: accept the shared proposal without any model call; or use GPT-5.6, ChatGPT, or Codex to build a complete next proposal from it. If Martin creates a derivative change, Foldweave produces a new self-contained Change File. Sofia can then apply that change to her equivalent copy. The participants exchange a verified structural pattern, not the project payload. How it works 1. Plan The user chooses a folder and describes the desired result. Foldweave supports four honest execution modes: Direct API: exact gpt-5.6 through the OpenAI Responses API with a user-supplied key. ChatGPT-hosted: the user's normal ChatGPT session supplies model inference through the Foldweave app and paired local companion. Foldweave makes no hidden direct API call. Recorded replay: a keyless, clearly labelled replay of a real GPT planning run. Unchanged Change File application: deterministic and model-free. Codex is also supported through the same bounded MCP tools and deterministic engine. 2. Compile The model may propose a complete plan or a strict revision. It cannot move files, approve its own proposal, bypass checks, create a receipt, or declare a result verified. One Python engine performs the authoritative work: scan and hash every in-scope member; account for every file exactly once; preserve protected members; validate every destination; detect collisions and stale input; derive supported relative Markdown link rewrites; build one immutable review preview; bind acceptance to the exact preview fingerprint; create a separate copy; verify the result independently; and retain transaction-specific reconstruction authority. Nothing is created while the job is merely under review. 3. Review and revise The native macOS application, browser fallback, ChatGPT widget, Codex integration, and CLI all use the same preview contract. The review shows: the current and proposed trees; every moved or renamed member; protected files and empty directories; supported link effects; complete file and change counts; why a path was proposed; whether output exists; and the exact proposal revision being accepted. A user may request a bounded revision. A failed revision leaves the previous valid proposal intact. Stale tabs, duplicate acceptance, changed sources, changed destinations, and concurrent revise-versus-accept races fail closed. 4. Carry the change to a different layout For ordinary files, Foldweave matches exact size, SHA-256, suffix, and protection status. For supported Markdown files, it commits to all bytes outside relative link destinations and refines the match using ordered incoming and outgoing link relationships. Protected members require exact path and bytes. The matcher never guesses from the origin path, receiver path, directory order, or filename similarity. Extra, missing, changed, or irreducibly ambiguous members block. This is why Martin can begin with a different local organization and still receive the exact reviewed structure. 5. Prove and reconstruct Each accepted transaction produces a receiver-specific result and receipt. The verifier checks source-free proof and can also compare against the selected source. The organized-tree commitment includes files, directories, and supported rewritten links. Reconstruction means: recreate the exact source selected when this transaction began. Martin reconstructs Martin's source, not Sofia's earlier layout. Why the Change File matters The Foldweave Change File is deliberately payload-free, but it is not metadata-free. It discloses project names and structure, sizes, hashes, supported link relationships, the original instruction, target names, lineage, and proof identifiers. This contract makes several useful workflows possible: a consultant can send a reviewed handoff structure without redistributing client payloads; a research group can apply one verified organization to equivalent local copies; a collaborator can inspect a shared proposal against their own layout before accepting it; a team can iterate serially through self-contained Change Files; an archivist can prove that every admitted member survived the transformation; and any participant can recreate the source used for their own transaction. Foldweave does not claim semantic correctness, support for independently edited copies, arbitrary file-format understanding, arbitrary reference rewriting, sender authentication, or universal reversibility. This release supports connected local project folders and relative Markdown links. How I built it with Codex I began with a constrained project-selection tournament. Candidate ideas were challenged against user value, Build Week fit, feasibility, differentiation, and whether a complete trustworthy transaction could be demonstrated. That process led to Foldweave's authority split: the model proposes, deterministic code compiles and proves, and the person decides. Codex was my primary implementation and integration environment. I used it to develop and continuously integrate: the deterministic folder engine and matcher; versioned jobs, immutable previews, exact acceptance, and restart recovery; sparse plan revisions and parent-child lineage; Change Files, receipts, verification, and reconstruction; the native macOS shell and secure Keychain boundary; the focused React review tree and ChatGPT widget; the shared local and public MCP services; the Codex plugin; the Cloudflare gateway and paired outbound companion; packaging, clean-clone reproduction, browser and native visual QA; and adversarial regression and refusal coverage. Codex also helped force early end-to-end transactions instead of allowing isolated subsystems to remain unintegrated. How GPT-5.6 is used In direct mode, Foldweave calls the exact gpt-5.6 alias through the Responses API with strict tool and response schemas, bounded eligible evidence, store=false, no fallback model, and no provider retry. GPT-5.6 contributes the part that benefits from language understanding: turning a plain-English request and bounded folder evidence into one complete structural proposal, or turning a focused user instruction into one strict revision. Everything after model output is deterministic. Fixed code validates the proposal, derives link rewrites, renders the review, executes only the accepted fingerprint, verifies the result, and constructs proof. In ChatGPT-hosted and Codex-hosted modes, the host supplies inference through the same bounded planning tools. ChatGPT subscription access and API billing remain separate. Recorded replay and unchanged Change File application use no model. What I am proud of The Sofia → Martin → Sofia demonstration proves more than a folder rename: two source layouts represent one strictly equivalent connected project; Sofia reviews and revises a GPT-5.6 proposal; Martin sees his own original tree beside the shared proposal; Martin can accept unchanged with no GPT call; Martin can build a derivative proposal through a live host; the child Change File is complete and does not require its parent; Sofia can apply Martin's derivative change; every accepted result converges to one organized-tree commitment; each participant reconstructs the source selected for that transaction; and no source folder is modified in place. Try it Repository: https://github.com/ModernBlueprints/Foldweave The README begins with a keyless replay that requires no API key, ChatGPT login, Cloudflare account, or native-app rebuild. It also documents the unsigned/ad-hoc macOS Apple-Silicon judge build, browser and CLI paths, direct GPT-5.6 mode, ChatGPT integration, and the Foldweave Codex plugin. The native release is tested on macOS Apple Silicon. The ChatGPT integration is technically ready for review, but I do not claim that it is approved, publicly listed, or generally available. ## README (from the GitHub repository) No README available. ## Detected evidence (automated analysis) Indexed codebase: 304 recognized source files, 8050 KB. - CSS (language) — detected in the code - FastAPI (technology) — detected in the code - HTML (language) — detected in the code - JavaScript (language) — detected in the code - OpenAI (technology) — detected in the code - Python (language) — detected in the code - React (technology) — detected in the code - TypeScript (language) — detected in the code ## Codebase structure (from repository index) ### Files (120 of 347) ``` .agents/plugins/marketplace.json .gitattributes .gitignore .python-version docs/CODEX_BUILD_LOG.md docs/LIMITATIONS.md docs/PREEXISTING_WORK.md docs/SUBMISSION_PACKAGE.md gateway/.gitignore gateway/package.json gateway/README.md gateway/src/canonical.ts gateway/src/constants.ts gateway/src/contracts.ts gateway/src/device-crypto.ts gateway/src/device-session.ts gateway/src/env.ts gateway/src/gateway.ts gateway/src/generated/foldweave-public-mcp-output-contract.v1.json gateway/src/http.ts gateway/src/index.ts gateway/src/oauth-return.ts gateway/src/pairing-code.ts gateway/src/pairing-directory.ts gateway/src/public-discovery.ts gateway/src/public-invocation.ts gateway/src/response-codec.ts gateway/test/canonical.test.ts gateway/test/env.d.ts gateway/test/oauth-return.test.ts gateway/test/protocol.test.ts gateway/test/raw.d.ts gateway/test/response-codec.test.ts gateway/test/worker.test.ts gateway/tsconfig.json gateway/vitest.config.ts gateway/wrangler.jsonc LICENSE packaging/assets/Foldweave.icns packaging/foldweave_entry.py packaging/Foldweave.spec packaging/pyinstaller_hooks/hook-bagit.py plugins/foldweave/.codex-plugin/plugin.json plugins/foldweave/.mcp.json plugins/foldweave/README.md pyproject.toml README.md sample_data/connected_change/ambiguity/notes/client-approval.md sample_data/connected_change/ambiguity/notes/internal-review.md sample_data/connected_change/martin_apollo/.env.example sample_data/connected_change/martin_apollo/conversations/approval.md sample_data/connected_change/martin_apollo/conversations/kickoff.md sample_data/connected_change/martin_apollo/desk/project-overview.md sample_data/connected_change/martin_apollo/drafts/numbers/budget.csv sample_data/connected_change/martin_apollo/evidence/audience.txt sample_data/connected_change/martin_apollo/evidence/interviews.txt sample_data/connected_change/martin_apollo/evidence/sources.csv sample_data/connected_change/martin_apollo/intake/client/brief.md sample_data/connected_change/martin_apollo/library/terms.txt sample_data/connected_change/martin_apollo/ready/budget.csv sample_data/connected_change/martin_apollo/sendoff/delivery.md sample_data/connected_change/README.md sample_data/connected_change/sofia_apollo/.env.example sample_data/connected_change/sofia_apollo/approved/Apollo-budget.csv sample_data/connected_change/sofia_apollo/briefing/Apollo-client-brief.md sample_data/connected_change/sofia_apollo/handoff/Apollo-delivery-notes.md sample_data/connected_change/sofia_apollo/notes/Apollo-project-notes.md sample_data/connected_change/sofia_apollo/notes/meetings/Apollo-approval-notes.md sample_data/connected_change/sofia_apollo/notes/meetings/Apollo-kickoff-notes.md sample_data/connected_change/sofia_apollo/references/Apollo-terms.txt sample_data/connected_change/sofia_apollo/research/Apollo-audience-research.txt sample_data/connected_change/sofia_apollo/research/Apollo-interview-summary.txt sample_data/connected_change/sofia_apollo/research/Apollo-source-log.csv sample_data/connected_change/sofia_apollo/working/data/Apollo-budget-working.csv sample_data/folder_a1/.env.example sample_data/folder_a1/assets/budget.csv sample_data/folder_a1/brief.md sample_data/folder_a1/notes/project-notes.txt sample_data/hero/metadata/metadata.csv sample_data/hero/normalization.csv sample_data/negative_unresolved_meaning/metadata/metadata.csv sample_data/README.md src/name_atlas/__init__.py src/name_atlas/app.py src/name_atlas/artifacts.py src/name_atlas/assets/chatgpt-widget/foldweave-chatgpt-widget.css src/name_atlas/assets/chatgpt-widget/foldweave-chatgpt-widget.js src/name_atlas/cases.py src/name_atlas/cli.py src/name_atlas/config.py src/name_atlas/connected_browser_cli.py src/name_atlas/connected_cli.py src/name_atlas/connected_planner_runtime.py src/name_atlas/connected_web_service.py src/name_atlas/decision_cards/__init__.py src/name_atlas/decision_cards/budget.py src/name_atlas/decision_cards/errors.py src/name_atlas/decision_cards/evidence.py src/name_atlas/decision_cards/models.py src/name_atlas/decision_cards/providers.py src/name_atlas/decision_cards/service.py src/name_atlas/decisions.py src/name_atlas/domain/__init__.py src/name_atlas/domain/contracts.py src/name_atlas/folder_app.py src/name_atlas/folder_job_service.py src/name_atlas/folder_refactor/__init__.py src/name_atlas/folder_refactor/compiler.py src/name_atlas/folder_refactor/connected_change/__init__.py src/name_atlas/folder_refactor/connected_change/accepted_plan.py src/name_atlas/folder_refactor/connected_change/contracts.py src/name_atlas/folder_refactor/connected_change/derivative.py src/name_atlas/folder_refactor/connected_change/descriptors.py src/name_atlas/folder_refactor/connected_change/evidence.py src/name_atlas/folder_refactor/connected_change/job_io.py src/name_atlas/folder_refactor/connected_change/job_service.py src/name_atlas/folder_refactor/connected_change/job_v2.py src/name_atlas/folder_refactor/connected_change/job_v3.py src/name_atlas/folder_refactor/connected_change/matcher.py src/name_atlas/folder_refactor/connected_change/organized_tree.py [227 more files omitted for size] ``` ### Dependencies - gateway/package.json: @cloudflare/vitest-pool-workers@0.18.6, @cloudflare/workers-oauth-provider@0.8.2, @cloudflare/workers-types@5.20260719.1, typescript@5.9.3, vitest@4.1.10, wrangler@4.112.0 - pyproject.toml: bagit@>=1.8,<2, cryptography@>=49,<50, fastapi@>=0.116,<1, httpx@>=0.28,<1, jinja2@>=3.1,<4, mcp@>=1.27,<2, openai@>=1.0,<3, pydantic@>=2.12,<3, pyobjc-core@>=12.2.1,<13, pyobjc-framework-cocoa@>=12.2.1,<13, pyobjc-framework-quartz@>=12.2.1,<13, pyobjc-framework-security@>=12.2.1,<13, pyobjc-framework-webkit@>=12.2.1,<13, pywebview@>=6.2.1,<7, uvicorn@>=0.35,<1, websockets@>=15,<16 - web/package.json: @blueprintjs/core@6.17.2, @blueprintjs/icons@6.13.0, @testing-library/dom@10.4.1, @testing-library/jest-dom@6.9.1, @testing-library/react@16.3.2, @testing-library/user-event@14.6.1, @types/node@22.20.1, @types/react@18.3.31, @types/react-dom@18.3.7, @vitejs/plugin-react@6.0.3, jsdom@29.1.1, react@18.3.1, react-dom@18.3.1, typescript@7.0.2, vite@8.1.5, vitest@4.1.10 ### Recent commits (newest first) - docs: record final Devpost readiness pass - fix: publish final constant-speed Foldweave demo - fix: finalize Foldweave replacement demo - docs: explain Foldweave cross-layout change engine - chore: rename public repository to Foldweave - docs: publish Foldweave Build Week demo - docs: record final Foldweave release verification - fix: remove hosted widget pointer focus outline - fix: polish Foldweave native UI and runtime - docs: reconcile public Foldweave judge path - docs: record Foldweave recording readiness - docs: finalize Foldweave judge documentation - docs: record Foldweave recording preflight - fix: normalize Foldweave review screenshot format - docs: record Foldweave public promotion - docs: reconcile Foldweave release evidence - docs: record Foldweave branch publication - docs: record Foldweave clean-clone acceptance - feat: qualify Foldweave release candidate - feat: deliver Foldweave native review and shared planning ## Key source files (fetched from GitHub, selected and truncated for size) Source contents could not be fetched from GitHub right now. [278 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]