diff --git a/README.md b/README.md index b72a132..11a5c27 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,21 @@ Clone `GameCult-Quartz` beside this repository, install its dependencies, then r The generated site is written to `quartz-site/public`. +## Architecture documentation + +The Ghostlight repository owns technical truth under +`docs/public-architecture`. This site commits an exact publication projection +under `content/Documentation` so GitHub Pages can build independently. + +Refresh and verify it with: + +```powershell +.\scripts\sync-architecture-docs.ps1 +.\scripts\sync-architecture-docs.ps1 -Check +``` + +Do not hand-edit the projected pages. Change the Ghostlight source, then sync. + ## Deployment Pushes to `main` invoke GameCult Quartz's reusable GitHub Pages workflow. GitHub Pages owns the custom domain setting for `ghostlight.gamecult.org`; a repository `CNAME` file is not authoritative for this Actions-based deployment. diff --git a/content/Documentation/Agents and model stages.md b/content/Documentation/Agents and model stages.md new file mode 100644 index 0000000..3540cd1 --- /dev/null +++ b/content/Documentation/Agents and model stages.md @@ -0,0 +1,121 @@ +--- +title: Agents and model stages +description: A catalog of Ghostlight's production model calls, their roles, outputs, and deterministic gates. +--- + +Ghostlight uses three logical model tiers. **Fast** handles bounded projection, +classification, and selection; **Balanced** handles reconciliation, causal +reasoning, and most agentic workbenches; **Capable** handles the hardest world +compilation and numinous elaboration. Deployments may map these aliases to +different physical models without changing stage contracts. + +“Agentic” means the stage can inspect a bounded workbench, take several typed +actions, receive deterministic feedback, and revise on the same snapshot. A +one-shot model stage still produces only a proposal. + +## Session Zero + +| Stage | Tier | Purpose | Output and downstream gate | +|---|---|---|---| +| `session_zero_projector` | Fast/configured | Lowers permitted negotiation state into the DM's private lived context | Projected stream; schema validation only, no state write | +| `session_zero_dm_persona` | Balanced/configured | Embodied persistent DM who discusses premise, boundaries, roles, and bargains | Natural speech; owns no accepted changes | +| `session_zero_interpreter` | Balanced/configured | Extracts only new typed proposals or one focused counterproposal from DM/player speech | Contract, character, or permission proposal; exact owner acceptance and Session Zero kernel gate | + +## Retrieval and world compilation + +| Stage | Tier | Purpose | Output and downstream gate | +|---|---|---|---| +| `opening_retrieval_plan` | Fast | Plans source queries for possible openings | Queries; Vault boundary executes and receipts results | +| `world_openings` | Balanced | Suggests grounded starting situations | Suggestions with evidence IDs; deterministic evidence validation | +| `role_retrieval_plan` | Fast | Plans source queries for playable roles | Queries; Vault boundary | +| `world_roles` | Balanced | Suggests roles, capabilities, and obligations | Suggestions; evidence and duplication checks | +| `custom_retrieval_plan` | Fast | Plans queries for a custom campaign brief | Queries only | +| `evidence_relevance` | Fast | Separates direct seed evidence from background and excluded material | Classification; deterministic source-lane admission | +| `world_compile` | Capable | Compiles the bounded playable seed: topology, cast, populations, institutions, facts, clocks, and civic state | Candidate seed; full structural and semantic validation before registry publication | +| `private_relationship_actor_compile` | Balanced | Compiles private player-character state and approved relationship anchors | Private actor proposal; identity, account, and relationship binding checks | +| `agency_compile` | Balanced | Profiles local actors, institutions, and populations across the six agency axes | Agency profiles and relations; exact subject coverage validation | +| `global_agency_compile` | Fast/configured | Builds the coarse offscreen strategic skeleton | Major powers, regions, channels, and pressures; schema and evidence checks | +| `global_agency_doctrine_synthesis` | Balanced | Proposes strategic doctrines from exact global agency anchors | Doctrine candidates; cannot rewrite source anchors | +| `global_agency_doctrine_verification` | Balanced | Judges whether synthesized doctrines preserve their anchors | Verdict; deterministic compiler decides admission | + +## Destination, civic, and clock workbenches + +| Stage | Tier | Purpose | Output and downstream gate | +|---|---|---|---| +| `destination_identity_resolution` | Fast | Decides whether a requested destination is an existing reachable place or a genuinely new region | Identity proposal; deterministic topology check chooses elaboration versus expansion | +| `destination_retrieval_plan` | Fast | Plans exact source queries for a destination | Queries only | +| `destination_compile` | Capable | Proposes geography, routes, residents, institutions, political relations, and civic apparatus | Expansion/elaboration candidate; topology, evidence, knowledge, and civic closure checks | +| `destination_reconciliation_agent_action` | Balanced, agentic | Repairs an exact rejected destination finding through small transactional edits | Revised private candidate; reruns the existing validators, never writes world state | +| `destination_civic_verification` | Balanced | Independently judges whether authority, succession, resources, redress, and resident knowledge are legible | Verdict receipt; kernel rebinds and checks it at admission | +| `gestalt_fission_retrieval_plan` | Fast | Plans evidence retrieval for a requested population subdivision | Queries; fission compiler and approval gate | +| `clock_consequence_binding_agent_action` | Balanced, agentic | Binds legacy clock consequence text to exact observable subjects and public channels | Binding proposal; deterministic threshold/event validation and kernel commit | + +## Titled world elaborators + +All titled workers use `world_elaboration_`, the common +agent harness, one exact frozen assignment, and at most one additive operation. +The weighted scheduler controls invocation frequency in proportion to the +user's slider shares. + +| Agent | Tier | Character of contribution | +|---|---|---| +| **Patina** | Fast | Durable low-stakes texture: objects, nicknames, customs, jokes, and reusable places | +| **Charter** | Balanced | Government, offices, law, succession, selection, procedure, and redress | +| **Ledger** | Fast | Labor, resources, infrastructure, exchange, scarcity, and class pressure | +| **Hearth** | Fast | Kinship, care, neighborhood, obligation, belonging, and private stakes | +| **Tangle** | Balanced | Factions, alliances, rivalries, constituencies, leverage, and plots | +| **Veil** | Fast | Secrets, rumors, misinformation, taboo, mystery, and disclosure paths | +| **Ember** | Fast | Active disputes, hazards, instability, escalation, and urgent pressure | +| **Numen** | Capable | Religion, ritual, magic, cosmology, awe, and bounded strangeness | + +The deterministic elaboration tool checks the operation against the title's +exact assignment and frozen namespace. Wave admission resolves conflicts; an +independent semantic verifier reviews the inhabited candidate; `WorldKernel` +alone commits it. + +## Foreground perception, response, and action + +| Stage | Tier | Purpose | Output and downstream gate | +|---|---|---|---| +| `speech_address_resolver` | Fast | Selects exact co-present direct addressees for player speech | Addressee IDs; presence and response-duty validation | +| `projector` | Fast/configured | Projects one actor's permitted typed state and visible event into lived narrative | Private context; never canonical truth | +| `persona` | Balanced/configured | Appraises the event and produces natural response from one actor's perspective | Speech, deliberate silence, private appraisal, or action intent | +| `interpreter` | Capable/configured, agentic | Negotiates natural intent into the closed action algebra | Typed action proposal; authority and semantic validation | +| `assessment_mutation_scope` | Fast/Balanced | Selects the smallest mutation lanes that could realize an attempted effect | Upper-bound scope or precise denial; deterministic lane checks | +| `action_assessment` | Balanced | Sets possibility, DC, stakes, outcome bands, and effect ceiling | Assessment; canonical DC/reference validation and player risk acceptance | +| `assessment_effect_verifier` | Balanced | Checks that a proposed outcome mutation is caused by the exact attempted means | Verdict; invalid effects cannot reach the kernel | +| `gestalt_presence_planner` | Fast/configured | Promotes an earned existing member, admits one speech-authorized first identity, or folds an irrelevant member | Presence plan; exact lineage, location, version, and identity checks | + +## Strategic simulation + +| Stage | Tier | Purpose | Output and downstream gate | +|---|---|---|---| +| `resolution_demand` | Fast | Weights current causal relevance across geography, ideology, authority, economy, species/body, and information | Demand weights and focal IDs; deterministic connected partitioner owns the cover | +| `nemesis_attention_agent_action` | Balanced, agentic | Searches committed causal anchors and decides which autonomous subjects genuinely need a response window now | Anchor/responder assignments or none; exact subject/anchor validation, no action authority | +| `cell_projector` | Fast/configured | Projects a cell's exact constituents and required perspective owners without merging private state | Cell lived context | +| `cell_persona` | Balanced/configured | Lets each required actor, institution, population, or named member appraise and choose independently | Attributed natural decisions; arenas never speak as synthetic actors | +| `cell_interpreter` | Capable/configured, agentic | Translates each selected strategic decision into one or more typed attempts | Attributed action proposals; graph, target, location, and effect validation | +| `cell_effect_verifier` | Balanced/configured | Checks that each strategic attempt uses only its own constituent's authority and knowledge | Ordered verdicts; correction may reuse the same bounded workbench | +| `strategic_outcome_resolver` | Balanced | Resolves opposition and proposes one durable result per admitted action | Outcome bundle; exact handles and action digests must match | +| `strategic_outcome_verifier` | Fast/Balanced | Independently checks high-risk custody, relation, knowledge, and member-specific consequences | Selective semantic verdict; ordinary structural effects remain deterministic | +| `strategic_individuation_selector` | Fast | Names at most one person when selected Gestalt action creates political work that cannot remain anonymous | Member proposal or none; shared individuation validator and kernel admission | + +## Newspaper + +| Stage | Tier | Purpose | Output and downstream gate | +|---|---|---|---| +| `newspaper_narrative_selection_agent_action` | Balanced, agentic | Assignment editor queries the frozen ledger, chooses issue shape and throughline, assigns recurring reporters, and binds evidence | Immutable agenda checkpoint; exact record, reporter, lead, and conflict-axis validation | +| `newspaper_journalist_agent_action` | Balanced, agentic | One embodied journalist writes one assigned story through their recurring beat, voice, biases, and source habits | Article copy plus citations; no factual admission authority | +| `newspaper_copy_desk` | Balanced | Performs the single hard factual review over the assembled page | Complete finding checklist; cannot rewrite or publish | +| `newspaper_night_editor_close_agent_action` | Balanced, agentic | Repairs the copy desk checklist once while preserving narrative and closes at deadline | Final page; deterministic press witness checks structure and lineage | + +Post-press grounding review is audit, not another same-edition rewrite loop. +Supported corrections become later-edition memory. + +## Deterministic stages that deliberately use no model + +The `WorldKernel`, mutation reducer, resolution partitioner, dice roller, +identity/version checks, topology and custody validation, information-scope +checks, checkpoint recovery, provenance hashing, archive verification, and Eve +projection lowering are deterministic. Keeping these outside model prompts is +what lets agents negotiate with the engine instead of impersonating it. diff --git a/content/Documentation/Architecture at a glance.md b/content/Documentation/Architecture at a glance.md new file mode 100644 index 0000000..5d3b16f --- /dev/null +++ b/content/Documentation/Architecture at a glance.md @@ -0,0 +1,64 @@ +--- +title: Architecture at a glance +description: Ghostlight's major organs and the flow from source evidence to committed world change. +--- + +## Major organs + +| Organ | Responsibility | Does not own | +|---|---|---| +| Lore Vault boundary | Retrieves exact source witnesses and records provenance | Campaign truth or invented facts | +| Session Zero | Negotiates campaign premise, roles, boundaries, and explicit player decisions | Published world state before approval | +| World compiler | Produces a bounded seed, topology, civic machinery, actors, populations, and agency profiles | Runtime mutation after publication | +| Projector | Converts permitted typed state into one subject's lived context | Canonical state or another subject's knowledge | +| Persona | Appraises and responds from the projected perspective | Typed effects or commit authority | +| Interpreter | Translates natural intent into the closed action algebra | Whether the action succeeds or commits | +| Assessor | Determines possibility, difficulty, stakes, and admissible mutation scope | Dice, narration, or world commit | +| Multiresolution resolver | Derives a connected active cover over canonical subjects | Subject identity, facts, or population membership | +| Nemesis | Selects who needs a decision window in response to unresolved causal pressure | Cover construction, actions, or outcomes | +| Strategic outcome resolver | Proposes bounded consequences for selected strategic attempts | Mutation admission or persistence | +| Titled elaborators | Propose one additive worldbuilding operation at a time | Existing state, evidence, or direct writes | +| Newspaper | Selects and narrates committed public events through an editorial Persona | World events or factual admission | +| `WorldKernel` | Validates commands and atomically commits canonical state, events, receipts, and revision | Model inference or presentation | +| CultCache / CultMesh / Eve | Persist typed state, publish provider state, and render interfaces | The domain decisions represented by that state | + +## Two scales, one world + +Canonical actors, institutions, population Gestalts, and durable named members +form the latent agency graph. An active-cell entitlement controls simultaneous +attention, not population size. A deterministic resolver compresses the graph +into cohesive cells and adversarial arenas while preserving complete coverage. + +At the current full-world target: + +```text +latent actionable subjects: about 2,400 +active cell entitlement: 240 +target active cover: about 10% +provider concurrency: separately bounded, at most 32 +``` + +Gestalt compression is reversible simulation resolution. It does not merge +identities or knowledge. Named members retain personal memories, possessions, +relationships, injuries, and obligations when folded back into a population. + +## One write path + +Foreground actions, NPC reactions, strategic waves, waits, travel, population +movement, region expansion, locality elaboration, clock consequences, and +approved population fission all lower into the same closed semantic mutation +algebra. `WorldKernel` validates the complete batch against one exact authority +envelope and commits it atomically. + +The browser, scheduler, models, newspapers, checkpoints, and reconciliation +workers cannot create a second result. A checkpoint proves work already done; +it is not another owner of the world. + +## Consumer boundary + +Ghostlight accepts sparse consumer-authored world seeds and externally owned +boundary snapshots through a generic contract. Delvehold retains sovereignty +over the Greathold, its players, civic state, dungeons, workshops, contracts, +and quantitative economy. Ghostlight owns the autonomous world beyond that +boundary. Each side validates proposed consequences inside its own authority. + diff --git a/content/Documentation/Authority and state.md b/content/Documentation/Authority and state.md new file mode 100644 index 0000000..7d22f2f --- /dev/null +++ b/content/Documentation/Authority and state.md @@ -0,0 +1,80 @@ +--- +title: Authority and state +description: Canonical owners, derived projections, forbidden writers, and persistence rules. +--- + +## Canonical owners + +- `WorldKernel` owns campaign revision and atomic world mutation. +- Actor state owns an individual's location, conditions, knowledge, goals, + possessions, commitments, and relationships. +- Institution state owns institutional posture, resources, goals, location, + information channels, and agency profile. +- A Gestalt owns a population's shared baseline. Durable member deltas own each + named person's departures from that baseline. +- World facts own their statement, scope, evidence ancestry, and discovery + locations. +- Clocks own progress, threshold, consequence declaration, and observable + scope. +- Civic manifests own public authority, selection or succession, resources, + redress, resident populations, governing institutions, and political edges + for one jurisdiction. +- The event ledger owns committed history. Newspaper copy is a projection of + that history, never a replacement for it. + +## Derived state + +The following values are disposable and reconstructable: + +- resolution cells and arenas; +- merge loss and demand weights; +- Nemesis attention assignments; +- Projector lived streams; +- browser and Eve surfaces; +- newspaper source queries and layouts; +- aggregate compatibility rows; +- build, run, and resume checkpoints. + +Derived state may carry exact bindings and still remain non-authoritative. A +receipt proves which proposal was considered against which snapshot; it does +not grant the proposer ownership of the result. + +## Proposal-only model boundary + +Every model stage is proposal-only. A stage may select, classify, appraise, +draft, translate, reconcile, or verify within its supplied schema. It cannot: + +- advance world revision; +- mutate another subject's private state; +- invent a source receipt; +- rebase stale work; +- widen its authority because an output field exists; +- commit only the valid half of an invalid batch. + +Semantic repair is bounded to the same frozen snapshot. Reconciliation workers +operate a private workbench and submit a corrected proposal through the same +validator; they do not patch canonical state. + +## Atomic persistence + +Accepted mutations, authority envelopes, model receipts, causal receipts, +events, and compatibility projections are persisted together through +CultCache. A later publication or interface refresh cannot roll back a commit. +Failure before commit changes nothing; failure after commit is recovered by +reading canonical state and rebuilding the missing projection or checkpoint. + +## Knowledge and perception + +Canonical truth and subject-local knowledge are separate components. A model +sees only the projection permitted for its exact perspective. Communication +adds existing facts to exact recipients; observation may admit a bounded local +finding when the attempted means can actually establish it. Public channels +are concrete information routes, not magic global knowledge. + +## External sovereignty + +A consumer may own a boundary subject completely. Ghostlight can observe its +published effects, depend on it, bargain with it, and propose consequences to +it, but cannot give it an autonomous turn or fabricate its internal choices. +The Greathold in Delvehold is the first intended example. + diff --git a/content/Documentation/Runtime pipelines.md b/content/Documentation/Runtime pipelines.md new file mode 100644 index 0000000..a557cc5 --- /dev/null +++ b/content/Documentation/Runtime pipelines.md @@ -0,0 +1,95 @@ +--- +title: Runtime pipelines +description: End-to-end Ghostlight flows from campaign negotiation to newspapers. +--- + +## Session Zero and publication + +1. A Projector lowers permitted shared or private negotiation state. +2. The persistent DM Persona speaks naturally with the players. +3. The Session Zero Interpreter extracts only newly proposed typed changes. +4. Material bargains remain unresolved until the exact owner accepts them. +5. Evidence retrieval and the compiler produce an approval preview. +6. Campaign, membership, contract, DM Persona, evidence, and seed digest publish + atomically before the campaign becomes discoverable. + +## World compilation + +1. Retrieval planners formulate bounded Vault queries. +2. Evidence relevance classifies direct seed evidence separately from + background and excluded material. +3. The compiler proposes local topology, actors, institutions, populations, + clocks, facts, and civic machinery. +4. Agency stages profile every non-player strategic subject and compile + relations and doctrines. +5. Deterministic validation checks topology, identity, evidence, knowledge, + civic closure, and authority. +6. Compatible missing detail may be reconciled on a private bounded workbench. +7. The registry publishes the accepted seed as an empty-store creation + transaction. Runtime models never gain a parallel creation path. + +## Foreground turn + +1. The speech-address resolver chooses exact co-present addressees. +2. Each affected participant receives its own Projector and Persona appraisal. +3. Direct addressees must speak or choose deliberate silence. +4. The Interpreter lowers proposed intent into the closed action algebra. +5. Mutation-scope preflight removes impossible effect lanes. +6. The assessor decides possibility, DC, stakes, and outcome ceilings. +7. The player accepts the exposed risk; the server rolls. +8. An effect verifier checks that the chosen typed consequence follows from the + attempted means and supplied authority. +9. `WorldKernel` commits the whole result and event atomically. + +## Strategic wave + +1. Resolution demand weights geography, ideology, authority, economy, body or + species, and information for the current horizon. +2. The deterministic partitioner derives a connected cover under the active + cell entitlement. +3. Nemesis searches committed causal anchors and assigns exact responders that + genuinely need a decision window. It may assign nobody. +4. Every selected cell runs Projector → Persona → Interpreter independently and + in parallel under a separate provider semaphore. +5. Cell effect verification rejects actions that borrow another constituent's + knowledge or authority. +6. The strategic outcome resolver proposes one bounded result per admitted + action; a separate outcome verifier checks selective semantic risks. +7. Optional individuation may name one person whose political work can no + longer remain anonymous. +8. `WorldKernel` validates the complete wave, advances time and clocks, commits + state and events atomically, then refreshes public projections. + +## World elaboration + +1. A consumer scale intent and current canonical subject count derive the + actionable-subject target and deficit. +2. Realm complexity weights distribute that target; the active cell budget and + provider concurrency remain separate controls. +3. The elaboration scheduler dispatches titled workers in proportion to their + user-controlled slider shares. +4. Each worker proposes exactly one additive place, route, fact, population, + institution, relation, migration edge, or civic-system operation. +5. Deterministic validation resolves write conflicts and verifies the complete + candidate. An independent civic verifier reviews inhabited apparatus. +6. `WorldKernel` alone admits the finalized operation set. + +The fixed-pass full-world driver is currently being replaced by the scale +demand described above. The derivation is implemented; subject-producing, +resumable budget expenditure remains active work and is not claimed complete. + +## Newspaper + +1. The assignment editor queries the immutable public-event ledger and selects + an issue shape, throughline, stories, evidence, and the best reporter for + each assignment. +2. Recurring in-world journalists write from individual beats, biases, source + habits, voices, and blind spots. Their job is narrative, not factual + admission. +3. The copy desk performs one factual review and returns a complete checklist. +4. The Night Editor receives the assembled page and that checklist once, + repairs what it can while preserving the story, and closes at deadline. +5. Deterministic provenance binds every factual assertion to exact committed + sources. Errors found after close become correction memory for a later + edition rather than an infinite rewrite loop. + diff --git a/content/Documentation/index.md b/content/Documentation/index.md new file mode 100644 index 0000000..a8a9198 --- /dev/null +++ b/content/Documentation/index.md @@ -0,0 +1,50 @@ +--- +title: Architecture +description: A public reference for Ghostlight's persistent-world simulation, agent pipeline, and authority boundaries. +--- + +Ghostlight is a persistent generative-agent engine. Models propose perceptions, +decisions, interpretations, and bounded worldbuilding operations; deterministic +code decides what those proposals are allowed to mean; one revisioned +`WorldKernel` commits canonical change. + +This reference describes the implemented Ghostlight Dungeon body and the +consumer-neutral machinery being prepared for Delvehold. It distinguishes live +code from planned scale work. In particular, the 240-cell ceiling is an active +attention budget, not a claim that the world contains only 240 subjects. The +current full-world target is approximately 2,400 potentially acting entities +under roughly ten-percent active cover. + +## Read the machine + +- [[Architecture at a glance]] — the organs and the main dataflow. +- [[Authority and state]] — who is allowed to decide and persist what. +- [[Runtime pipelines]] — Session Zero, compilation, foreground turns, + strategic simulation, elaboration, and newspapers. +- [[Agents and model stages]] — every production agent and model stage, its + inputs, output, model class, authority, and downstream gate. + +## The compact rule + +```text +source evidence + canonical state + ↓ projection + model proposal + ↓ deterministic validation + typed mutation or refusal + ↓ WorldKernel + atomic state + event + receipt commit +``` + +A model response is never world truth merely because it is well written or +well typed. Receipts bind every accepted inference to its exact stage and world +snapshot. Invalid, stale, or partially illegal work leaves canonical state +unchanged. + +## Scope + +The public reference follows the current source in `crates/ghostlight-dungeon`. +Research plans and older fixture pipelines remain in the repository but are not +presented as live runtime stages. Physical model names are deployment choices; +the architecture names the stable logical tiers: Fast, Balanced, and Capable. + diff --git a/content/index.md b/content/index.md index bdf0812..1f65d3f 100644 --- a/content/index.md +++ b/content/index.md @@ -8,6 +8,7 @@ description: A persistent, source-grounded AI roleplaying world that remembers w <div class="gd-nav-links"> <a href="#world">The world</a> <a href="#vaults">Lore Vaults</a> +<a href="/Documentation/">Architecture</a> <a href="#plans">Plans</a> <a class="gd-nav-cta" href="mailto:meta@gamecult.org?subject=Ghostlight%20Dungeon%20early%20access">Join early access</a> </div> diff --git a/scripts/sync-architecture-docs.ps1 b/scripts/sync-architecture-docs.ps1 new file mode 100644 index 0000000..592383c --- /dev/null +++ b/scripts/sync-architecture-docs.ps1 @@ -0,0 +1,48 @@ +param( + [string]$GhostlightRoot = (Join-Path (Split-Path -Parent $PSScriptRoot) "..\Ghostlight"), + [switch]$Check +) + +$ErrorActionPreference = "Stop" +$siteRoot = Split-Path -Parent $PSScriptRoot +$sourceRoot = Join-Path $GhostlightRoot "docs\public-architecture" +$destinationRoot = Join-Path $siteRoot "content\Documentation" + +if (-not (Test-Path -LiteralPath $sourceRoot)) { + throw "Ghostlight public architecture source was not found at '$sourceRoot'." +} + +$sourceFiles = Get-ChildItem -LiteralPath $sourceRoot -File -Filter *.md | Sort-Object Name +if (-not $sourceFiles) { + throw "Ghostlight public architecture source contains no Markdown files." +} + +if ($Check) { + foreach ($source in $sourceFiles) { + $destination = Join-Path $destinationRoot $source.Name + if (-not (Test-Path -LiteralPath $destination)) { + throw "Published architecture projection is missing '$($source.Name)'." + } + $sourceHash = (Get-FileHash -LiteralPath $source.FullName -Algorithm SHA256).Hash + $destinationHash = (Get-FileHash -LiteralPath $destination -Algorithm SHA256).Hash + if ($sourceHash -ne $destinationHash) { + throw "Published architecture projection is stale: '$($source.Name)'." + } + } + $extra = Get-ChildItem -LiteralPath $destinationRoot -File -Filter *.md | + Where-Object { $_.Name -notin $sourceFiles.Name } + if ($extra) { + throw "Published architecture projection has unowned files: $($extra.Name -join ', ')." + } + Write-Output "Architecture projection matches Ghostlight source." + exit 0 +} + +New-Item -ItemType Directory -Path $destinationRoot -Force | Out-Null +Get-ChildItem -LiteralPath $destinationRoot -File -Filter *.md -ErrorAction SilentlyContinue | + Remove-Item -Force +foreach ($source in $sourceFiles) { + Copy-Item -LiteralPath $source.FullName -Destination (Join-Path $destinationRoot $source.Name) +} +Write-Output "Published $($sourceFiles.Count) architecture pages from Ghostlight source." + diff --git a/site/quartz.config.ts b/site/quartz.config.ts index 79f21bb..c0a6a42 100644 --- a/site/quartz.config.ts +++ b/site/quartz.config.ts @@ -72,6 +72,7 @@ const config: QuartzConfig = { Plugin.CreatedModifiedDate({ priority: ["frontmatter", "git", "filesystem"] }), Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: true }), Plugin.GitHubFlavoredMarkdown(), + Plugin.TableOfContents(), Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }), Plugin.Description(), ], diff --git a/site/quartz.layout.ts b/site/quartz.layout.ts index 19e409c..27e08dd 100644 --- a/site/quartz.layout.ts +++ b/site/quartz.layout.ts @@ -1,6 +1,18 @@ import { PageLayout, SharedLayout } from "./quartz/cfg" import * as Component from "./quartz/components" +const documentationExplorer = Component.ConditionalRender({ + component: Component.Explorer({ + title: "Architecture", + folderDefaultState: "open", + folderClickBehavior: "link", + useSavedState: false, + filterFn: (node) => node.slug.startsWith("Documentation"), + }), + condition: (page) => + page.fileData.slug === "Documentation" || page.fileData.slug?.startsWith("Documentation/"), +}) + export const sharedPageComponents: SharedLayout = { head: Component.Head(), header: [], @@ -15,15 +27,24 @@ export const sharedPageComponents: SharedLayout = { } export const defaultContentPageLayout: PageLayout = { - beforeBody: [], + beforeBody: [ + Component.ConditionalRender({ + component: Component.ArticleTitle(), + condition: (page) => page.fileData.slug !== "index", + }), + ], afterBody: [], - left: [], - right: [], + left: [documentationExplorer], + right: [ + Component.ConditionalRender({ + component: Component.TableOfContents(), + condition: (page) => page.fileData.slug?.startsWith("Documentation/"), + }), + ], } export const defaultListPageLayout: PageLayout = { - beforeBody: [], - left: [], + beforeBody: [Component.ArticleTitle()], + left: [documentationExplorer], right: [], } - diff --git a/site/quartz/styles/custom.scss b/site/quartz/styles/custom.scss index 80aafa2..a3e8266 100644 --- a/site/quartz/styles/custom.scss +++ b/site/quartz/styles/custom.scss @@ -11,13 +11,42 @@ body { #090b12; } -.page > #quartz-body { display: block; } -.page > #quartz-body .center { margin: 0; max-width: none; padding: 0; } -.page > #quartz-body .page-header { margin: 0; } -.page article { max-width: none; } -.page article > h1:first-child { display: none; } +.page:has(.gd-shell) > #quartz-body { display: block; } +.page:has(.gd-shell) > #quartz-body .center { margin: 0; max-width: none; padding: 0; } +.page:has(.gd-shell) > #quartz-body .page-header { margin: 0; } +.page:has(.gd-shell) article { max-width: none; } +.page:has(.gd-shell) article > h1:first-child { display: none; } .page footer { max-width: 1180px; margin: 0 auto; padding: 2rem 1.5rem 3rem; border-top: 1px solid rgba(255,255,255,.08); } +.page:not(:has(.gd-shell)) article { + font-family: "Inter", sans-serif; + line-height: 1.72; +} + +.page:not(:has(.gd-shell)) article table { + display: table; + width: 100%; + font-size: .86rem; +} + +@media (min-width: 960px) { + .page:not(:has(.gd-shell)) > #quartz-body { + display: grid; + grid-template-columns: minmax(180px, 230px) minmax(0, 760px) minmax(160px, 220px); + gap: 2.5rem; + max-width: 1260px; + margin: 0 auto; + padding: 2.5rem 1.5rem 0; + } + + .page:not(:has(.gd-shell)) > #quartz-body .center { + min-width: 0; + max-width: 760px; + margin: 0; + padding: 0; + } +} + .gd-shell { --mint: #73efd1; --violet: #e39bff; --paper: #f8f5ff; --muted: #9aa0b5; color: var(--paper); overflow: hidden; } .gd-shell * { box-sizing: border-box; } .gd-shell a { color: inherit; }