Note

    How This Site Works Intake Dossier

    How This Site Works is an onboarding project for Hyphenomenon itself: it explains how a new project can start with one operator prompt that names the Hyphenomenon intake skill, the local repo path, source paths, a project title, and route context.

    Project Intake - How This Site Works

    Project Name: How This Site Works
    Repository: https://github.com/maggielerman/hyphenomenon
    Live URL(s): https://hyphenomenon.com
    Source Repo Path: /Users/maggielerman/Github/hyphenomenon

    1) Executive Summary

    How This Site Works is an onboarding project for Hyphenomenon itself: it explains how a new project can start with one operator prompt that names the Hyphenomenon intake skill, the local repo path, source paths, a project title, and route context.

    That prompt is the important product behavior. The workflow takes care of the repetitive setup: scaffold the dossier, gather screenshots, extract source artifacts, build project-page and workflow packets, dry-run the database write, and create a local project record for review. The public page should make that easy loop visible while still showing the human editorial gate that decides what becomes public proof.

    2) Project Type and Domain

    • Project type: Initiative
    • Domains: builder, designer
    • Primary audience: public readers, prospective collaborators, and reviewers who need an orientation layer before exploring the map or project catalog.
    • Operator audience: the single editor/admin maintaining the living archive and deciding which generated traces become durable public material.

    3) Repository and Live URLs

    4) Product/User Journey Summary

    A reader first encounters the homepage premise: Diaries of an AI optimist, living projects, and a human-in-the-loop archive. The How This Site Works project gives that premise a deeper canonical page by showing the operating loop behind the site.

    The expected journey is:

    • land on the homepage;
    • follow See how this site works or the top-nav How it works link;
    • see that a new project begins with a simple prompt to run the intake skill with local paths and route context;
    • inspect the generated project page, workflows, supporting notes, screenshots, and Explore membership as reviewable artifacts;
    • continue into Projects, Notes, Workflows, Chats, or the Explore map with the archive model already established;
    • understand that the site is maintained by a mix of automation-assisted capture and human editorial selection, not by either manual publishing alone or unreviewed automation.

    The project should frame the site as a public proof system, not as a static portfolio and not as a fully automatic content machine.

    5) Architecture and Stack Summary

    Hyphenomenon is a Next.js App Router application with public editorial routes and admin-gated operator routes. The public runtime reads projects, notes, chats, workflows, and graph data from the canonical knowledge backbone through server-side catalog loaders.

    The project detail route is /projects/[slug]. It resolves DB-backed project records through getProjectBySlug, then renders narrative sections, product surfaces, workflows, screenshots, outbound links, and supporting artifacts. The Explore map reads the same public knowledge graph and can scope to a project by node.meta.slug.

    The current implementation uses:

    • Next.js and React for route rendering and UI components;
    • Neon/Postgres-backed kb_* knowledge tables for canonical public content;
    • Vercel Blob-backed media where screenshots or images are uploaded;
    • docs-first governance in DOCS/;
    • DB-first intake scripts for importing project dossiers into the knowledge backbone.

    6) Key Workflows and Operational Flows

    • Public orientation: homepage hero and How this site works section explain the living archive loop.
    • Project exploration: /projects lists the public project catalog; /projects/[slug] provides the canonical case-study page.
    • Graph exploration: /explore and /explore?project=... let readers move through project relationships.
    • Prompt-to-project intake workflow: the operator asks Codex to run ML-hyphenomenon-project-intake, provides a project title, local repo path, source paths, live URL, and canonical route, then the workflow scaffolds the dossier and evidence package.
    • Artifact generation workflow: screenshots are captured, source artifacts are hydrated into note candidates, project-page packets and workflow packets are authored, and validation/dry-runs report exactly what would change.
    • Editorial workflow: automation helps collect and structure evidence, but human review decides what becomes public, rewritten, kept local, appended as evidence, or excluded.
    • Promotion workflow: local review comes first; production apply remains a separate explicit decision with a fresh scoped dry-run.

    7) AI Context: Prompts, Chats, Agent Workflows

    The repo contains explicit AI/agent governance in AGENTS.md, project-level checkpoint rules in DOCS/PROJECTS/, and prompt-driven intake scripts under scripts/intake/project/prompts/.

    The important public-facing AI context is the handoff: the operator can say, in plain language, "run the Hyphenomenon intake skill for this repo," include the local paths and route information, and have Codex assemble the first project record. That is the thing this project should prove.

    This intake should not import AGENTS.md, changelog entries, roadmap entries, or prompt files as standalone public notes. Those files are source evidence for the project page, not public artifacts by default. The public artifacts should be the intake workflow, dossier/packet evidence, generated project route, supporting notes, and local-review boundary.

    8) Supporting Docs and External Resources

    • Documentation index - canonical documentation map and public/admin route posture.
    • Solution implementation - system implementation overview for knowledge backbone, admin, and visualization behavior.
    • Project feature guide - project route contract and detail-page layout expectations.
    • Workflow feature guide - public workflow content model.
    • Database operations - production/local database safety policy.
    • scripts/intake/project/README.md - DB-first intake runbook and apply/dry-run behavior.
    • DOCS/intake/how-this-site-works-project-page-packet.json - structured project-page proof packet for the current P3 pass.
    • DOCS/intake/how-this-site-works-workflow-packet.json - workflow packet showing the prompt-to-project and local-review loops.

    Hydration Source Artifacts

    Artifact (relative repo path)Canonical URLTypeWhy hydrate this into note body
    ../../DOCS/solution-implementation.mdGitHubmarkdownDurable system overview for how the public archive, knowledge backbone, admin, and visualization fit together.
    ../../DOCS/features/projects.mdGitHubmarkdownSource-backed project-page contract that explains how project supernodes become public proof surfaces.
    ../../DOCS/features/workflows.mdGitHubmarkdownDurable workflow model for explaining how operational playbooks and automation traces are represented.
    ../../DOCS/database/operations-and-maintenance.mdGitHubmarkdownSafety and source-of-truth policy for local versus production knowledge data.
    ../../public/home-explore-map-still.svgGitHubimageVisual evidence of the public map metaphor used in the homepage hero.

    9) Screenshot Gallery (with relative links + captions)

    1. Home/Landing - Homepage entry point showing the AI-optimist diary framing and current archive explanation.
    2. Primary Workflow - Projects index showing how public project records are presented as the main catalog.
    3. Key Feature - Explore map showing connected project, note, workflow, and chat relationships.
    4. Admin/Settings Equivalent - Workflow index showing the public operational-playbook surface.
    5. Supporting Evidence - Notes index showing how supporting evidence can live alongside projects and workflows.

    10) Candidate Import Nodes and Relationships

    • Project supernode:
      • id: project-how-this-site-works
      • slug: how-this-site-works
      • title: How this site works
      • type: initiative
    • Durable supporting notes:
      • How the archive is implemented from DOCS/solution-implementation.md
      • Projects as proof surfaces from DOCS/features/projects.md
      • Workflows as public operating evidence from DOCS/features/workflows.md
      • Knowledge data safety model from DOCS/database/operations-and-maintenance.md
    • Candidate workflow:
      • Prompt-to-project intake workflow, showing the one-prompt handoff, scaffold, capture, packet creation, hydration, dry-run, review, local apply, and render.
      • Local review and promotion loop, showing how the generated output stays editable and how production apply stays separate.
    • Relationships:
      • Project related to the durable notes and workflow above.
      • Project scoped in Explore through meta.slug and meta.node_ids.
    • Explicit exclusions:
      • Do not import roadmap, changelog, AGENTS.md, prompt files, route maps, or the intake dossier itself as public notes.
      • Do not create screenshot-gallery notes. Screenshots belong on project metadata.

    11) Risks, Gaps, and Unknowns

    • Unknown: whether this project should eventually replace the homepage How this site works section or coexist with it long-term.
    • Risk: importing repository governance files as public notes would repeat the Family Shapes intake-output failure mode.
    • Risk: applying to a production database would violate the 1052 plan. This intake is local-only until separately approved.
    • No .docx or .pdf hydration source is needed for this intake; the durable source material is Markdown and runtime screenshots.

    12) Handoff Checklist for Hyphenomenon Import

    • Confirm dossier sections complete and source-backed
    • Confirm screenshot files exist in docs/intake/screenshots
    • Confirm screenshot links render from docs/intake/ML-hyphenomenon-project-intake.md
    • Confirm Unknowns are explicit
    • Run source artifact extraction
    • Validate dossier and hydration payload
    • Run dry-run import and inspect counts/hash
    • Apply only to local/non-production DB if dry-run is scoped correctly