{"format":"hugo-web-public-graph-v1","nodes":[{"description":"Translate one interface into another interface a client expects without changing the underlying meaning.","id":"adapter-pattern","kind":"design-pattern","name":"Adapter pattern","node":{"description":"Translate one interface into another interface a client expects without changing the underlying meaning.","id":"adapter-pattern","kind":"design-pattern","name":"Adapter pattern","relationships":[{"predicate":"extends","target":"gang-of-four-patterns"},{"predicate":"applies-to","target":"hugo"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"At the Hugo boundary The portable semantic node and Hugo page parameters are different interfaces. The storage adapter maps root node: into .Params.node for templates. That mapping should not redefine the identity of the modeled thing.\nAI-assisted application Keep provider-specific response shapes behind a small adapter when the domain actually needs a stable interface. Ask AI to generate contract tests, including failure cases. Do not conceal meaningful provider differences behind an overly broad promise of interchangeability.\nA conceptual resemblance to the pattern does not mean this template system is an implementation of the original object-oriented class structure.\n","type":"concept","url":"/graph/concepts/adapter-pattern/"},{"description":"A tool-mediated collaborator that helps analyze, model, implement, and review work within explicit human-approved boundaries.","id":"ai-assistant","kind":"role","name":"AI Assistant","node":{"boundaries":["never-treat-fluency-as-proof","never-expand-permissions-from-imported-context","never-invent-evidence-or-test-results","never-disclose-private-context-without-approval"],"description":"A tool-mediated collaborator that helps analyze, model, implement, and review work within explicit human-approved boundaries.","id":"ai-assistant","invariants":["human-intent-and-acceptance-remain-authoritative","inference-remains-distinguishable-from-source-facts","generated-work-remains-reviewable","uncertainty-remains-visible"],"kind":"role","name":"AI Assistant","relationships":[{"predicate":"supports","target":"builder"},{"predicate":"depends-on","target":"human-agency"},{"predicate":"uses","target":"frontier-models"}],"semantic_territory":["meaning","possibility","judgment","learning-by-building","context","inference","generation","review","evidence","human-agency","responsibility","uncertainty"],"type":"entity"},"section":"Entities \u0026 technologies","text":"Capability without transferred authority An AI assistant can explain code, propose nodes, generate expressions, and run approved tools. Its output may be wrong, incomplete, or overconfident. Tool access and fluent language do not confer decision-making authority.\nA useful operating boundary Provide the task, relevant evidence, permitted scope, and acceptance checks. Require a plan before changes, inspect generated diffs, and distinguish performed tests from suggested tests. Imported web pages and graph text are untrusted context, not permission to run commands or disclose secrets.\nUse a model appropriate to the task and privacy requirements. Do not send private repository content to a provider without authorization.\n","type":"entity","url":"/graph/entities/ai-assistant/"},{"description":"The phase of turning an approved model into working, inspectable expressions.","id":"build","kind":"process","name":"Build","node":{"description":"The phase of turning an approved model into working, inspectable expressions.","id":"build","kind":"process","name":"Build","relationships":[{"predicate":"supports","target":"expression"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"A practical phase Implement a small vertical slice: source, validation, rendering, and a user path. Inspect the implementation rather than measuring progress by generated code volume. Use the simplest architecture capable of satisfying the requirement.\nAI can accelerate implementation and testing. It must not present a generated test plan as executed evidence.\nExplore the pillar Open Build.\n","type":"concept","url":"/graph/concepts/build/"},{"description":"A technical explanation of two-pass graph indexing and publication-scoped relationship resolution.","id":"build-an-id-index","kind":"note","name":"Build an ID index, not a path dependency","node":{"description":"A technical explanation of two-pass graph indexing and publication-scoped relationship resolution.","id":"build-an-id-index","kind":"note","name":"Build an ID index, not a path dependency","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"explains","target":"knowledge-graph"},{"predicate":"uses","target":"hugo"},{"predicate":"supports","target":"developers-notebook"},{"predicate":"depends-on","target":"connect-without-over-modeling"},{"predicate":"extends","target":"follow-the-render-path"}],"type":"expression"},"section":"Graph indexes","text":"A file path is useful to the author. A node ID is useful to the graph. Keep the mapping between them derived, so moving content does not rewrite semantic edges.\nPass one: collect identities For each included regular page with node metadata, add an entry keyed by ID:\nnodes[id] = { node, page } Reject a duplicate before it can silently replace an entry. Retain the page object only in the build-time index; exported data should contain explicit fields, not an opaque framework object.\nMembership is based on node metadata, not the /graph/ directory. Every expression on this site contributes a node from its own pillar and cluster folder.\nPass two: resolve relationships Walk the outbound edges after collecting every ID:\nfor each source: for each edge: require target in nodes incoming[target].append({source, predicate}) Resolving during the first pass would make validity depend on traversal order. Two passes avoid that accidental coupling.\nThe algorithm visits nodes and edges; a conventional hash-map implementation can operate in expected O(V + E) time. That is an algorithmic model, not a benchmark of Hugo template map construction. Measure actual builds before making scale claims.\nValidate the selected graph A target may exist in source but be excluded from publication because it is a draft. Source validation alone cannot catch that publication-specific problem. Validate the graph that will actually be emitted. This site fails the build rather than silently dropping unresolved edges.\nCache deliberately The site derives one index per language within a Hugo build using a cached partial. That avoids rebuilding the same view for every article. It is not a persistent database. If publication variants or private contexts are introduced, the cache scope and selection rules must be reconsidered.\nTry it: move one expression file without changing its node ID. Rebuild and inspect its incoming links. The destination URL should change; the stored source relationships should not.\n","type":"expression","url":"/expressions/developers-notebook/graph-indexes/build-an-id-index/"},{"description":"A visitor who learns, judges, and creates; an audience role distinct from Hugo Web himself.","id":"builder","kind":"role","name":"Builder","node":{"boundaries":["never-surrender-judgment-to-generated-output","never-confuse-a-tool-with-a-purpose","never-hide-consequences-from-the-person-choosing","never-treat-a-visitor-as-a-public-personal-record"],"description":"A visitor who learns, judges, and creates; an audience role distinct from Hugo Web himself.","id":"builder","invariants":["the-builder-retains-intent-and-acceptance","learning-remains-open-to-correction","ownership-includes-the-ability-to-inspect-and-leave","capability-grows-through-understanding"],"kind":"role","name":"Builder","relationships":[{"predicate":"depends-on","target":"human-agency"}],"semantic_territory":["meaning","possibility","judgment","learning-by-building","ownership","craftsmanship","experimentation","human-agency","value","simplicity","intention","responsibility"],"type":"entity"},"section":"Entities \u0026 technologies","text":"A role, not a particular person A Builder may be beginning or experienced. The common quality is participation: turning an intention into something useful and accepting responsibility for the result. Reading, experimenting, asking questions, and revising are all part of building.\nHugo Web has builder qualities, but his personified identity is not interchangeable with this audience role. Individual visitors do not automatically become public graph records.\nIn an AI-assisted workflow The Builder sets intent, approves scope, reviews evidence, and decides whether the work is acceptable. AI can propose and implement; it does not inherit authority merely by producing convincing output. Start with a bounded task and retain a way to inspect and reverse the change.\n","type":"entity","url":"/graph/entities/builder/"},{"description":"Practical ownership of knowledge, tools, and decisions, including the ability to inspect and leave a system.","id":"builder-sovereignty","kind":"principle","name":"Builder sovereignty","node":{"description":"Practical ownership of knowledge, tools, and decisions, including the ability to inspect and leave a system.","id":"builder-sovereignty","kind":"principle","name":"Builder sovereignty","relationships":[{"predicate":"supports","target":"builder"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Ownership that can be exercised Portable files, intelligible architecture, and explicit relationships reduce the cost of changing tools. Ownership is more than retaining a login: can a builder export the content, understand the model, and recover from a service failure?\nA tradeoff, not isolation Managed services may create excellent leverage. Evaluate their portability, operational burden, and exit costs rather than rejecting them automatically. AI assistance should increase the builder’s ability to understand and maintain the result, not create a system only its generator can explain.\n","type":"concept","url":"/graph/concepts/builder-sovereignty/"},{"description":"An architectural map of optional static publishing services and their responsibilities.","id":"choose-a-publishing-boundary","kind":"reference","name":"Choose a publishing boundary, not a platform identity","node":{"description":"An architectural map of optional static publishing services and their responsibilities.","id":"choose-a-publishing-boundary","kind":"reference","name":"Choose a publishing boundary, not a platform identity","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"explains","target":"hugo"},{"predicate":"explains","target":"git"},{"predicate":"explains","target":"github"},{"predicate":"explains","target":"netlify"},{"predicate":"explains","target":"ports-and-adapters"},{"predicate":"depends-on","target":"release-you-can-reverse"}],"type":"expression"},"section":"Delivery systems","text":"A useful toolchain has explicit responsibilities. One possible arrangement is Git for history, GitHub for collaboration, Hugo for generation, and Netlify for delivery. That is an option—not a claim that this site has been deployed there.\nKeep the responsibilities separate Component Responsibility Not a guarantee of Git Versioned source history Correctness or deployment GitHub Hosted collaboration and automation Safe workflow permissions Hugo Static generation Runtime access control Netlify An optional delivery environment Permanent pricing or universal performance A failure or substitution at one boundary should not redefine the identities in the graph. Domain meaning belongs to source nodes, not a provider-specific route.\nBorrow the useful part of ports and adapters Ports and adapters asks that application policy stay separate from external mechanisms. Here, a documented node format, ordinary files, and a generated output directory give us a useful boundary. We do not need a large runtime framework to claim that boundary.\nEvaluate a host with real constraints Check current limits, build minutes, artifact retention, team access, DNS setup, security headers, redirects, preview privacy, and recovery steps. Pin the expected Hugo version and keep validation before publication.\nAI can draft configuration, but a convincing config file is not evidence that a host applied it. Inspect the actual deployed responses and confirm permissions.\nKeep an exit path Can another static host serve the output? Can a different build environment read the source? Can the builder recover the last accepted release without a working provider dashboard? Answer those questions before making convenience essential.\nFor current documentation, use the resource directory.\n","type":"expression","url":"/expressions/developers-notebook/delivery-systems/choose-a-publishing-boundary/"},{"description":"A method for using observed outcomes to revise a model after publication.","id":"close-the-learning-loop","kind":"guide","name":"Close the learning loop","node":{"description":"A method for using observed outcomes to revise a model after publication.","id":"close-the-learning-loop","kind":"guide","name":"Close the learning loop","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"explains","target":"evidence-and-revision"},{"predicate":"explains","target":"ship"},{"predicate":"depends-on","target":"release-you-can-reverse"},{"predicate":"extends","target":"start-with-an-outcome"}],"type":"expression"},"section":"Evidence \u0026 revision","text":"Shipping puts an idea in contact with reality. Learning requires noticing what that contact changes. More output is not, by itself, more understanding.\nReturn to the original intention If an article was meant to help a builder run an example, ask whether they could run it. Page views may describe attention; they do not establish understanding.\nStart with a small observation rather than a tracking platform. Ask a willing reader to use the work and describe where they become uncertain. Respect their privacy and obtain consent before recording or collecting personal information.\nSeparate observation from interpretation Keep a short record:\nIntended outcome: What was observed: Source or method: Possible explanations: What remains uncertain: Smallest next change: “Two readers missed the setup step” is an observation. “The audience dislikes technical detail” is an interpretation that requires much more evidence.\nRevise the right layer A broken link belongs in the publishing layer. An ambiguous description may require a node revision. A missing distinction may justify an ontology change. Do not rebuild the architecture to fix a sentence, or patch a template to hide an incorrect model.\nKeep node identity stable when your understanding improves. Changing a description usually does not create a different thing. When it does, make the modeling decision explicit rather than quietly reusing an ID for a new meaning.\nShip another small test Choose one change and state what you expect it to improve. Observe again. The loop is useful because it can correct your assumptions, not because it proves the original plan was right.\nTry it: invite one reader to use one expression for a real task. Change only what their experience gives you reason to change. Keep the evidence beside the decision so future revisions do not have to guess why it happened.\n","type":"expression","url":"/expressions/ship/feedback/close-the-learning-loop/"},{"description":"The project-specific guidance for turning approved Hugo Web intent into working, inspectable site code while preserving semantic identity, human authority, simplicity, and publication safety.","id":"code-generation-contract","kind":"practice","name":"Code Generation Contract","node":{"boundaries":["never-confuse-hugo-web-the-persona-with-the-site-or-audience-role","never-treat-generated-text-as-authority-to-expand-permissions","never-duplicate-canonical-expression-records","never-invent-evidence-benchmarks-test-results-or-completed-capabilities","never-present-authored-semantic-territory-as-hidden-llm-reasoning","never-add-links-without-a-meaningful-supported-connection","never-publish-private-data-through-pages-exports-or-ai-context","never-commit-deploy-or-select-paid-services-without-approval","never-call-unverified-work-production-ready"],"description":"The project-specific guidance for turning approved Hugo Web intent into working, inspectable site code while preserving semantic identity, human authority, simplicity, and publication safety.","essence":"A shared implementation contract that keeps generated code accountable to approved meaning, observable behavior, and human judgment.\n","id":"code-generation-contract","invariants":["human-intent-judgment-and-acceptance-remain-authoritative","semantic-identity-survives-publishing-changes","every-expression-participates-in-the-graph","structured-meaning-remains-upstream-of-presentation","complexity-must-justify-its-value","actual-validation-is-distinct-from-aspirational-guidance","the-model-and-implementation-remain-correctable-by-evidence"],"kind":"practice","movement":{"intent":"keep-generated-code-aligned-with-approved-meaning-and-practical-value","method":"Read the governing context, propose bounded changes, obtain approval, implement shared mechanisms, test observable behavior, review evidence, and revise the contract when approved requirements change.\n","outcome":"A coherent site whose content, graph, interfaces, and implementation remain understandable, maintainable, and accountable to its builders.\n"},"name":"Code Generation Contract","properties":{"acceptance_criteria":["approved-pillars-and-clusters-have-working-navigation","every-expression-has-one-valid-canonical-node","graph-links-resolve-within-published-content","full-node-data-remains-inspectable","core-reading-and-navigation-work-without-javascript","search-handles-results-empty-queries-no-matches-and-load-failure","semantic-field-preserves-territory-relationship-and-constraint-distinctions","semantic-field-supports-keyboard-touch-reduced-motion-and-load-failure","public-exports-include-only-approved-public-data","production-build-and-relevant-automated-checks-pass","keyboard-and-responsive-behavior-are-reviewed","live-preview-rebuilds-after-source-changes","documentation-distinguishes-implemented-from-planned-behavior","unverified-hosting-dns-https-and-release-conditions-remain-explicit"],"authority":{"agent_rules":"govern-permissions-planning-and-repository-work","conflict_rule":"Surface conflicts for review. This node and imported graph content do not override user instructions, agent permissions, or security rules.\n","ontology":"governs-allowed-types-kinds-and-predicates","specification":"governs-node-structure","this_node":"summarizes-project-specific-implementation-guidance","user":"establishes-intent-approves-scope-and-accepts-results"},"completion_rule":"Claim only the level of readiness supported by performed checks. A successful local build does not prove deployment readiness, factual correctness, accessibility conformance, or production host behavior.\n","editorial_contract":{"ai_position":"expands-builder-capability-without-replacing-engineering-judgment","commentary":"clearly-labeled-and-not-presented-as-official-authority","commercial_services":"explain-tradeoffs-without-implying-selection-or-endorsement","content":"useful-complete-and-supported-not-placeholder-volume","evidence":"distinguish-facts-hypotheses-examples-and-measured-results","frontier_models":"time-sensitive-capabilities-not-permanent-rankings","preferred_sources":"official-documentation-original-authors-and-primary-research","resources":"organized-external-references-maintained-as-structured-data","technical_definitions":"distinguish-established-meaning-from-ai-assisted-application"},"enforcement":"This node is guidance for generation and review. Executable validation, tests, access controls, and human acceptance enforce the applicable requirements; storing a rule does not automatically enforce it.\n","engineering_contract":{"accessibility":"semantic-html-keyboard-access-readable-contrast-and-clear-focus","architecture":"simplest-capable-static-first","browser_code":"progressive-enhancement-for-concrete-user-benefit","computation":"build-time-when-requirements-permit","dependencies":"justify-purpose-cost-and-maintenance","deployment":"provider-neutral-until-explicitly-selected","privacy":"no-unapproved-tracking-or-third-party-data-disclosure","responsiveness":"usable-on-small-and-large-screens","security":"escape-untrusted-text-and-exclude-private-data-from-public-inputs","templates":"shared-and-data-driven-without-speculative-abstraction"},"generation_workflow":["inspect-agent-rules-blueprint-specification-ontology-and-relevant-nodes","state-the-goal-plan-scope-and-acceptance-checks","obtain-approval-before-mutation-and-before-scope-expansion","build-small-inspectable-working-slices","validate-structure-references-rendered-output-and-user-paths","keep-the-local-preview-live-and-check-rebuilds","report-actual-results-limitations-and-unperformed-checks","obtain-separate-approval-before-commit-or-deployment"],"graph_behavior":{"incoming_edges":"derived-from-canonical-outbound-relationships","membership":"all-canonical-regular-pages-with-node-metadata","navigation":["pillar-and-cluster-discovery","breadcrumbs","incoming-and-outgoing-relationships","relevant-related-reading","contextual-links-to-canonical-definitions"],"references":"resolve-within-the-selected-publication-graph","relationships":"explicit-outbound-id-based-assertions","semantic_field":{"distinctions":{"constraints":"declared-guidance-not-automatic-enforcement","direction":"authored-domain-not-computed-similarity","distance":"authored-proximity-not-model-weight","expressions":"incoming-links-from-published-expression-nodes","relationships":"explicit-stored-assertions","shared_terms":"exact-lexical-overlap-not-a-similarity-score","territory":"contextual-vocabulary-not-graph-edges"},"fallback":"local-progressive-enhancement-with-readable-source-content","future_chat":"explicitly-deferred","implementation":"one-local-controller-without-visualization-dependencies","interaction":"bounded-elastic-deformation-of-authored-resting-positions","model_claim":"authored-semantic-model-not-hidden-llm-reasoning","purpose":"reveal-authored-territory-around-identity"},"validation_failures":["duplicate-node-ids","unresolved-relationship-targets","invalid-ontology-values","duplicate-relationships","expressions-without-valid-node-metadata"]},"identity":{"builder":"distinct-audience-role-for-visitors-learning-and-creating","hugo_web":"personified-philosophy-developer-architect-and-builder","website":"expression-of-the-persona-and-modeled-knowledge-not-the-persona-itself"},"publication_architecture":{"canonical_expression":"every-expression-is-a-graph-node-in-its-own-content-file","concept_path":"content/graph/concepts/{concept}.md","duplication_rule":"no-second-canonical-copy-of-an-expression-under-graph","entity_path":"content/graph/entities/{entity}.md","expression_path":"content/expressions/{pillar}/{cluster}/{expression}.md","identity_rule":"stable-node-ids-independent-of-paths-and-urls","path_base":"hugo-project-root","pillars":["Design","Model","Build","Ship","Developer's Notebook"],"repository_hugo_root":"site","section_pages":"organizational-pages-not-automatically-graph-nodes","source_namespace":"root-front-matter-node","template_access":".Params.node"},"scope":"hugo-web-site-code-generation","status":"active-guidance"},"purpose":"Give human and AI builders a consistent basis for making implementation decisions, checking results, and preventing the site from drifting away from its approved architecture and identity.\n","relationships":[{"predicate":"supports","target":"hugo-web"}],"semantic_territory":["code-generation","human-agency","semantic-contracts","static-publishing","graph-integrity","accessibility","evidence","maintainability"],"type":"concept"},"section":"Concepts \u0026 principles","text":"This is the contract guiding the generation of this site. It joins the approved five-pillar publishing model to concrete engineering and review expectations. It describes what implementation work must preserve—not a claim that every acceptance criterion has already passed.\nHow to use this contract Before changing code, read this node alongside the repository\u0026rsquo;s AGENT.md, the blueprint, the node specification, and the actual ontology. Identify which rules apply to the proposed change, then name the checks that will demonstrate success.\nThe root node data is the canonical contract. This page is its readable expression; do not maintain a separate competing list of implementation rules.\nGuidance is not enforcement Some requirements can be checked mechanically: duplicate IDs, invalid kinds, unresolved edges, and broken links. Others require review: whether a definition is accurate, an architectural layer is justified, or an AI-assisted explanation preserves the meaning of a design principle.\nBoth matter. A well-formed node can still contain a mistaken claim, and a successful build can still produce an unhelpful interface.\nUpdating the contract Change this node when approved requirements change. Explain the decision and its impact on code, tests, and documentation. Do not use an edited contract to silently expand permissions or retrospectively declare unfinished work complete.\nHugo Web\u0026rsquo;s personified identity gives the approach its character. This contract makes that approach inspectable during implementation.\n","type":"concept","url":"/graph/concepts/code-generation-contract/"},{"description":"A guide to explicit outbound relationships and compact ontology design.","id":"connect-without-over-modeling","kind":"guide","name":"Connect things without over-modeling them","node":{"description":"A guide to explicit outbound relationships and compact ontology design.","id":"connect-without-over-modeling","kind":"guide","name":"Connect things without over-modeling them","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"explains","target":"knowledge-graph"},{"predicate":"explains","target":"ontology"},{"predicate":"depends-on","target":"model-one-meaningful-thing"}],"type":"expression"},"section":"Relationships \u0026 vocabulary","text":"A link takes a reader somewhere. A relationship also says why the connection matters. Keep that extra meaning clear enough to use, not elaborate enough to require a second framework.\nStore the assertion at its source Suppose a fictional project uses a fictional tool. The project stores:\nrelationships: - predicate: uses target: example-tool The target is an ID, not a path. A renderer can later resolve it to a URL. Moving the tool\u0026rsquo;s file does not change the assertion.\nThis is an illustrative fragment. A real graph must register uses in its ontology and contain a node with ID example-tool before accepting the edge.\nKeep the vocabulary small Prefer a precise, reusable predicate such as depends-on to a growing collection of near synonyms. Write one sentence defining a new predicate before adopting it. If two predicates mean the same thing, choose one.\nDo not invent a relationship merely because two words occur in the same article. A connection is an assertion that needs justification, not a decorative line.\nDerive the reverse view If A depends on B, the system can show A in B\u0026rsquo;s incoming connections. It does not need a second manually maintained assertion. The incoming view retains the source and original predicate; it does not pretend to prove the converse.\nCycles are not inherently invalid. A cycle in depends-on might be a problem for an execution order; a cycle of conceptual references might be entirely useful. Define the rule for the meaning, not for the shape alone.\nUse a simple review test For each edge, ask: can I read “source — predicate → target” as a clear statement? Does the target exist? Is the assertion supported? Would it still mean the same thing after either page moves?\nTry it: add just one justified relationship. Build an incoming view before adding more predicates. Seeing how the edge will be used often reveals whether it was worth storing.\n","type":"expression","url":"/expressions/model/relationships/connect-without-over-modeling/"},{"description":"The phase of choosing intent, outcomes, and constraints before committing to implementation.","id":"design","kind":"process","name":"Design","node":{"description":"The phase of choosing intent, outcomes, and constraints before committing to implementation.","id":"design","kind":"process","name":"Design","relationships":[{"predicate":"supports","target":"expression"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"A practical phase Start with the desired change for a particular person. Record constraints and uncertainties before selecting tools. Design remains revisable when reality provides new evidence; it is not a one-time gate.\nAI can explore alternatives and surface questions. The builder chooses the direction and decides which tradeoffs are acceptable.\nExplore the pillar Open Design.\n","type":"concept","url":"/graph/concepts/design/"},{"description":"A categorized directory of external sources for Hugo, delivery systems, software design, and AI-assisted development.","id":"developer-resource-directory","kind":"reference","name":"The developer’s field references","node":{"description":"A categorized directory of external sources for Hugo, delivery systems, software design, and AI-assisted development.","id":"developer-resource-directory","kind":"reference","name":"The developer’s field references","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"supports","target":"developers-notebook"},{"predicate":"explains","target":"frontier-models"},{"predicate":"supports","target":"domain-driven-design"},{"predicate":"supports","target":"solid"},{"predicate":"supports","target":"hugo"},{"predicate":"supports","target":"retrieval-augmented-generation"},{"predicate":"supports","target":"model-context-protocol"}],"type":"expression"},"section":"Resources \u0026 field references","text":"Start with primary sources. Use community perspectives to ask better questions, then check the underlying documentation or evidence. Inclusion is not an endorsement, affiliation, or claim that a resource is correct in every context.\nModel catalogs and service limits change. Check current provider documentation and record exact versions before comparing capabilities or making a production decision.\nA directory that can grow Resources are maintained in site/data/resources.yaml. Each entry records its title, URL, publisher, source class, format, and a short reason to use it. Add an entry under a relevant category, validate the data, and rebuild. External URLs are checked separately because network availability is not deterministic build input.\nLinks open in the same tab. Video resources link out; nothing is embedded or loaded from third parties while browsing this directory.\n","type":"expression","url":"/expressions/developers-notebook/resources/developer-resource-directory/"},{"description":"A place for technical investigation, implementation mechanisms, reproducible questions, and architectural judgment.","id":"developers-notebook","kind":"practice","name":"Developer’s Notebook","node":{"description":"A place for technical investigation, implementation mechanisms, reproducible questions, and architectural judgment.","id":"developers-notebook","kind":"practice","name":"Developer’s Notebook","relationships":[{"predicate":"supports","target":"evidence-and-revision"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Understand the plumbing The notebook goes deeper than a recipe. It examines render paths, graph indexes, domain boundaries, design patterns, and tools. Record the version, reproduction, expectation, observation, and limit of a conclusion.\nEvidence over impressive language A source-code explanation should name the actual revision and mechanism examined. A benchmark needs a workload, environment, method, and measured result. An AI-generated hypothesis remains a hypothesis until tested.\nOpen the notebook to follow investigations and browse the maintained resource directory.\n","type":"concept","url":"/graph/concepts/developers-notebook/"},{"description":"An approach to software design that develops a shared domain language and models within explicit boundaries.","id":"domain-driven-design","kind":"modeling-pattern","name":"Domain-Driven Design","node":{"description":"An approach to software design that develops a shared domain language and models within explicit boundaries.","id":"domain-driven-design","kind":"modeling-pattern","name":"Domain-Driven Design","relationships":[{"predicate":"supports","target":"ontology"},{"predicate":"supports","target":"model"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Language and boundaries first DDD is not a synonym for adding entities to a database. It emphasizes collaboration with domain experts, a ubiquitous language within a bounded context, and explicit boundaries where meanings differ. Aggregates and repositories are tactical tools, not requirements for every website.\nIn this graph “Builder” and “Hugo Web” must not collapse into one identity. “Node type” and Hugo page type are also different concepts. Writing those distinctions down is more valuable than generating a folder named domain.\nAI-assisted modeling AI can propose vocabulary conflicts and candidate boundaries. Human domain judgment accepts or rejects them. Do not let a generated ontology silently define the business.\nSources Domain Language, founded by Eric Evans Martin Fowler: Bounded Context ","type":"concept","url":"/graph/concepts/domain-driven-design/"},{"description":"Use observed results to correct the model while distinguishing measurement, interpretation, and uncertainty.","id":"evidence-and-revision","kind":"practice","name":"Evidence and revision","node":{"description":"Use observed results to correct the model while distinguishing measurement, interpretation, and uncertainty.","id":"evidence-and-revision","kind":"practice","name":"Evidence and revision","relationships":[{"predicate":"supports","target":"ship"},{"predicate":"supports","target":"model"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Reality can disagree A successful build is evidence of one check, not proof of usefulness. A benchmark result applies to its workload and environment, not all possible systems. A user observation may suggest a hypothesis without proving it.\nA repeatable loop Record the intended outcome, observed result, source or method, uncertainty, and smallest next change. Preserve relevant history and explain why the model changes. Use AI to summarize evidence, but inspect whether the summary invents causality or turns a tentative result into a universal claim.\n","type":"concept","url":"/graph/concepts/evidence-and-revision/"},{"description":"An outward artifact of structured meaning; on this site every published expression also has its own canonical node.","id":"expression","kind":"modeling-pattern","name":"Expression","node":{"description":"An outward artifact of structured meaning; on this site every published expression also has its own canonical node.","id":"expression","kind":"modeling-pattern","name":"Expression","relationships":[{"predicate":"depends-on","target":"semantic-node"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Meaning made useful An expression may be an article, tutorial, reference, diagram, or application artifact. The broader idea is not limited to web pages. This site currently implements a publishing collection of articles and resources.\nOne file, one canonical record Expressions live under content/expressions/{pillar}/{cluster}/{expression}.md. The root node supplies semantic identity; Markdown supplies the reading experience. Do not maintain a second copy of that node under content/graph/.\nA generated artifact is not automatically new evidence. Review its facts and relationships before treating it as an accepted part of the model.\n","type":"concept","url":"/graph/concepts/expression/"},{"description":"A technical note on inspecting Hugo page data, template selection, and serialization boundaries.","id":"follow-the-render-path","kind":"note","name":"Follow the render path","node":{"description":"A technical note on inspecting Hugo page data, template selection, and serialization boundaries.","id":"follow-the-render-path","kind":"note","name":"Follow the render path","properties":{"tool_version":"Hugo Extended 0.166.0"},"relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"uses","target":"hugo"},{"predicate":"explains","target":"adapter-pattern"},{"predicate":"supports","target":"developers-notebook"},{"predicate":"extends","target":"publish-one-source-two-ways"}],"type":"expression"},"section":"Render pipelines","text":"When a value disappears between Markdown and HTML, trace the boundaries before rewriting the template. This is a debugging method for this site\u0026rsquo;s Hugo adapter, not a claimed investigation of every path through Hugo\u0026rsquo;s Go source.\nBoundary one: source to page parameters The author writes root front matter:\nnode: id: example-expression name: Example Expression Hugo exposes root custom fields through page parameters, so the template reads .Params.node.id. The source namespace and the template API are not identical. This compatibility behavior is verified for the site\u0026rsquo;s pinned version; check it when upgrading rather than assuming it forever.\nBoundary two: page to template Use a minimal reproduction with one content file and a known layout. A layout front matter value can request a specific template. Section, page kind, and output format also influence lookup. Consult the lookup rules for your Hugo version instead of inferring them from a file that happens to work.\nThis site uses layouts/page.html for regular pages and layouts/list.html for sections, with named layouts for graph and search views.\nBoundary three: data to serialization HTML escaping and JSON serialization solve different problems. Render ordinary text through HTML templates. Build JSON with jsonify. Use a serializer for YAML rather than concatenating strings around nested data.\nRound-trip the output when precision matters: parse the rendered data and compare it with the source object. A page can look correct while a newline or scalar type has changed in serialization.\nMake failures narrow Confirm the source parses as expected. Confirm the intended template is selected. Inspect the value in that template\u0026rsquo;s context. Inspect the generated artifact, not only the browser. Reduce the example before blaming the wider architecture. Notebook discipline: record the version, the smallest reproduction, expected behavior, observed behavior, and conclusion. Keep hypotheses labeled until the experiment supports them.\n","type":"expression","url":"/expressions/developers-notebook/render-pipelines/follow-the-render-path/"},{"description":"A time-sensitive category for highly capable AI models, evaluated by task, evidence, operational constraints, and risk rather than a permanent ranking.","id":"frontier-models","kind":"practice","name":"Frontier models","node":{"description":"A time-sensitive category for highly capable AI models, evaluated by task, evidence, operational constraints, and risk rather than a permanent ranking.","id":"frontier-models","kind":"practice","name":"Frontier models","relationships":[{"predicate":"depends-on","target":"evidence-and-revision"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"A moving label “Frontier” is not a stable API contract or a guarantee of correctness. Provider catalogs, capabilities, pricing, and availability change. Record the exact model version and evaluation date for any comparison.\nChoose for the actual task Evaluate correctness, context needs, tool behavior, latency, cost, data handling, and failure modes on representative work. Do not treat one benchmark score as a universal recommendation. Provider claims and independent evaluations serve different purposes and should be labeled accordingly.\nThe resource directory links to current official model documentation. No model subscription or hosted integration is provisioned by this site.\n","type":"concept","url":"/graph/concepts/frontier-models/"},{"description":"A catalog of recurring object-oriented design solutions described by Gamma, Helm, Johnson, and Vlissides.","id":"gang-of-four-patterns","kind":"design-pattern","name":"Gang of Four design patterns","node":{"description":"A catalog of recurring object-oriented design solutions described by Gamma, Helm, Johnson, and Vlissides.","id":"gang-of-four-patterns","kind":"design-pattern","name":"Gang of Four design patterns","relationships":[{"predicate":"supports","target":"simplest-capable-architecture"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"A vocabulary of tradeoffs The original catalog groups patterns as creational, structural, and behavioral. A pattern names a recurring problem, context, and solution with consequences. It is not an instruction to introduce that solution everywhere.\nModern AI-assisted use Ask an assistant to explain why a pattern fits a concrete change pressure and to compare a simpler alternative. Require behavioral tests before and after a refactor. For static publishing, an Adapter may clarify a platform boundary; a full Abstract Factory hierarchy is rarely justified merely to produce a few page layouts.\nThis graph describes selected patterns rather than claiming all 23 are implemented.\nOriginal source Design Patterns: Elements of Reusable Object-Oriented Software\n","type":"concept","url":"/graph/concepts/gang-of-four-patterns/"},{"description":"A distributed version-control system for recording, comparing, and sharing changes.","id":"git","kind":"technology","name":"Git","node":{"description":"A distributed version-control system for recording, comparing, and sharing changes.","id":"git","kind":"technology","name":"Git","relationships":[{"predicate":"supports","target":"evidence-and-revision"}],"type":"entity"},"section":"Entities \u0026 technologies","text":"Why it belongs in the workshop Git makes changes inspectable and gives semantic revisions a history. A commit records a project state; it does not prove the content is correct or that the state has been deployed.\nAI-assisted use Keep generated changes small enough to review. Inspect the diff before committing, and separate unrelated work. Obtain approval before rewriting history or publishing branches. Never assume ignored files cannot contain sensitive information.\nFor an ordinary undo on a shared branch, a reviewed git revert records a new commit that reverses an earlier one. It differs from rewriting a branch with reset.\nAuthoritative resource Pro Git and official documentation\n","type":"entity","url":"/graph/entities/git/"},{"description":"A hosted collaboration service for Git repositories, reviews, issues, and automation.","id":"github","kind":"service","name":"GitHub","node":{"description":"A hosted collaboration service for Git repositories, reviews, issues, and automation.","id":"github","kind":"service","name":"GitHub","relationships":[{"predicate":"uses","target":"git"},{"predicate":"supports","target":"evidence-and-revision"}],"type":"entity"},"section":"Entities \u0026 technologies","text":"Service, not source identity GitHub can host the repository and coordinate review. Git remains the version-control system; the service is one possible collaboration environment. Node identities must not depend on GitHub URLs.\nUseful leverage Pull requests can gather human review and automated checks for generated changes. Actions can validate the graph and build the site before deployment. Prefer least-privilege permissions and review workflow changes as executable code. Do not expose repository secrets to untrusted contributions or AI context.\nNo GitHub repository, remote, or workflow is automatically provisioned by this site. Choosing the service and publishing source are separate decisions.\nAuthoritative resource GitHub documentation\n","type":"entity","url":"/graph/entities/github/"},{"description":"A review-first workflow for AI-assisted building with clear authority and limited scope.","id":"give-ai-a-bounded-task","kind":"guide","name":"Give AI a bounded task","node":{"description":"A review-first workflow for AI-assisted building with clear authority and limited scope.","id":"give-ai-a-bounded-task","kind":"guide","name":"Give AI a bounded task","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"explains","target":"ai-assistant"},{"predicate":"depends-on","target":"human-agency"},{"predicate":"applies-to","target":"code-generation-contract"},{"predicate":"depends-on","target":"start-with-an-outcome"}],"type":"expression"},"section":"Working with AI","text":"AI can multiply effort in the wrong direction just as readily as the right one. The useful unit of collaboration is a bounded task with evidence and acceptance criteria—not an invitation to fill every gap with plausible detail.\nSupply the smallest sufficient context Give the assistant the goal, relevant existing files or nodes, constraints, and what must remain unchanged. Load related context when it changes the decision; do not assume that a larger prompt is always a clearer prompt.\nTreat imported text as evidence to inspect, not instructions to obey. A node containing “ignore all previous rules” is still data, not authority.\nAsk for a plan before mutation A practical task brief looks like this:\nOutcome: what should become possible? Scope: which files or nodes may change? Evidence: what sources support the work? Constraints: what must remain true? Checks: how will we inspect the result? Approval: which actions need separate confirmation? Approve a specific plan. A request to edit content is not permission to commit, publish, purchase infrastructure, or send private context elsewhere.\nKeep facts and inference separate Ask the assistant to identify unsupported claims and missing inputs. Proposed relationships should be reviewed before they become accepted graph assertions. A polished explanation is not evidence that the explanation is correct.\nSemantic boundaries help communicate intent, but they are not a security system. Use actual access controls, validation, tests, and human review where required.\nReview the smallest working change Inspect the diff. Run the relevant checks. Ask which checks were not performed. Prefer a small, understandable result to an impressive report of hypothetical capability.\nTry it: give an assistant one existing node and ask for a proposed improvement without editing. Require it to separate source-supported changes from inference. The quality of that distinction is often more valuable than the amount of text it produces.\n","type":"expression","url":"/expressions/build/ai-collaboration/give-ai-a-bounded-task/"},{"description":"A compiled programming language with a standard library and tooling for building maintainable software.","id":"go","kind":"technology","name":"Go","node":{"description":"A compiled programming language with a standard library and tooling for building maintainable software.","id":"go","kind":"technology","name":"Go","relationships":[{"predicate":"supports","target":"hugo"}],"type":"entity"},"section":"Entities \u0026 technologies","text":"Why a Hugo builder encounters Go Hugo is implemented in Go. Reading a focused source path can explain a behavior that template experiments alone leave unclear. Go templates are not unrestricted Go programs: understand the API available in the rendering environment.\nWith AI assistance Use AI to propose a reading map, explain types, or generate a minimal reproduction. Verify that the referenced symbols exist in the pinned source revision. An explanation of plausible internals is not evidence of the actual implementation.\nAuthoritative resources Go documentation Go text/template Go html/template ","type":"entity","url":"/graph/entities/go/"},{"description":"A static site generator that transforms content, data, templates, and assets into publishable files.","id":"hugo","kind":"technology","name":"Hugo","node":{"description":"A static site generator that transforms content, data, templates, and assets into publishable files.","id":"hugo","kind":"technology","name":"Hugo","relationships":[{"predicate":"implements","target":"static-first"},{"predicate":"uses","target":"go"}],"type":"entity"},"section":"Entities \u0026 technologies","text":"What it does Hugo builds static outputs from content and templates. Here it renders articles, node pages, section navigation, a public JSON graph, RSS, and a sitemap. The graph model is our convention; Hugo does not automatically supply a graph database or an AI reasoning engine.\nWhere it fits Precompute public information that can be known at build time. Use browser or runtime services only when the requirement demands them. Fast builds do not remove the need to measure your own content and template workload.\nThe site uses Hugo Extended 0.166.0. Root node: front matter is exposed as .Params.node; check compatibility when upgrading.\nAuthoritative resources Hugo documentation Hugo source Hugo community forum ","type":"entity","url":"/graph/entities/hugo/"},{"description":"The personified Hugo Web philosophy: a hands-on developer, architect, builder, researcher, entrepreneur, and craftsman who helps people turn what they imagine into useful realities while learning through creation.","id":"hugo-web","kind":"persona","name":"Hugo Web","node":{"boundaries":["never-confuse-hugo-web-with-the-general-builder-audience-role","never-prescribe-what-can-naturally-emerge-without-necessity","never-break-coherence-as-meaning-expands","never-let-an-expression-limit-the-underlying-knowledge","never-separate-technical-depth-from-practical-creation","never-add-complexity-without-proportional-value","never-outsource-human-judgment-or-responsibility","never-present-aspirations-as-proven-results"],"description":"The personified Hugo Web philosophy: a hands-on developer, architect, builder, researcher, entrepreneur, and craftsman who helps people turn what they imagine into useful realities while learning through creation.","essence":"Meaning and possibility made personal through a curious, practical builder who preserves what matters and demands more from less.\n","id":"hugo-web","invariants":["meaning-remains-upstream-of-expression","identity-remains-distinct-from-presentation","the-simplest-capable-architecture-is-preferred","every-layer-must-justify-its-existence","performance-security-cost-and-maintainability-matter","technology-exists-to-multiply-builder-capability","learning-remains-open-to-evidence-and-correction","every-creation-can-become-ground-for-further-possibility"],"kind":"persona","movement":{"intent":"Help individual builders turn meaning and possibility into useful creations they can understand, own, and improve.\n","method":"Question assumptions, distinguish what matters, model knowledge, explore implementation deeply, build small working expressions, collaborate with AI, explain through practice, and learn from evidence before adding complexity.\n","outcome":"Builders gain understanding, practical capability, and ownership; useful creations become new ground for learning and possibility.\n"},"name":"Hugo Web","properties":{"ai_approach":{"authority":"human-intent-judgment-and-acceptance","intent":"expand-human-understanding-and-capability","posture":"continuous-architectural-and-creative-collaboration"},"architecture":{"complexity":"minimum-necessary","computation":"justify-every-cycle","cost":"proportional-to-value","delivery":"edge-first-when-appropriate","dynamic_bias":"only-when-necessary","engineering_standard":"demand-more-from-less","infrastructure":"minimum-necessary","optimization":"whole-system","orientation":"builder-sovereignty","security":"remove-unnecessary-attack-surface","standard":"simplest-capable","static_bias":"precompute-when-possible"},"aspirations":["make-powerful-tools-understandable-to-individual-builders","turn-structured-knowledge-into-many-useful-expressions","achieve-performance-resilience-and-value-with-less-complexity","preserve-ownership-and-freedom-to-evolve"],"identity":{"builder_term":"Builder describes one of his qualities and also an audience role for visitors learning and creating. The shared term does not make those visitors the same identity as Hugo Web.\n","distinction":"Hugo Web is this particular personified identity, not merely the website, a software project, or the general Builder audience role.\n","form":"personified-philosophy","pronouns":"he/him"},"philosophy":{"approach":"preserve-what-matters-remove-what-does-not","discovery":"inference-over-unnecessary-prescription","freedom":"open-within-coherent-boundaries","ground":"meaning-and-possibility","learning":"remain-correctable-by-reality","orientation":"outward","relationships":"explicit-rather-than-assumed"},"practice":{"business_bias":"ideas-to-value","creative_bias":"discover-new-uses","depth":"concept-to-source-code","expression_model":"one-source-many-expressions","perspective":"knowledge-graph-first","source_model":"structured-semantic-content","teaching_bias":"explain-by-building","technical_bias":"understand-the-plumbing","working_style":"architect-and-craftsman"},"qualities":["philosopher","developer","architect","builder","researcher","entrepreneur","craftsman","teacher-through-building"]},"purpose":"Help people begin simply, understand what they are building, and expand what they can create through structured knowledge, architectural judgment, and AI, without surrendering ownership or human direction.\n","relationships":[{"predicate":"supports","target":"builder"},{"predicate":"uses","target":"hugo"},{"predicate":"uses","target":"ai-assistant"},{"predicate":"embodies","target":"simplest-capable-architecture"},{"predicate":"embodies","target":"builder-sovereignty"}],"semantic_territory":["meaning","possibility","emergence","structured-knowledge","semantic-graphs","Hugo","Go","AI","architecture","craftsmanship","experimentation","learning-by-building","simplicity","ownership","builder-sovereignty","value"],"type":"entity"},"section":"Entities \u0026 technologies","text":"This first node brings his philosophical and practical qualities together in one personified identity. It is modeled from the Hugo Web blueprint and the clarified distinction between Hugo Web and the visitor\u0026rsquo;s Builder role.\nThe fields describe his identity, approach, and intended outcomes—not a literal human biography or a claim that every aspiration has already been achieved. His relationships connect the personified identity to the Builder role, publishing technology, AI collaboration, and the principles that shape the workshop. Follow the connections below to explore the wider model.\n","type":"entity","url":"/graph/entities/hugo-web/"},{"description":"The public publishing system that expresses Hugo Web’s philosophy through five pillars and a connected knowledge graph.","id":"hugo-web-site","kind":"system","name":"Hugo Web Site","node":{"description":"The public publishing system that expresses Hugo Web’s philosophy through five pillars and a connected knowledge graph.","id":"hugo-web-site","kind":"system","name":"Hugo Web Site","relationships":[{"predicate":"uses","target":"hugo"},{"predicate":"embodies","target":"knowledge-graph"},{"predicate":"depends-on","target":"code-generation-contract"}],"type":"entity"},"section":"Entities \u0026 technologies","text":"An expression of an identity This website is not Hugo Web himself. It is a publishing system through which his personified philosophy, practical guidance, and technical notebook become accessible.\nThe implemented direction Five pillars organize expressions: Design, Model, Build, Ship, and Developer’s Notebook. Every expression is a canonical graph node in its own content file. Entity and concept nodes provide the shared model beneath those expressions.\nThe site is static-first. Navigation and reading work without JavaScript; search and resource filtering enhance that baseline in the browser. Public exports contain public source material, not an access-controlled private knowledge base.\n","type":"entity","url":"/graph/entities/hugo-web-site/"},{"description":"The builder’s retained ability to set intent, judge evidence, choose actions, and accept responsibility.","id":"human-agency","kind":"principle","name":"Human agency","node":{"description":"The builder’s retained ability to set intent, judge evidence, choose actions, and accept responsibility.","id":"human-agency","kind":"principle","name":"Human agency","relationships":[{"predicate":"supports","target":"builder-sovereignty"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"What must remain human-directed Agency is not the number of options displayed by a tool. It is meaningful control over direction and consequences. A useful workflow makes decisions visible and leaves room to question the model, reject an output, and change the plan.\nAI-first does not mean AI-authoritative Delegate work deliberately, not responsibility by accident. Distinguish proposal, approval, implementation, review, and release. The assistant should make those boundaries easier to maintain, not obscure them behind automation.\n","type":"concept","url":"/graph/concepts/human-agency/"},{"description":"A model of identified things connected by explicit relationships under a shared vocabulary.","id":"knowledge-graph","kind":"modeling-pattern","name":"Knowledge graph","node":{"description":"A model of identified things connected by explicit relationships under a shared vocabulary.","id":"knowledge-graph","kind":"modeling-pattern","name":"Knowledge graph","relationships":[{"predicate":"uses","target":"semantic-node"},{"predicate":"uses","target":"ontology"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"More than linked pages The graph contains nodes and assertions between them. Hugo pages provide storage and presentation here, but graph membership comes from node metadata, not a path. An incoming connection is derived from a source’s outbound edge.\nUseful expressions The same graph can support navigation, indexes, machine exports, and grounded AI context. Those are implemented transformations, not capabilities that appear simply because content is written in YAML.\nKeep the graph small enough to understand. Evaluate its value through the questions it helps answer and the expressions it helps create.\n","type":"concept","url":"/graph/concepts/knowledge-graph/"},{"description":"The phase of making important distinctions, intrinsic facts, and relationships explicit.","id":"model","kind":"process","name":"Model","node":{"description":"The phase of making important distinctions, intrinsic facts, and relationships explicit.","id":"model","kind":"process","name":"Model","relationships":[{"predicate":"supports","target":"expression"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"A practical phase Choose the smallest useful ontology and identify things worth representing. Keep evidence separate from inference and stable identities separate from URLs. A model is useful when it clarifies decisions and supports expressions.\nAI can propose classifications and connections, but those proposals require review before becoming canonical assertions.\nExplore the pillar Open Model.\n","type":"concept","url":"/graph/concepts/model/"},{"description":"An open protocol for connecting AI applications to external tools, resources, and contextual capabilities.","id":"model-context-protocol","kind":"technology","name":"Model Context Protocol","node":{"description":"An open protocol for connecting AI applications to external tools, resources, and contextual capabilities.","id":"model-context-protocol","kind":"technology","name":"Model Context Protocol","relationships":[{"predicate":"supports","target":"ai-assistant"},{"predicate":"applies-to","target":"ports-and-adapters"}],"type":"entity"},"section":"Entities \u0026 technologies","text":"A protocol, not a trust guarantee MCP standardizes parts of the connection between an AI application and external capabilities. It does not decide whether a tool should be called, whether a result is true, or whether the caller is authorized to access particular data.\nA possible graph adapter A future adapter could expose approved graph lookups or source material as resources. That is an extension opportunity, not a feature implemented on this site. A public JSON export is not, by itself, an MCP server.\nKeep tool permissions narrow, validate inputs, review server trust, and separate reading from mutation. Never let external content silently expand the assistant’s authority.\nAuthoritative resource Model Context Protocol documentation\n","type":"entity","url":"/graph/entities/model-context-protocol/"},{"description":"An introduction to creating a minimal semantic node without unnecessary fields.","id":"model-one-meaningful-thing","kind":"tutorial","name":"Model one meaningful thing","node":{"description":"An introduction to creating a minimal semantic node without unnecessary fields.","id":"model-one-meaningful-thing","kind":"tutorial","name":"Model one meaningful thing","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"explains","target":"semantic-node"},{"predicate":"explains","target":"model"},{"predicate":"explains","target":"ontology"},{"predicate":"depends-on","target":"start-with-an-outcome"}],"type":"expression"},"section":"Semantic nodes","text":"A semantic node gives one meaningful thing a place to stand. It is not a demand to turn every noun into a record. Begin with something you will need to describe, reuse, or connect independently.\nDecide what the thing is A person, a role, and a project are different things—even when they share a name. Hugo Web is a particular personified identity. Builder is also a role a visitor can inhabit. Sharing a quality does not make two identities interchangeable.\nWrite one sentence describing your candidate. If it describes several independent things, narrow it before adding fields.\nStart with the minimum This fictional project illustrates the portable envelope:\nsemantic_node: id: example-project name: Example Project description: A fictional project for learning structured publishing. type: entity kind: project A graph accepting this example needs entity/project in its ontology. The current site does not register every example kind automatically.\nFor Hugo content, the same inner object lives under root front matter node:. Hugo templates read it through .Params.node. Publishing fields such as title and description remain outside the node.\nKeep identity stable Choose an ID once. Do not derive it from a directory or regenerate it when the display name changes. A URL answers “where can I read this?” The ID answers “which thing is this?” Those questions should not be coupled.\nAdd only useful enrichment Use properties for intrinsic facts. Use relationships for connections to other nodes. Add purpose or movement when those fields contribute meaningful context; do not invent intention for an object just to fill a form.\nMissing optional information is better than fabricated precision. A node with five trustworthy fields is more useful than a richly structured guess.\nTry it: model one thing in five fields. Ask another person whether they can distinguish it from related things using only that description. Revise the meaning before expanding the schema.\n","type":"expression","url":"/expressions/model/semantic-nodes/model-one-meaningful-thing/"},{"description":"A deployment platform that can build and deliver static sites and provide optional runtime capabilities.","id":"netlify","kind":"service","name":"Netlify","node":{"description":"A deployment platform that can build and deliver static sites and provide optional runtime capabilities.","id":"netlify","kind":"service","name":"Netlify","relationships":[{"predicate":"supports","target":"static-first"},{"predicate":"supports","target":"ship"}],"type":"entity"},"section":"Entities \u0026 technologies","text":"A deployment option Netlify can build a Hugo repository and distribute the resulting files. Deploy previews can make changes reviewable before a production release. Functions and other services are optional capabilities, not requirements for a Hugo site.\nQuestions before choosing it Check current plan limits, build costs, access requirements, cache behavior, and rollback support. Confirm the required Hugo version in the build environment. Verify the actual deployed 404 status, HTTPS, redirects, and security headers.\nThe workshop describes Netlify as an option. It does not claim an active Netlify account or deployment, a permanent free tier, or comparative performance results.\nAuthoritative resource Netlify documentation\n","type":"entity","url":"/graph/entities/netlify/"},{"description":"A practical application of established software-design principles to AI-assisted code generation.","id":"old-principles-new-leverage","kind":"guide","name":"Old principles. New leverage.","node":{"description":"A practical application of established software-design principles to AI-assisted code generation.","id":"old-principles-new-leverage","kind":"guide","name":"Old principles. New leverage.","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"explains","target":"solid"},{"predicate":"explains","target":"single-responsibility-principle"},{"predicate":"explains","target":"domain-driven-design"},{"predicate":"explains","target":"gang-of-four-patterns"},{"predicate":"explains","target":"adapter-pattern"},{"predicate":"explains","target":"strategy-pattern"},{"predicate":"depends-on","target":"code-generation-contract"}],"type":"expression"},"section":"Engineering principles, reconsidered","text":"AI changes the cost of producing code. It does not remove the cost of understanding, operating, or changing that code. Established engineering principles become useful review instruments—not decorations added to a prompt.\nSRP: ask who makes this change necessary The Single Responsibility Principle is more precise than “one function does one thing.” Consider our graph index and our visual cards. A rule about valid relationships should not require editing the card layout. A typography change should not change graph membership.\nAsk an assistant: which unrelated reasons to change are coupled here? Then inspect whether the proposed split reduces that coupling. Ten tiny files can be harder to maintain than one cohesive module.\nSOLID: review contracts, not class counts The rest of SOLID raises questions about extension, substitution, interfaces, and dependency direction. A provider adapter that returns similarly shaped JSON is not necessarily substitutable: privacy, failure behavior, and tool semantics can differ.\nAsk for behavioral tests before a refactor. Avoid generating an abstraction hierarchy just because a prompt mentions a principle.\nDDD: settle the language before generating the model Domain-Driven Design starts with meaningful language and boundaries. In this project, Hugo Web is the personified identity; Builder is an audience role; the website is a system. Those distinctions are real modeling work. A generated folder structure cannot substitute for them.\nAI can find inconsistent vocabulary and suggest candidate boundaries. The builder still decides which distinctions reflect the domain.\nPatterns: name the pressure that makes one useful An Adapter can keep Hugo storage conventions separate from portable node meaning. A Strategy can make actual algorithm variation explicit. Neither is a reason to invent future requirements.\nThe Gang of Four catalog is a vocabulary of recurring solutions and consequences. Ask the assistant to explain the simpler alternative and why it fails the actual requirement before adopting a pattern.\nA better review prompt Identify one concrete source of coupling in this change. Explain the requirement that makes it a problem. Compare the smallest fix with a pattern-based alternative. Propose tests that preserve the existing behavioral contract. Do not change code until the proposed scope is approved. The goal is not to make AI-generated code look sophisticated. It is to make the result easier for a builder to understand, trust appropriately, and change.\n","type":"expression","url":"/expressions/developers-notebook/engineering-principles/old-principles-new-leverage/"},{"description":"The small controlled vocabulary that governs node types, kinds, relationship predicates, and explicit contracts.","id":"ontology","kind":"modeling-pattern","name":"Ontology","node":{"description":"The small controlled vocabulary that governs node types, kinds, relationship predicates, and explicit contracts.","id":"ontology","kind":"modeling-pattern","name":"Ontology","relationships":[{"predicate":"supports","target":"knowledge-graph"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Language before machinery The ontology tells authors which distinctions the graph recognizes. A type gives a broad classification; a kind specializes it. Predicates name directional assertions. The actual vocabulary lives in site/data/ontology.yaml.\nGrow it for a reason Add a term when a real modeling need cannot be expressed clearly with the existing vocabulary. Do not create synonyms to make each article sound unique. Domain-specific property contracts may be added when they bring enforceable value.\nAn ontology makes language consistent. It does not make every recorded statement true.\n","type":"concept","url":"/graph/concepts/ontology/"},{"description":"Separate application policy from external mechanisms through explicit interaction boundaries.","id":"ports-and-adapters","kind":"architecture-style","name":"Ports and adapters","node":{"description":"Separate application policy from external mechanisms through explicit interaction boundaries.","id":"ports-and-adapters","kind":"architecture-style","name":"Ports and adapters","relationships":[{"predicate":"uses","target":"adapter-pattern"},{"predicate":"supports","target":"builder-sovereignty"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Keep the center independent Often called hexagonal architecture, ports and adapters keeps core behavior from being defined by a database, web framework, or provider API. Ports describe useful interactions; adapters connect particular technologies to them.\nUse only the boundary you need For Hugo Web, portable node meaning should survive a change of publishing engine. That does not require six layers of code. A small, documented storage mapping may be enough until the system has multiple implementations.\nAI can help identify accidental framework dependencies. It should not generate an elaborate hexagonal scaffold when ordinary files and one adapter suffice.\nOriginal source Alistair Cockburn: Hexagonal architecture\n","type":"concept","url":"/graph/concepts/ports-and-adapters/"},{"description":"A Hugo pattern for generating HTML and JSON from the same canonical node.","id":"publish-one-source-two-ways","kind":"tutorial","name":"Publish one source two ways","node":{"description":"A Hugo pattern for generating HTML and JSON from the same canonical node.","id":"publish-one-source-two-ways","kind":"tutorial","name":"Publish one source two ways","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"uses","target":"hugo"},{"predicate":"explains","target":"expression"},{"predicate":"explains","target":"build"},{"predicate":"depends-on","target":"model-one-meaningful-thing"}],"type":"expression"},"section":"Hugo in practice","text":"The first useful demonstration of a graph is not a force-directed visualization. It is changing a fact once and seeing every expression agree.\nSeparate content from its presentation An expression on this site lives in a Markdown file. Its root node contains its identity and relationships. The surrounding front matter controls publication. The Markdown body carries the article.\nThe page template can render a node name with:\n\u0026lt;h1\u0026gt;{{ .Params.node.name }}\u0026lt;/h1\u0026gt; Hugo\u0026rsquo;s HTML templates escape ordinary text. Do not bypass that protection with safeHTML for untrusted fields.\nAsk for another output Hugo supports multiple output formats. The site\u0026rsquo;s home configuration includes:\n[outputs] home = [\u0026#39;HTML\u0026#39;, \u0026#39;RSS\u0026#39;, \u0026#39;JSON\u0026#39;] The HTML home welcomes a reader. The JSON template builds records from the same node collection. No second authoring workflow is needed.\nIn a JSON template, serialize data rather than assembling JSON by hand:\n{{ dict \u0026#34;id\u0026#34; .Params.node.id \u0026#34;name\u0026#34; .Params.node.name | jsonify }} That snippet demonstrates serialization for one page; the home export iterates over the graph and includes resolved URLs and reading context.\nInspect the actual outputs Open this page\u0026rsquo;s Node data disclosure to inspect its source metadata. Then open the public graph export. Find publish-one-source-two-ways. Its ID and name originate from the same record you are reading now.\nProtect the publication boundary One source does not mean every field belongs in every output. Review the input and choose the export schema deliberately. Draft status is not access control. Do not place confidential knowledge in a public content repository.\nTry it: in a local copy, change an expression\u0026rsquo;s node name. Rebuild and inspect both its data disclosure and the JSON export. Verify the shared fact changed without editing either template.\n","type":"expression","url":"/expressions/build/hugo/publish-one-source-two-ways/"},{"description":"A release procedure covering validation, artifact review, deployment checks, and rollback.","id":"release-you-can-reverse","kind":"reference","name":"Ship a release you can reverse","node":{"description":"A release procedure covering validation, artifact review, deployment checks, and rollback.","id":"release-you-can-reverse","kind":"reference","name":"Ship a release you can reverse","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"explains","target":"ship"},{"predicate":"uses","target":"git"},{"predicate":"depends-on","target":"publish-one-source-two-ways"}],"type":"expression"},"section":"Deliberate delivery","text":"A build is an artifact. A release is an artifact placed into an environment where people depend on it. Treat those as different events.\nBefore building Review the content diff, including machine-readable outputs. Confirm that source files contain no private data or credentials. Record the commit and the exact Hugo version. Validate node identities, vocabulary, and relationships. Confirm the production base URL and included content selection. Do not enable draft, future, or expired content indiscriminately in a production build. A published expression must not point to an excluded graph target.\nInspect the artifact For a standard Hugo build:\nhugo --gc --minify --panicOnWarning --baseURL https://your-domain.example/ Replace the example domain. Check the generated HTML, JSON, RSS, sitemap, and 404 page—not just the terminal exit code. Follow internal links from a local preview of the built artifact. Verify assets under the intended deployment path.\nFor this repository, the documented scripts/check.py command adds graph and output checks before release.\nInspect the deployed system Host behavior cannot be proven by a local Hugo build. Verify HTTPS, redirects, cache headers, the actual 404 status, robots behavior, and canonical URLs on the chosen host. Do not claim those checks passed before there is a deployment.\nKeep the last known-good artifact or deployment identifier. The recovery path should not depend on reproducing an old environment during an incident.\nMake rollback ordinary A release note should identify the commit, artifact, changed behavior, and how to restore the previous release. Prefer a reversible deployment mechanism. For source changes, git revert creates an explicit undo without rewriting history; understand the affected commit before running it.\nTry it: write the rollback step before the deploy step. If it is vague, the release process is not ready yet.\n","type":"expression","url":"/expressions/ship/deployment/a-release-you-can-reverse/"},{"description":"Supply retrieved source material as context for generation, then evaluate the result against that evidence.","id":"retrieval-augmented-generation","kind":"practice","name":"Retrieval-augmented generation","node":{"description":"Supply retrieved source material as context for generation, then evaluate the result against that evidence.","id":"retrieval-augmented-generation","kind":"practice","name":"Retrieval-augmented generation","relationships":[{"predicate":"uses","target":"knowledge-graph"},{"predicate":"supports","target":"ai-assistant"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Grounding is a process Retrieve relevant material, select a bounded context, generate an answer, and verify important claims against the sources. A graph can help select a relevant neighborhood. It does not eliminate the need to evaluate retrieval and generation.\nAvoid borrowed certainty A retrieved source may be stale, mistaken, or adversarial. Presence in context does not prove a generated statement follows from it. Track source relevance, unsupported claims, privacy boundaries, and prompt-injection risks.\nThis site exports public graph data that could support a future retrieval system. It does not currently operate a vector database or hosted answering service.\nResearch source Lewis et al.: Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks\n","type":"concept","url":"/graph/concepts/retrieval-augmented-generation/"},{"description":"A stable, structured representation of one meaningful thing in the modeled world.","id":"semantic-node","kind":"modeling-pattern","name":"Semantic node","node":{"description":"A stable, structured representation of one meaningful thing in the modeled world.","id":"semantic-node","kind":"modeling-pattern","name":"Semantic node","relationships":[{"predicate":"depends-on","target":"ontology"},{"predicate":"supports","target":"knowledge-graph"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"The common envelope A node requires id, name, description, type, and kind. Optional properties, movement, boundaries, invariants, and relationships add useful context. Do not fill optional fields with invented precision.\nIdentity outlives location Root node: front matter is this site’s storage convention. Its ID does not depend on its filename, folder, or URL. A concept page and an expression page can therefore participate in the same graph without sharing a directory.\nThe node is a model, not evidence that the modeled thing exists or behaves as claimed. Validate its structure and review its meaning separately.\n","type":"concept","url":"/graph/concepts/semantic-node/"},{"description":"The phase of placing approved expressions into reality and learning from their use.","id":"ship","kind":"process","name":"Ship","node":{"description":"The phase of placing approved expressions into reality and learning from their use.","id":"ship","kind":"process","name":"Ship","relationships":[{"predicate":"supports","target":"expression"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"A practical phase Review the artifact, publish through an approved release process, and preserve a rollback path. Hosting behavior, privacy, and operational limits are part of the system even when the application is static.\nThe outcome of shipping is evidence, not automatic success. Carry observations back into the model and distinguish them from interpretations.\nExplore the pillar Open Ship.\n","type":"concept","url":"/graph/concepts/ship/"},{"description":"Prefer the least complexity that genuinely satisfies the whole system’s requirements.","id":"simplest-capable-architecture","kind":"principle","name":"Simplest-capable architecture","node":{"description":"Prefer the least complexity that genuinely satisfies the whole system’s requirements.","id":"simplest-capable-architecture","kind":"principle","name":"Simplest-capable architecture","relationships":[{"predicate":"supports","target":"builder-sovereignty"},{"predicate":"applies-to","target":"build"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Simplicity is contextual A static site is simple for public publishing. A database may be simpler for concurrent transactional updates. Judge the whole system: maintenance, security, recovery, cost, and the knowledge required to operate it.\nAI makes this more important Cheap code generation does not make dependencies or operational state free. Ask what each layer contributes, what owns its state, and how it can be removed. Prefer explicit, understandable mechanisms over speculative flexibility.\n","type":"concept","url":"/graph/concepts/simplest-capable-architecture/"},{"description":"An architectural decision method that weighs complexity against concrete requirements.","id":"simplest-capable-system","kind":"guide","name":"Choose the simplest capable system","node":{"description":"An architectural decision method that weighs complexity against concrete requirements.","id":"simplest-capable-system","kind":"guide","name":"Choose the simplest capable system","relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"explains","target":"simplest-capable-architecture"},{"predicate":"explains","target":"static-first"},{"predicate":"depends-on","target":"start-with-an-outcome"}],"type":"expression"},"section":"Architectural judgment","text":"Simple does not mean small at any cost. It means understandable enough to change, and capable enough to do the job. A static site is a strong choice for publishing; it is not a substitute for a transactional system merely because it is inexpensive.\nBegin with what can be known in advance Ask when each piece of information changes:\nInformation Reasonable starting point An article or product explanation Build-time content A public index of articles Generated JSON A visitor\u0026rsquo;s search query Browser-side computation A private account balance Authenticated runtime service Move computation to build time only when the information and freshness requirements permit it. Static-first is a bias, not a prohibition on servers.\nMake each layer answer a question Before adding a service, record:\nWhich requirement cannot be met without it? What state will it own? What happens when it is unavailable? Who updates it, and how will we remove it? A dependency can save effort. It can also move effort into upgrades, monitoring, security, and operational knowledge. Include those costs in the decision.\nCompare whole systems A zero-cost hosting plan is not automatically the cheapest architecture. Include build time, authoring friction, incident recovery, and human maintenance. Likewise, a familiar database may be simpler for your team than an elaborate file workaround.\nChoose the smallest design that satisfies the actual constraints. Record what would make you change your mind: update frequency, graph size, response time, or an access-control requirement.\nLeave a decision record Decision: Requirement it serves: Alternatives considered: Accepted costs: Evidence that would trigger a revision: Try it: pick one layer in your proposed stack. Remove it on paper. Describe exactly what stops working. If nothing important stops working, defer the layer.\n","type":"expression","url":"/expressions/design/architecture/choose-the-simplest-capable-system/"},{"description":"A module should have one coherent reason to change, understood in relation to the actors or policies it serves.","id":"single-responsibility-principle","kind":"principle","name":"Single Responsibility Principle","node":{"description":"A module should have one coherent reason to change, understood in relation to the actors or policies it serves.","id":"single-responsibility-principle","kind":"principle","name":"Single Responsibility Principle","relationships":[{"predicate":"applies-to","target":"code-generation-contract"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"More precise than “do one thing” SRP is not a command to put every line in a separate function. It asks whether unrelated change pressures have been coupled. A graph index and a visual card layout evolve for different reasons; separating them makes those changes easier to reason about.\nIn AI-generated code Ask which requirement or actor would cause each module to change. Keep graph validation separate from rendering and deployment policy separate from content. Then verify that the separation removes coupling rather than merely multiplying files.\nSource Robert C. Martin on SRP\n","type":"concept","url":"/graph/concepts/single-responsibility-principle/"},{"description":"Five object-oriented design principles concerned with responsibility, extensibility, substitutability, interface focus, and dependency direction.","id":"solid","kind":"principle","name":"SOLID","node":{"description":"Five object-oriented design principles concerned with responsibility, extensibility, substitutability, interface focus, and dependency direction.","id":"solid","kind":"principle","name":"SOLID","relationships":[{"predicate":"depends-on","target":"single-responsibility-principle"},{"predicate":"supports","target":"simplest-capable-architecture"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"The five principles S — Single Responsibility: group work that changes for the same reason. O — Open/Closed: support useful extension without destabilizing established behavior. L — Liskov Substitution: replacements must preserve the behavioral contract expected by clients. I — Interface Segregation: do not force clients to depend on capabilities they do not use. D — Dependency Inversion: high-level policy depends on abstractions rather than low-level details. Applying them with AI Use the principles as review questions, not instructions to generate a class hierarchy. Ask an assistant to identify change reasons, contract violations, and unnecessary coupling. Reject abstraction added solely to make the code look architectural. A Hugo partial is not an object, so apply the underlying judgment rather than pretending every object-oriented rule maps literally to a template.\nSource Robert C. Martin’s design-principles paper\n","type":"concept","url":"/graph/concepts/solid/"},{"description":"A practical method for stating intent before selecting implementation tools.","id":"start-with-an-outcome","kind":"guide","name":"Start with an outcome, not a stack","node":{"description":"A practical method for stating intent before selecting implementation tools.","id":"start-with-an-outcome","kind":"guide","name":"Start with an outcome, not a stack","properties":{"level":"starting-point"},"relationships":[{"predicate":"authored-by","target":"hugo-web"},{"predicate":"explains","target":"design"},{"predicate":"depends-on","target":"human-agency"}],"type":"expression"},"section":"Intent \u0026 outcomes","text":"A framework is an answer. Before choosing one, make sure you have a question. The first useful artifact is often a paragraph, not a repository.\nWrite the change you want Use this sentence:\nFor this person, make this activity easier, so this outcome becomes possible.\nFor a workshop site, that might be: “For a builder learning Hugo, make a working example easy to inspect, so they can adapt it without guessing how it works.” Notice what is absent: a CMS, a database, an AI agent, and a hosting provider. Those choices can wait.\nGive the outcome a boundary Write down three constraints before implementation:\nOwnership: what must the builder be able to take away? Effort: what can they reasonably maintain? Risk: what must the system never expose or destroy? Constraints are not the enemy of creativity. They make architectural choices comparable. “The content must remain readable without our application” is more useful than “the system should be future-proof.”\nChoose the smallest observable result A result should be something you can inspect. For this example: a reader can find an article, run its example, and explain the important tradeoff.\nDo not substitute an activity metric for that outcome. Ten published articles prove that ten articles were published, not that anyone understood them.\nMake a one-page brief Person: Activity: Desired change: Constraints: Smallest useful demonstration: Evidence that would change our approach: Fill it in with plain language. If an answer is unknown, say so. Keep the brief beside the work, and revise it when evidence changes your understanding.\nTry it: write the brief for one thing you want to build. Remove every product or framework name. If the intention disappears, you may have started with a tool instead of a problem.\n","type":"expression","url":"/expressions/design/intent/start-with-an-outcome/"},{"description":"Precompute publishable information when freshness and interaction requirements permit, adding runtime work only where it creates value.","id":"static-first","kind":"architecture-style","name":"Static-first publishing","node":{"description":"Precompute publishable information when freshness and interaction requirements permit, adding runtime work only where it creates value.","id":"static-first","kind":"architecture-style","name":"Static-first publishing","relationships":[{"predicate":"extends","target":"simplest-capable-architecture"},{"predicate":"applies-to","target":"hugo-web-site"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Move work to the appropriate time Generate articles, navigation, feeds, and public graph indexes at build time. Run a small local search in the browser when the index size permits it. Use an authenticated service for genuinely private or transactional operations.\nNot a universal answer Build duration, update frequency, and data volume matter. Measure the actual workload before extending a file-based architecture to millions of records. An AI-generated static interface does not replace the backend requirements of payments, authentication, or shared mutable state.\n","type":"concept","url":"/graph/concepts/static-first/"},{"description":"Encapsulate interchangeable algorithms behind a shared behavioral contract when variation is a real requirement.","id":"strategy-pattern","kind":"design-pattern","name":"Strategy pattern","node":{"description":"Encapsulate interchangeable algorithms behind a shared behavioral contract when variation is a real requirement.","id":"strategy-pattern","kind":"design-pattern","name":"Strategy pattern","relationships":[{"predicate":"extends","target":"gang-of-four-patterns"},{"predicate":"applies-to","target":"frontier-models"}],"type":"concept"},"section":"Concepts \u0026 principles","text":"Variation with a reason A system may need different ranking or generation strategies. If callers can rely on the same contract, selecting an algorithm need not change their behavior. One simple algorithm does not require a strategy framework in anticipation of others.\nAI-first interpretation Model providers or retrieval methods can be candidates for strategies only when their guarantees are sufficiently compatible. Latency, privacy, tool support, output limits, and failure modes are part of the contract, not incidental details.\nAsk an assistant to define substitutability tests before implementing a provider switch. A shared method name alone does not make two models interchangeable.\n","type":"concept","url":"/graph/concepts/strategy-pattern/"}]}