forgo.cloud
Sign in
Repo workspace

forkjoin-ai/gnosis

GG Surface Map

docs/GG_SURFACE_MAP.md
forkjoin-ai/gnosis
Repo overview Open in workbench

GG Surface Map

Parent README: ../README.md

This map identifies the GG-facing surfaces a developer may need to use or extend. It is grouped by behavior rather than by every file.

Primary Developer Surfaces

Surface Classification What it owns
../docs/GETTING_STARTED.md primary First-run orientation and basic mental model.
GG_DEVELOPER_GUIDE.md primary Canonical GG developer entrypoint.
GG_LANGUAGE_REFERENCE.md primary Practical .gg, .test.gg, .mgg, and .gnarly language reference.
GG_CLI_REFERENCE.md primary Command map for gnosis, gnode, monster, and validation targets.
GG_MODULES_AND_EXTENSIONS.md primary Modules, public exports, extension points, and cross-site integrations.

Authoring And Examples

Surface Classification What it owns
../example.gg primary Small direct GG example.
../betti.gg primary Compact topology reused throughout docs and benchmarks.
../examples/README.md primary Example tree, .test.gg suites, benchmarks, crypto, proofs, transformer examples.
../topologies/ advanced Larger topology corpus, including app, domain, music, void, and generated families.
../binder.gg and nested binder.gg files advanced Local binder/topology metadata for subtrees.

CLI And Execution

Surface Classification What it owns
../bin/README.md primary Script entrypoints such as gnosis.js, gnode.js, and host helpers.
../gnode/README.md primary TypeScript-first bridge into GG, schedule extraction, and execution.
../polyglot/README.md primary Rust extractor/lowering layer and Monster execution path.
../runtime/README.md advanced Rust/WASM runtime crate.
../gnode/benchmarks/README.md advanced Runtime shootouts and performance evidence.

Compiler, Module, And Runtime Source

Surface Classification What it owns
../src/README.md primary TypeScript source map and public subpath ownership.
../src/betty/README.md primary Betty compiler, parser, optimization, proof artifact generation.
../src/betti/README.md advanced Betti-adjacent trace and runtime support.
../src/mod/README.md primary .gg / .mgg loader, resolver, exports, effects, merged source.
../src/runtime/README.md primary TypeScript runtime registry, built-ins, admission, and execution semantics.
../src/capabilities/README.md primary Effect/capability target profiles.
../src/testing/README.md primary GG test adapters and test-runner surface.
../src/universe/README.md primary Executable universe kernel and fail-closed admission contract.

Polyglot And Existing-Code Extraction

Surface Classification What it owns
../polyglot/src/README.md primary Rust extractor/compiler crate internals.
../polyglot/src/extractors/README.md primary Language extraction ownership.
../polyglot/src/framework_recognizers/README.md primary Framework recognition.
../polyglot/gg-walker-wasm/README.md advanced Tier-C interpreter-embed walker.
../polyglot/docs/BETTI_WASM_GUIDE.md advanced Write, compile, and run certified WASM programs.
../polyglot/docs/BETTI_WASM_REFERENCE.md advanced Betti WASM class grammars, ABI, manifest, envelopes, and BSNP specs.

Formal And Proof Surfaces

Surface Classification What it owns
../FORMAL_LEDGER.md primary Human-facing formal index and consumer contracts.
../THEOREM_LEDGER.md primary Machine-oriented theorem ledger.
../lean/README.md advanced Lean theorem surface.
../tla/ advanced TLA+ generated and hand-authored formal surface.
../PROOF_ARTIFACT_PATHS.md advanced Generated proof artifact path audit.
../FALLBACK_PROOF_ARTIFACTS.md advanced Generated fallback proof triage.

Ebooks And Long-Form References

Book Classification What it covers
Book 153 cross-reference Topological programming language concepts.
Book 188 cross-reference Module system tutorial.
Book 189 cross-reference GG test framework tutorial.
Book 194 cross-reference Formatter and REPL developer experience.
Book 195 cross-reference CLI walkthrough.
Book 200 cross-reference Polyglot gnode and cross-language execution.
Surface Classification What it owns
../aeon.toml primary Source for the public Gnosis site.
https://gnosis.forgo.cloud/ primary Public Gnosis project site.
apps/oss-sites-worker cross-site Site fleet index and OSS site hosting.
open-source/x-gnosis cross-site Native/web serving of compiled Gnosis surfaces.
apps/polyglot-scanner cross-site Scanner-facing polyglot workflows.
apps/gnosis-engine-mcp cross-site MCP-facing engine integration.
apps/gnot-demo-site cross-site Gnot and structural serialization demos.
apps/knot-viz cross-site Visualizer support.

Extension Ownership

Extension type Start here Notes
Language syntax or compiler labels ../src/betty/README.md Add parser/compiler docs and examples.
Runtime handlers ../src/runtime/README.md Preserve admission, capability, and execution-auth boundaries.
Modules and dependency resolution ../src/mod/README.md Keep .mgg, gnosis.mod, lockfile, and resolver behavior aligned.
Existing language extraction ../polyglot/src/README.md Add diagnostics for partial extraction.
TypeScript/editor diagnostics ../src/README.md Use ts-check, SARIF, CLI lint/analyze, and watcher surfaces.
Formal/proof claims ../FORMAL_LEDGER.md Link theorem IDs and generated artifact paths explicitly.

Inventory Notes

The current checkout contains thousands of GG-family files across examples, topologies, tests, binders, and generated/supporting surfaces. Treat this map as the navigation anchor; use rg --files open-source/gnosis -g '*.gg' -g '*.mgg' -g 'gnosis.mod' when you need the exact live inventory.