diff --git a/AGENTS.md b/AGENTS.md index 8c2f91b..2a59283 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,13 @@ Do not merge or publish this transition without direct owner authorization. Docu The current v2 proposal inserts Chapter 05, *Engineering Data: From Measurements to Decisions*, and shifts later v2 briefs to 06–13. Keep the existing original twelve published lessons and their canonical calculations unchanged. The shared at-a-glance summary uses data from site/src/data/chapter-glances.ts; do not confuse these summaries with evidence of feature completion. The new v2 reader-preview route is separate from original lesson 05. Synthetic power and mounting fields are teaching assumptions, never physically verified measurements. +## Chapter 1 reader pilot — owner-authorized 15 November 2026 + +The owner approved applying the revised site direction and terminology to Chapter 1 as a local pilot before other chapters. Read project/SITE-DIRECTION.md as the current editorial direction. Implement the complete preview at learn/v2/01-new-engineering-paradigm/ with its own dark reading layout; preserve the original Chapter 1 route, fragments and V0 lab. This authorization supersedes the earlier Home/Learn-only scope for this single pilot. + +The pilot uses a concrete opening, explanatory graphics and optional interactions without the universal six-tile summary. Other chapter layouts stay unchanged pending review. Register complete reader previews separately in site/src/data/chapters.ts and label their status in Home/Learn. Keep conceptual situations distinct from model executions or recorded agent runs. + +After checking in the reviewed work, the owner explicitly requested publication on 15 November 2026. That authorization covers the revised front page, Learn navigation and the v2 Chapter 1 reader preview in this branch. Keep the reader-preview label because editorial review continues. It does not authorize migration of other chapters, publication of the separate v3 manuscripts or changes to the engineering engine. ## V3 approved editorial manuscripts — agents must read first diff --git a/SITE_SPEC.md b/SITE_SPEC.md index 0f7d83b..8397891 100644 --- a/SITE_SPEC.md +++ b/SITE_SPEC.md @@ -2,6 +2,8 @@ **Status:** Proposed baseline · **Version:** 0.1 · **Date:** 2026-10-16 +**Historical release specification.** For the current editorial direction and the authorized Chapter 1 reader pilot, use [project/SITE-DIRECTION.md](project/SITE-DIRECTION.md). The original curriculum and visual direction below document the first release; the V0 technical contracts remain in force. + ## 1. Purpose Executable Engineering Lab is a standalone, practical learning site showing how engineering intent can become structured, connected, executable, and verifiable engineering knowledge. It builds conceptually on [Document-as-Code Lab](https://and-gu.github.io/document-as-code-lab/) without assuming readers completed it. diff --git a/chapters/01-the-new-engineering-paradigm.md b/chapters/01-the-new-engineering-paradigm.md index 8d26c27..116e60c 100644 --- a/chapters/01-the-new-engineering-paradigm.md +++ b/chapters/01-the-new-engineering-paradigm.md @@ -1,15 +1,26 @@ # Chapter 01 — The New Engineering Paradigm -Status: v2 implementation brief (proposed) +Status: owner-authorized reader pilot, 15 November 2026; local preview before wider adoption or publication Part: I — Engineering in the Age of AI ## The one question -Why does faster AI execution require a different engineering environment? +How do software-driven workflows and AI agents change the way we develop systems? ## What the reader must gain -Explain how digital threads and agents reinforce each other; identify the production-versus-review bottleneck; recognize discipline-specific cadences. +Distinguish systems engineering, executable engineering, software-driven workflows, AI assistance and agentic work. Explain how the product system and engineering environment develop together; distinguish AI used in engineering from AI in products; recognize discipline-specific feedback and release cadences. + +## Terminology introduced here +Use the shared definitions and introduction sequence in [the curriculum map](../project/CURRICULUM-MAP.md#terminology-and-introduction-sequence). + +- Establish systems engineering as the scope across software, electronics, physical design, people and use. +- Introduce executable engineering and software-driven workflows through a model, experiment or repeatable check in the opening situation. +- Explain an AI agent as carrying out a defined task with tools, inspecting results and adapting the next step. Introduce agentic engineering as this way of working within the broader category of AI-assisted engineering. +- Distinguish AI used to develop the product from AI contributing to the product's behavior. Neither product AI nor all automation is necessarily agentic. +- Reserve large language model (LLM) detail for Chapter 07 unless a specific example requires it earlier; spell out the term on first use. + +Introduce “We build the machine that builds the machine” through the product system and the engineering environment. Make the people, methods, models, tools and workflows in the second system explicit. ## Opening engineering situation -An operations team proposes a distributed monitoring capability. Compare a document/tool-silo workflow with connected information and bounded agent assistance. +An operations team wants to detect developing equipment faults. The intended use, sensor mounting, signal interpretation and operator response are still open questions. Explain how product questions shape the engineering environment through a clearly conceptual monitoring example. ## Narrative arc 1. Start with a concrete decision or unexpected constraint, not a definition. @@ -20,7 +31,13 @@ An operations team proposes a distributed monitoring capability. Compare a docum 6. Connect the decision to the next engineering question. ## Primary learning experience -Side-by-side interactive lifecycle maps with visible handoff delays and review points; no fabricated productivity numbers. +A two-lane visual connects the product system to the engineering environment through questions and findings. Expand three illustrative findings—mounting behavior, a classifier's missed condition and changed firmware sampling—to inspect the next product work and the next improvement to the engineering environment. A separate comparison distinguishes AI in engineering from AI in products; a cadence schematic shows different feedback loops without invented durations. A reasoning check asks what passing software checks establish about physical mounting. + +## Reader layout and route + +The complete pilot is at `/learn/v2/01-new-engineering-paradigm/`, with a dark sans-serif reading layout, grouped course navigation, compact chapter information and contextual deeper links. Preserve `/learn/01-engineering-intent/` and all original fragments. Chapter 2's bridge points to the planned learning map until a complete reader exists. Home and Learn link to the pilot as a preview. + +The pilot deliberately omits the six-tile At a Glance panel under the updated [site direction](../project/SITE-DIRECTION.md). Other chapter content and layouts await review. ## Reuse and migration from v1 Existing homepage framing and Ch 1 intent explanation; retain Ch 1 V0 lab as legacy/related resource. diff --git a/chapters/07-directing-ai-engineering-agents.md b/chapters/07-directing-ai-engineering-agents.md index 06b8f74..02c27b1 100644 --- a/chapters/07-directing-ai-engineering-agents.md +++ b/chapters/07-directing-ai-engineering-agents.md @@ -8,6 +8,9 @@ What can an agent do on our behalf, and how do we know what actually happened? ## What the reader must gain Set task objective, sources, permissions, tool boundaries, stop conditions and review deliverable; distinguish agent narration from trace and evidence. +## Terminology developed here +Build on the [Chapter 01 vocabulary](../project/CURRICULUM-MAP.md#terminology-and-introduction-sequence). Explain large language model (LLM) at first use, separating the underlying model from the agent's tools, context and execution loop. Contrast interactive AI assistance, predefined automation and an agent selecting and adapting steps toward a delegated objective. Use “agentic engineering” for this working practice; do not use it as a synonym for all AI in engineering or AI in products. + ## Opening engineering situation Agent investigates a bounded DMS proposal, reads approved sources, modifies an isolated fixture, runs checks and opens a reviewable diff. diff --git a/docs/design/chapter-style-guide.fragment.html b/docs/design/chapter-style-guide.fragment.html new file mode 100644 index 0000000..0aa5766 --- /dev/null +++ b/docs/design/chapter-style-guide.fragment.html @@ -0,0 +1,242 @@ + +
+
Executable Engineering LabCHAPTER STYLE GUIDE · PROPOSAL
+
+ + + + +
+ +
+
+ +
+
Course navigation · Chapter 01

Part I · Why and what next
01 The New Engineering Paradigm
02 Planning Under Uncertainty

+

PART I / CHAPTER 01

+

The New Engineering Paradigm

+

How do we turn faster modeling, agentic work and frequent releases into useful progress across the whole system?

+ +

An operations team wants to detect developing equipment faults. The sensor, its mounting and the operator’s response are still open questions. Each experiment develops our understanding of the product—and the means of investigating it.

+
+
PRODUCT SYSTEM

What should we build?

Behavior · interfaces · use

+
Questions →← Findings
+
ENGINEERING ENVIRONMENT

How can we find out?

People · models · tools

+

A product question shapes an experiment. Its findings guide both the design and the next engineering capability.

+
+
CONCRETE SITUATIONEARLY VISUALOPTIONAL DEPTH
+
+
+
+ + + + + + +
+ + diff --git a/docs/design/chapter-style-guide.html b/docs/design/chapter-style-guide.html new file mode 100644 index 0000000..285d730 --- /dev/null +++ b/docs/design/chapter-style-guide.html @@ -0,0 +1,3036 @@ + + + + + + + +Chapter Style Guide + + + + + + + + + diff --git a/docs/v2/CHAPTER-01-PILOT-REVIEW.md b/docs/v2/CHAPTER-01-PILOT-REVIEW.md new file mode 100644 index 0000000..4d9ce8c --- /dev/null +++ b/docs/v2/CHAPTER-01-PILOT-REVIEW.md @@ -0,0 +1,44 @@ +# Chapter 1 reader pilot — review record + +Prepared 15 November 2026 after the owner authorized the revised site direction and Chapter 1 pilot. The initial local preview was followed by explicit publication authorization, recorded below. Adoption across other chapters remains pending. + +## Preview + +- Chapter: `http://127.0.0.1:4327/executable-engineering-lab/learn/v2/01-new-engineering-paradigm/` +- Front page: `http://127.0.0.1:4327/executable-engineering-lab/` +- Direction: [project/SITE-DIRECTION.md](../../project/SITE-DIRECTION.md) +- Owner-facing original direction: [site direction and front-page brief](https://chatgpt.com/space/page_52692f0497f48191bc7e6b4a254696a0) + +The existing local Astro preview process serves the rebuilt `dist/`. Both Home and Learn link to the completed pilot, explicitly labeled as a reader preview. The pilot registry is separate from published v2 articles. + +## What to review + +The opening starts with an uncertain equipment-monitoring need. A two-lane graphic connects product behavior with the people, models, tools and methods used to investigate it. Three expandable illustrative findings show changes to both kinds of work. The narrative introduces the agreed vocabulary, distinguishes engineering AI from product AI, and explains speed through different feedback cycles. A reasoning check asks what software checks establish about a physical mounting question. + +The dark reader has grouped course navigation, a current chapter indicator, optional chapter information and a collapsed course menu on narrow screens. It omits the six-tile overview. The next-chapter link leads to the planned learning map because Chapter 2 is not yet implemented in the new course. + +These situations are conceptual explanations, not simulated measurements or recorded agent runs. The original Chapter 1 and the other original lesson routes remain intact. No canonical model, source schema, evidence calculation or agent execution capability was changed. + +## Observed verification + +- `npm run check`: zero Astro errors, warnings or hints; six test files and all 86 tests passed; strict source validation passed; 18 static routes built. +- After a small diagram-width correction, `npm run build` passed again. No calculation or interaction code changed after the full check. +- `npm run evidence`: canonical result remains 38.52%, engineering FAIL against the 50% teaching criterion. This is the intended model result, not a build failure. +- Static link audit: 69 internal links from Home, Learn and the pilot resolve to existing build outputs and valid fragments; no duplicate IDs on those pages. +- Browser: the pilot returns HTTP 200; desktop 1738px, tablet 768px, and narrow 390px/320px layouts were inspected. No horizontal document overflow was observed. +- Keyboard: skip link focuses `main`; findings expand with Enter; mobile course navigation opens and closes with Enter; the reasoning-check disclosure opens correctly. +- Navigation: Chapter 2 bridge reaches Learn's Part I; the pilot link there returns to Chapter 1. Home's pilot link was independently checked by the requested front-page sub-agent. +- No browser errors or warnings were reported for the pilot. A desktop screenshot was saved at `/Users/andersgustafsson/Documents/Codex/2026-11-11/r/outputs/chapter-01-pilot-desktop.jpg`. +- The front-page sub-agent checked desktop, tablet, mobile, skip navigation and the lesson directory, and captured fresh desktop/mobile screenshots. Its only additional Home change was the labeled Chapter 1 preview row. + +The owner-facing direction and revised-brief Pages were saved and their changed content read back successfully. At the initial preview handoff, no commit, push, merge or publication had been performed. + +## Session checkpoint + +The owner subsequently requested checking in all session changes. This checkpoint includes the front page, Chapter 1 pilot, direction and terminology updates, and the [chapter style-guide proposal](../../project/CHAPTER-STYLE-GUIDE.md). Chapter 1 remains the implemented reading reference; proposed typography refinements are documented separately. Checking in the feature branch does not approve publication or migration of the other chapters. + +Before committing, `npm run check` passed again: 50 Astro files without diagnostics, all 86 tests, source validation and all 18 static routes. `npm run evidence` completed with the unchanged 38.52% teaching-model result. The style-guide specimen was preserved as editable source and a standalone browser export under `docs/design/`, outside the deployed site. + +## Publication scope + +The owner subsequently requested publication on 15 November 2026. The release includes the revised front page, Learn navigation and the complete v2 Chapter 1 reader preview. Its preview label remains because editorial review continues. The separate v3 manuscripts and research archive stay outside the site. Publication success must be established from the GitHub Pages workflow and live routes; this authorization record alone is not a deployment result. diff --git a/project/CHAPTER-STYLE-GUIDE.md b/project/CHAPTER-STYLE-GUIDE.md new file mode 100644 index 0000000..257b31d --- /dev/null +++ b/project/CHAPTER-STYLE-GUIDE.md @@ -0,0 +1,95 @@ +# Chapter style guide — working proposal + +Recorded 15 November 2026. The front page establishes the visual identity; the Chapter 1 reader pilot is the main reference for chapter composition and layout. The owner liked parts of the pilot and identified further review work. Preserve that reference while developing the wider information site. + +This document records the proposal and the differences discussed in review. It does not mean every proposed typography adjustment has been applied or that the other chapters have been migrated. + +## References and authority + +- [Site direction](SITE-DIRECTION.md): audience, purpose and engineering argument. +- [Editorial guide](EDITORIAL-GUIDE.md): voice and chapter composition. +- [Curriculum map](CURRICULUM-MAP.md#terminology-and-introduction-sequence): terminology and its introduction sequence. +- [Chapter 1 pilot](../site/src/pages/learn/v2/01-new-engineering-paradigm.astro): the implemented reading reference, at `/learn/v2/01-new-engineering-paradigm/`. +- [Visual style-guide proposal](../docs/design/chapter-style-guide.html): open the standalone HTML in a browser to inspect reading layout, type and color, graphics, and components. Its editable source is [chapter-style-guide.fragment.html](../docs/design/chapter-style-guide.fragment.html). + +## A shared identity, a reading layout + +Retain the front page's dark surfaces, sans-serif typography, warm white text, teal and gold, fine rules and restrained use of pattern. The chapter layout gives prose, examples and explanatory graphics more room. It should feel like the same engineering publication. + +Use Inter for prose and headings, with a system sans-serif fallback. Use IBM Plex Mono sparingly for chapter numbers, short labels, status and technical notation. Avoid serif type, decorative dashboards and large collections of cards that interrupt the argument. + +| Role | Proposed value | Use | +| --- | --- | --- | +| Canvas | `#0d1011` | Main reading surface | +| Panel | `#151a1c` | A bounded example or optional interaction | +| Primary text | `#f1f3ef` | Headings and emphasis | +| Reading text | `#d7dedf` | Proposed brighter body copy | +| Secondary text | `#b9c2c5` | Captions and supporting labels | +| Rule | `#384144` | Quiet structural separation | +| Teal | `#9ed8cb` | Product-system work | +| Gold | `#f1d67b` | Engineering-environment work and selected navigation | + +Keep the product/environment color mapping consistent when a diagram uses it. Pair color with words, position or shape. Teal and gold do not mean PASS and FAIL. Check contrast against the actual surface; thin decorative rules are not sufficient boundaries for an essential control. + +## Reading structure + +Use a shared shell with clear part and chapter location, a readable prose column, optional in-page navigation, and meaningful previous/next destinations. Collapse course navigation on narrow screens. Clearly distinguish available articles, reader previews and planned chapters. + +Follow Chapter 1's teaching patterns where they serve the subject: + +1. Open with a recognizable engineering situation and a concrete question. +2. Introduce a useful visual early, beside the explanation it supports. +3. Develop the example through findings, alternatives or consequences. +4. Introduce terminology when the reader needs the distinction. +5. Offer optional depth or a reasoning check. +6. Close with what the reader can now assess and the next engineering question. + +These are composition principles, not mandatory headings or a fixed sequence of components. Each chapter needs its own learning gain. A six-tile overview is optional, and core understanding must remain visible without interaction or setup. + +## Typography and spacing proposal + +| Element | Desktop | Narrow screens | +| --- | --- | --- | +| Chapter title | 48 px | 34–38 px | +| Section heading | 30 px | 26 px | +| Subsection heading | 21 px | 20 px | +| Opening paragraph | 20 px | 18 px | +| Body copy | 18 px, about 1.7 line height | 16–17 px | +| Essential diagram labels | About 14 px | Reflow rather than shrink | +| Captions | 13–14 px | Keep readable at the same scale | +| Short mono labels | About 12 px | Avoid dense strings | + +Aim for a prose measure of 60–68 characters. Use an 8 px spacing rhythm: 8, 16, 24, 32, 48 and 64 px. Allow roughly 48–64 px between major sections and 24 px inside a substantial example panel. Use relative CSS units and preserve browser zoom. + +These values refine the pilot rather than describe its current CSS exactly. The pilot currently uses 16 px body text, approximately 15.4 px on narrow screens, a title up to 64 px, secondary text for most prose, and a slightly different panel color (`#151b1e`). The proposed larger, brighter reading text and smaller title remain candidates for a future layout update. Do not apply them silently while checking in this session. + +## Graphics that explain the engineering + +Use a diagram to show a relationship, sequence, comparison or consequence that would take more effort to explain in prose. Label the relationship as well as its endpoints. Place the graphic close to its explanation and give it a caption stating the useful conclusion. + +Chapter 1 supplies several reusable patterns: product/environment lanes, one finding with two consequences, engineering AI beside product AI, and different feedback cadences. Keep their engineering meanings intact when adapting them. The front page's two circles are another explanatory form, not a compulsory illustration for every chapter. + +Distinguish a conceptual example, a model calculation and an authentic recorded run. Do not invent durations, measured improvements or agent actions to make a graphic persuasive. Use ordinary text or HTML where it helps labels wrap. Stack comparisons and lanes on small screens; avoid scaling a desktop diagram until its text becomes unreadable. + +Use hexagons sparingly around an opening when useful. Keep patterns out of sustained reading and detailed diagrams. Motion should explain a change and respect reduced-motion preferences. + +## Reusable components + +| Component | Purpose | +| --- | --- | +| Chapter opening | Location, title, useful opening paragraph and compact optional chapter information | +| Principle statement | One important idea with a restrained gold rule | +| Term in context | A short definition attached to its first meaningful use | +| Explanatory figure | Labeled relationships and a consequence-focused caption | +| Finding comparison | What a finding changes in the product and the engineering environment | +| Disclosure | Optional detail, sources or alternative findings | +| Reasoning check | A concrete judgment before revealing an explanation | +| Chapter close | The new capability to assess or decide, followed by a working next destination | + +Prefer native links, buttons and disclosures. Provide visible focus, keyboard operation, accessible names and text equivalents for diagrams. Avoid hiding the central argument behind closed panels. + +## Implementation boundary + +The pilot's shared files are [ChapterLayout.astro](../site/src/layouts/ChapterLayout.astro), [CourseNavigation.astro](../site/src/components/CourseNavigation.astro) and [chapter-reading.css](../site/src/styles/chapter-reading.css). They are the starting point for future reuse, with chapter-specific content and in-page navigation reviewed as the next chapters are implemented. + +The visual proposal is a review specimen, outside the deployed site. Its illustrative copy is not replacement tutorial content. Keep the existing lessons, routes and executable lab intact while the broader curriculum is reviewed. Future rollout should verify readable diagrams, working navigation, keyboard use, narrow-screen reflow and accurate content status. diff --git a/project/CURRICULUM-MAP.md b/project/CURRICULUM-MAP.md index 13b7f76..fcbe5de 100644 --- a/project/CURRICULUM-MAP.md +++ b/project/CURRICULUM-MAP.md @@ -3,7 +3,7 @@ Status: proposed. Routes below are targets; **do not assume they exist**. | Part | # | Chapter | Distinct learning gain | Demonstration | |---|---:|---|---|---| -| I — Why and what next | 01 | The New Engineering Paradigm | Explain AI+digital engineering convergence | Fragmented vs connected workflow | +| I — Why and what next | 01 | The New Engineering Paradigm | Establish systems scope and shared terminology; explain how software-driven workflows and AI agents change engineering | Compare systems engineering workflows and feedback cycles | | I | 02 | Planning Under Uncertainty | Separate exploration from committed increments | DMS roadmap/option planning | | II — Learn and specify | 03 | Engineering Knowledge as Code | Explain cross-discipline source relationships | Interactive change-impact graph | | II | 04 | Learning Through Models and Prototypes | Qualify model fidelity and experiment results | Sensor/electronics/mount options | @@ -17,6 +17,26 @@ Status: proposed. Routes below are targets; **do not assume they exist**. | IV | 12 | Managing Engineering Knowledge at Scale | Track configurations, reuse and supplier interfaces | Variant/baseline comparison | | IV | 13 | The AI-Native Engineering Environment | Synthesize integrated workflow | End-to-end DMS engineering case | +## Terminology and introduction sequence + +The owner approved this terminology direction on 15 November 2026 during the front-page review. These are editorial definitions for the tutorial; the chapter sequence and future demonstrations remain planned. Systems engineering establishes the scope, executable engineering describes the approach, and AI agents are one capability within it. + +| Term | Meaning and usage in this tutorial | Introduce and develop | +|---|---|---| +| Systems engineering | Understanding and developing the whole system across disciplines, people and operating conditions. Keep software, electronics, physical design and use in view. | Establish in Chapter 01; apply throughout. | +| Executable engineering | The site's working description for engineering where models, analyses, tests and parts of the workflow can be run, evaluated and improved. It does not imply that every engineering activity is executable or automated. | Introduce on Home and in Chapter 01; develop through Chapters 03–06 and synthesize in Chapter 13. | +| Software-driven workflows | Software supports how engineering work is performed across disciplines: running models, handling data, testing, reviewing and preparing releases. This is broader than software development. | Introduce in Chapter 01; apply in Chapters 04–06, 08–09 and 13. | +| AI-assisted engineering | The broad use of AI in engineering work, including interactive assistance and delegated agent tasks. “AI-assisted systems engineering” is a useful description of that application, not the name for the entire tutorial approach. | Introduce in Chapter 01; illustrate in Chapter 04 and deepen in Chapter 07. | +| AI agents / agentic engineering | Agents pursue a defined task, use tools, inspect results and adapt their next steps. Prefer “AI agents” in introductory prose; use “agentic engineering” for this way of working. Engineers direct and evaluate the work. | Explain AI agents in Chapter 01; develop task delegation, tool use, context and evaluation in Chapter 07, then apply in Chapters 08–09 and 13. | +| AI in products | AI contributing to product behavior, including prediction, perception or decision support. Product AI need not be agentic or based on an LLM. | Distinguish from AI used in engineering in Chapter 01; revisit when evaluating models and system behavior in Chapters 04, 05 and 10. | +| Large language model (LLM) | A model technology underlying many AI assistants and agents. Explain the model's role separately from the surrounding tools and workflow. Spell out the term at first use; use it where the underlying mechanism matters. | Explain in Chapter 07, or at first use if a preceding example requires the mechanism. Do not lead Home with the acronym. | + +Use the opening engineering situation to introduce the distinctions, rather than requiring readers to memorize a glossary before seeing the problem. Carry the same meanings into subsequent chapter briefs and the future Reference glossary. The scope of AI in products remains separate from the choice to use agents during development. + +“We build the machine that builds the machine” describes the co-development of the product system and its engineering environment: people, methods, models, tools and workflows. Chapter 01 introduces the two systems; Chapter 13 brings the idea together. Frequent software releases, model iterations and physical validation retain their different cadences. + +The systems scope follows [INCOSE's systems engineering definition](https://www.incose.org/about-systems-engineering/). The agent distinction draws on [Anthropic's explanation of predefined workflows and agents that choose their steps and tools](https://www.anthropic.com/research/building-effective-agents). “Executable engineering” is the tutorial's working description, not a claim of a standardized discipline. + ## Content dependency model 01→02 sets motive and direction. 02 feeds 03, 04, 05 and 06 through uncertainty priorities. diff --git a/project/EDITORIAL-GUIDE.md b/project/EDITORIAL-GUIDE.md index 998b126..44cd96e 100644 --- a/project/EDITORIAL-GUIDE.md +++ b/project/EDITORIAL-GUIDE.md @@ -3,6 +3,9 @@ ## Voice American English, confident but measured, practical and readable. Engineer-to-engineer, not marketing. Avoid anthropomorphizing tools (prefer 'the agent requires access to ...' or 'the workflow provides ...' over 'AI wants ...'). Start with a meaningful decision or tension. Keep one purpose per paragraph. +## Terminology +Follow the [curriculum terminology and introduction sequence](CURRICULUM-MAP.md#terminology-and-introduction-sequence). Systems engineering establishes the scope; executable engineering describes the tutorial's approach; AI agents are a capability within it. Explain terms at first use. Prefer “AI agents” in introductory copy and use “agentic engineering” for delegated work with tools and feedback. Keep AI-assisted engineering, agentic work, AI in products and large language models distinct. Describe software-driven workflows across engineering disciplines without implying that the subject is software development alone. + ## Chapter composition A chapter brief specifies a **unique** learning gain, opening engineering question, scenario progression, narrative arc, one primary visualization/interactivity, evidence boundary, and next chapter bridge. Do not mandate identical heading sequences or a custom code lab per chapter. Exercises optional where value is clear. Ask reader to predict before revealing answers when appropriate. @@ -13,7 +16,11 @@ Reference known distinctions rather than re-explaining baseline FAIL, 50% teachi Each part represents at least two distinct non-software disciplines in substantive scenarios. At least one cross-discipline decision has conflicting constraints and lead-times. Distinguish design maturity, model confidence and physical acceptance. ## Visual language -Muted earth/olive palette retained where helpful; typography with strong hierarchy, whitespace, meaningful diagrams, few decorations. Prefer real interactive graph/scenario/workflow visualization to stock images. Label model provenance and simulated vs historical vs live data. Maintain keyboard operation, semantic labels, text equivalent, reduced motion where useful and narrow-screen usability. +Follow [the current site direction](SITE-DIRECTION.md): dark surfaces, readable sans-serif type, warm white text and restrained teal/gold accents. Use strong hierarchy, whitespace and meaningful diagrams. Choose a static comparison, annotated workflow or interaction according to its learning purpose. Label conceptual examples, model outputs and authentic recorded runs accurately. Maintain keyboard operation, semantic labels, text equivalents and narrow-screen usability. + +The Chapter 1 reader pilot begins with a concrete situation and an early visual. Keep status and source information in a compact disclosure. A six-tile overview is optional for future chapter reviews, not a template requirement. Core understanding should not require controls, an AI account or local setup. + +Use the [chapter style-guide proposal](CHAPTER-STYLE-GUIDE.md) alongside the pilot when reviewing future layouts. It distinguishes the implemented reference from proposed typography refinements and leaves chapter composition flexible. ## Language examples Avoid: 'The source relation establishes what the evidence supports' repeated as boilerplate. diff --git a/project/INFORMATION-ARCHITECTURE.md b/project/INFORMATION-ARCHITECTURE.md index 28ec7c5..bc816a6 100644 --- a/project/INFORMATION-ARCHITECTURE.md +++ b/project/INFORMATION-ARCHITECTURE.md @@ -1,7 +1,7 @@ # Information architecture v2.0 ## Routes (target, not existing) -Home: compelling AI-native, multidisciplinary engineering thesis plus first-step CTA. +Home: systems engineering practice changing through software, executable models and AI; clear routes into useful reading and examples. Learn: 4 parts, 13 chapters, unique outcomes, progress markers without mandatory gating. Lab: V0 coverage plus staged isolated D1+ experimental tools. Explore: knowledge graph, architecture alternatives, roadmap, decision/evidence paths. @@ -13,6 +13,7 @@ Reference: glossary, assumptions, canonical sources, example specifications, rev - Existing `engineering/`, `schemas/`, `models/`, `scripts/` authoritative V0 definitions and computation. - New experimental demonstrations isolated under a namespaced future directory agreed in PR, with versioned scenario fixtures. - `site/src/data/chapters.ts` remains the published chapter registry; do not register incomplete/unpublished routes. +- Its separate `chapterPreviews` export holds complete local reader previews present in the build, explicitly distinguished from published articles. The first pilot is `learn/v2/01-new-engineering-paradigm/`; it does not replace the original Chapter 1. - Historical milestone documents retained with historical labels. ## Information presentation @@ -25,3 +26,5 @@ Preserve existing URL paths by redirects, aliases, or published fallback until m Every page has clear location (part/chapter), forward/back, Learn index, source/reference links. A migrated old slug should lead to appropriate new content or historical archived lesson; no 404s. Never claim a scenario/agent run is live if it is a static replay. + +The Chapter 1 pilot uses the shared four-part curriculum grouping, marks the current chapter, links available articles and labels planned chapters without dead links. On narrow screens, course navigation is collapsed. The next planned chapter links to its part on Learn. Other chapter layouts wait for pilot review. diff --git a/project/SITE-DIRECTION.md b/project/SITE-DIRECTION.md new file mode 100644 index 0000000..92f55da --- /dev/null +++ b/project/SITE-DIRECTION.md @@ -0,0 +1,83 @@ +# Site direction — Executable Engineering Lab + +Updated 15 November 2026 from the owner's front-page reviews and approved revised brief. This is the editorial direction for the reviewed front page and v2 reader pilot. The separate [v3 manuscript index](v3/manuscripts/INDEX.md) governs approved v3 prose. Historical release specifications and the implemented V0 model retain their technical history and contracts. + +The [original site-direction document](https://chatgpt.com/space/page_52692f0497f48191bc7e6b4a254696a0) is the owner-facing brief. The [revised brief and review rationale](https://chatgpt.com/space/page_ddc0b4dd8ea88191afe241eed2019b95) records how the direction developed. + +## Purpose, vision and mission + +Help senior engineers, technical leaders and executives understand and evaluate how systems engineering changes through executable models, software-driven workflows and AI agents. Build informed support within the company through useful explanations and inspectable examples. + +**Vision:** R&D teams investigate more possibilities, test ideas earlier and evolve useful systems through shorter feedback cycles, while developing the engineering environment that supports the work. + +**Mission:** Explain and demonstrate how models, software-driven workflows and AI agents support that change across software, electronics, physical design and operation. Help readers understand mechanisms, evaluate results and identify a useful next experiment. + +Credibility follows from substance and judgment. The site is an engineering publication and learning environment, not a service offer, hiring funnel, platform advertisement or demonstration of web-design skill. + +## The engineering argument + +Greenfield products and applications are the main setting. Use cases, requirements and architecture can be unclear; the team learns while making progress. Carry that story through implementation, integration, testing, validation, delivery and evolution. + +> We develop, operate and improve the engineering environment alongside the product. + +“We build the machine that builds the machine” makes this relationship memorable. The second machine includes people, methods, models, tools and workflows. Improve it through concrete product questions; reuse existing capability and add what the next investigation requires. + +Show what teams can model, investigate, delegate, evaluate and deliver differently. Speed means shorter learning loops and more frequent useful improvements. Software releases, model revisions and physical prototypes have different cadences. Testing and quality are part of this work. + +AI used during engineering and AI in products are distinct subjects. Digital threads and integration support the work; connected information alone is not the principal benefit. Product maturity and planning should reflect findings, uncertainties and dependencies as well as completed activities. Governance and assurance remain in the curriculum, proportional to the work they qualify. + +## Vocabulary + +The [curriculum map](CURRICULUM-MAP.md#terminology-and-introduction-sequence) owns the detailed definitions and introduction sequence. + +| Term | Editorial use | +| --- | --- | +| Systems engineering | The whole-system scope across disciplines, people and use. | +| Executable engineering | The tutorial's working description: models, analyses, tests and parts of the workflow can be run, evaluated and improved. | +| Software-driven workflows | Software supports engineering work across disciplines, not only software development. | +| AI-assisted engineering | The broad category of AI used in engineering work, including interactive assistance and delegated tasks. | +| AI agents / agentic engineering | Agents use tools, inspect results and adapt steps toward a defined task. Engineers direct and evaluate the work. Prefer “AI agents” in introductory prose. | +| AI in products | AI contributes to product behavior. It need not be agentic or use an LLM. | +| Large language model (LLM) | A model technology behind many assistants and agents, distinct from their tools and workflows. Expand the acronym at first use. | + +Introduce the shared language through Chapter 1's engineering situation. Chapter 7 develops agent mechanisms and delegation. Do not make the reader memorize a glossary before encountering a problem. A fixed workflow does not become agentic merely because AI helped create it. + +## Content and reading design + +Retain the planned four parts and thirteen chapters. Each chapter has a distinct engineering question, reader outcome, example and next question. Parts express a progression in understanding, not arbitrary content buckets. Keep the grouping consistent on Learn and in chapter navigation. + +Start with a recognizable situation and place a useful visual early. Put explanation beside the model, comparison or relationship it explains. Use optional interaction for prediction, variation, inspection or comparison; core understanding must remain available without an account or local setup. + +The document-as-code work supplies reading principles: situation before terminology, a readable prose column, clear course location, optional deeper references, compact chapter information and meaningful previous/next destinations. Its later local decision to remove six-tile summaries is adopted for the Chapter 1 pilot. An overview is optional where it helps; six tiles are not a universal requirement for new or revised chapters. Existing chapter panels remain until their own review. + +Preserve the front page's dark theme, sans-serif typography, warm white text, teal and gold distinctions, and subtle patterns. The main visual task is to explain engineering. Avoid diagrams that imply measured schedules, automated approvals or implemented agents when none exist. + +The [chapter style-guide proposal](CHAPTER-STYLE-GUIDE.md) records the reusable reading patterns and proposed refinements. Chapter 1 is its main implemented reference; the proposal does not authorize automatic migration of the remaining chapters. + +For the Chapter 1 pilot: + +- Open with a new monitoring product whose use and design are still uncertain. +- Show product-system work and engineering-environment work together. +- Let a reader follow illustrative findings into changes to both systems. +- Explain executable models, software-driven workflows and the distinct roles of AI in context. +- Show different engineering feedback cycles without invented durations or productivity claims. +- Close with a decision about which uncertainty to investigate next. +- Use a responsive course sidebar, collapsed navigation on small screens and optional chapter information. Link planned chapters to the learning map rather than nonexistent pages. + +## Boundaries and current scope + +The owner authorized updating this direction and implementing Chapter 1 as a local reader preview on 15 November 2026. The noncolliding route is `/learn/v2/01-new-engineering-paradigm/`. Preserve the original `/learn/01-engineering-intent/` lesson and its fragments. Other chapter content and layouts wait for pilot review. + +Keep preview articles separate from the published-article registry and label them accurately. Home and Learn must provide a working route into the pilot. Its scenarios are conceptual illustrations, not numerical simulations, measured observations or agent-run transcripts. The existing single-sensor model remains the working executable lab. + +Do not change the canonical V0 sources, calculation, evidence contract or existing lesson routes for this editorial pilot. New physical demonstrations and authentic agent runs require separately scoped implementation. A local preview and passing checks do not constitute publication approval. + +## Review questions + +Can a reader explain what is changing in engineering practice, why it helps the team and what practical work it requires? Are models, agentic work, software-driven delivery and physical behavior all visible? Does the terminology clarify rather than dominate? Does each graphic reduce the work of understanding? Can the reader distinguish an illustration, a working example and a planned capability? + +Review Chapter 1 for these qualities before applying the layout to other chapters. + +## Publication authorization — 15 November 2026 + +After the session changes were committed, the owner explicitly requested publication. Publish the reviewed front page, Learn navigation and Chapter 1 reader preview while retaining its editorial preview status. This does not approve the remaining chapter migrations or publication of the separate v3 manuscripts and research archive. diff --git a/project/TUTORIAL-SPEC.md b/project/TUTORIAL-SPEC.md index d0afe1d..6834664 100644 --- a/project/TUTORIAL-SPEC.md +++ b/project/TUTORIAL-SPEC.md @@ -1,19 +1,21 @@ # Tutorial specification v2.0 — Executable Engineering Lab -Status: proposed | Language: American English | Format: browser-first Astro tutorial +Status: revised direction; Chapter 1 pilot authorized, remaining curriculum planned | Language: American English | Format: browser-first Astro tutorial + +Current editorial authority: [Site direction](SITE-DIRECTION.md), updated 15 November 2026. ## Product promise -**Engineering at the Speed of AI.** -Show how connected engineering knowledge and constrained AI-assisted work increase the speed of learning and controlled delivery in multidisciplinary systems, without abandoning engineering judgment, architecture or verification. +**Software and AI change what we build. And how we build it.** +Explain how executable models, software-driven workflows and AI agents support faster learning and useful delivery across software, electronics, physical design and operation. Show the practical mechanisms and engineering judgment behind the change. ## Central thesis -Digital engineering has long sought connected information across engineering disciplines. Agentic AI can use and transform that information at high speed, increasing both opportunity and the need for control. Knowledge, exploratory models, progressive specifications, reviewable increments and engineering evidence must co-evolve. +We develop, operate and improve the engineering environment alongside the product. Greenfield product questions shape the models, methods, tools and workflows the team needs. Those capabilities expand what it can investigate and deliver. AI in products and AI used during development have distinct roles; digital threads and integration support the work rather than define its primary benefit. ## Audience Practicing systems, mechanical, electronics, software, manufacturing, integration, safety and verification engineers; engineering leads and technically engaged managers. Do not assume familiarity with Git, Astro, YAML, SysML, specific agents or CI. Explain terms where first used; add optional implementation depth. ## Learning outcomes At the end readers can: -1. Explain why integrated information and agentic workflows reinforce one another. +1. Explain how executable models, software-driven workflows and AI agents change systems engineering, distinguishing AI assistance from AI in products. 2. Separate vision, roadmap initiative, uncertainty, release increment and implementation backlog. 3. Distinguish intent, hypothesis, controlled definition, observed evidence and decision. 4. Navigate and critique cross-discipline digital threads and change impact. @@ -47,10 +49,11 @@ Browser-first; local development optional. A chapter can be valuable without req Narrative-first, concise American English, reader-facing engineering question before tool explanation. Avoid recurring lengthy disclaimers in the main prose; provide a consistent `Model limits / What this does not establish` pattern in relevant context. Use terms consistently: need, requirement, model, evidence, approval, hypothesis, design option, baseline, release. +The [curriculum terminology and introduction sequence](CURRICULUM-MAP.md#terminology-and-introduction-sequence) defines systems engineering, executable engineering, software-driven workflows, AI-assisted engineering, AI agents/agentic engineering, AI in products and large language models. Establish the shared vocabulary in Chapter 01; develop agent mechanisms in Chapter 07. Do not imply simulation results equal operational assurance. ## Success criteria -- AI-native engineering and multidisciplinary integration clearly articulated above the fold. +- The opening makes the change in systems engineering practice, its mechanisms and relevance to R&D understandable. - Every chapter demonstrably adds a unique concept and decision-making capability. - At least one actual, provenance-bearing agent-run record is inspectable (static replay acceptable; no invented agent actions). - At least one cross-discipline change impacts electronics, mechanical installation and software/integration, without treating synthetic values as certified evidence. @@ -60,4 +63,8 @@ Do not imply simulation results equal operational assurance. ## Proposed data enrichment extension (November 2026) -Insert v2 Chapter 05 — Engineering Data: From Measurements to Decisions — immediately after modeling/prototypes. The learning outcome is to evaluate and improve the usefulness of engineering data through quality, annotation, enrichment, visualization, review and preservation/reuse. Use a deterministic V0 parameter study with explicitly hypothetical cross-discipline planning constraints. Distinguish computed outputs from measurements; show original, curated and derived data with their provenance. The proposed v2 curriculum now has 13 chapters. Every lesson should have an accessible Chapter at a Glance, with one concise idea and six topic-specific anchors; these tiles are conceptual, not six mandatory process steps. The original 12 published routes and V0 assertions remain untouched. The new chapter draft is for owner editorial review, not implementation approval. +Insert v2 Chapter 05 — Engineering Data: From Measurements to Decisions — immediately after modeling/prototypes. The learning outcome is to evaluate and improve the usefulness of engineering data through quality, annotation, enrichment, visualization, review and preservation/reuse. Use a deterministic V0 parameter study with explicitly hypothetical cross-discipline planning constraints. Distinguish computed outputs from measurements; show original, curated and derived data with their provenance. The proposed v2 curriculum now has 13 chapters. The original 12 published routes and V0 assertions remain untouched. + +## Chapter reading pilot — 15 November 2026 + +The owner authorized Chapter 1 as a local reader preview applying the revised direction. Use an engineering situation, an early explanatory graphic, terminology in context, optional deeper material and consistent course navigation. A six-tile At a Glance panel is no longer a universal requirement for new or revised chapters. Existing chapter panels remain pending their individual review. Implement and evaluate Chapter 1 before applying its layout more widely; this is not publication approval. diff --git a/site/src/assets/hero-hexagons.svg b/site/src/assets/hero-hexagons.svg new file mode 100644 index 0000000..ff072cb --- /dev/null +++ b/site/src/assets/hero-hexagons.svg @@ -0,0 +1,3 @@ + + + diff --git a/site/src/components/CourseNavigation.astro b/site/src/components/CourseNavigation.astro new file mode 100644 index 0000000..fb1203d --- /dev/null +++ b/site/src/components/CourseNavigation.astro @@ -0,0 +1,26 @@ +--- +import { v2Parts } from '../data/v2-curriculum'; +import { v2Chapters, chapterPreviews } from '../data/chapters'; +interface Props { current: number } +const { current } = Astro.props; +const base = import.meta.env.BASE_URL; +const available = [...chapterPreviews, ...v2Chapters]; +--- + diff --git a/site/src/data/chapters.ts b/site/src/data/chapters.ts index 1523f2a..6ff105f 100644 --- a/site/src/data/chapters.ts +++ b/site/src/data/chapters.ts @@ -18,3 +18,8 @@ export const chapters = [ export const v2Chapters = [ { path: 'v2/05-engineering-data', title: 'Engineering Data: From Measurements to Decisions', summary: 'Check, annotate and combine data; interpret calculated geometry alongside hypothetical power constraints.', number: 5 }, ] as const; + +/** Complete editorial reader previews, separate from the established articles. */ +export const chapterPreviews = [ + { path: 'v2/01-new-engineering-paradigm', title: 'The New Engineering Paradigm', summary: 'Develop the system and its engineering environment together, using executable models, AI agents and useful feedback across disciplines.', number: 1 }, +] as const; diff --git a/site/src/layouts/ChapterLayout.astro b/site/src/layouts/ChapterLayout.astro new file mode 100644 index 0000000..c3dfed6 --- /dev/null +++ b/site/src/layouts/ChapterLayout.astro @@ -0,0 +1,45 @@ +--- +import CourseNavigation from '../components/CourseNavigation.astro'; +import '../styles/chapter-reading.css'; +interface Props { title: string; description: string; number: number } +const { title, description, number } = Astro.props; +const base = import.meta.env.BASE_URL; +--- + + + + + + + + {title} · Executable Engineering Lab + + + + + + + +
+ +
+
Course navigation · Chapter {String(number).padStart(2, '0')}
+ +
+
+ + + diff --git a/site/src/layouts/HomeLayout.astro b/site/src/layouts/HomeLayout.astro new file mode 100644 index 0000000..5a0e338 --- /dev/null +++ b/site/src/layouts/HomeLayout.astro @@ -0,0 +1,83 @@ +--- +interface Props { + title: string; + description: string; +} + +const { title, description } = Astro.props; +const base = import.meta.env.BASE_URL; +--- + + + + + + + + + {title} · Executable Engineering Lab + + + + + + + +
+ + + + + + + diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro index 595b3b6..106953c 100644 --- a/site/src/pages/index.astro +++ b/site/src/pages/index.astro @@ -1,34 +1,287 @@ --- -import Layout from '../layouts/Layout.astro'; -import { chapters, v2Chapters } from '../data/chapters'; -import { v2Parts } from '../data/v2-curriculum'; -const base = import.meta.env.BASE_URL; +import HomeLayout from '../layouts/HomeLayout.astro'; +import { chapters, chapterPreviews, v2Chapters } from '../data/chapters'; +const base = import.meta.env.BASE_URL; +const featuredPaths: ReadonlySet = new Set([ + '04-executable-models', + '05-experimentation', + '07-agentic-engineering', + '09-continuous-engineering', +]); +const featuredChapters = chapters.filter(chapter => featuredPaths.has(chapter.path)); --- - -

Executable Engineering Lab · A practical learning environment

-

Engineering at the Speed of AI.

-

Digital Engineering connects knowledge across disciplines. AI agents can accelerate exploration and implementation. The challenge is to use both without losing control of engineering decisions, architecture, or evidence.

-

Follow a fictional Distributed Monitoring System from uncertain intent toward progressively more informed engineering decisions. The planned curriculum will explore how software, electronics, mechanical design, integration and verification contribute at different speeds.

-

Our approach: specify what we know, explore what we don't, verify what we build, and preserve what we learn.

-

Explore the learning path → · Open the existing coverage lab

-

V2 curriculum in development. The published lessons and working lab below remain the current learning experience.

-

Four connected questions

-
- {v2Parts.map(part =>

{part.title}

{part.message}

V2 direction: {part.chapters.join(' / ')}

)} + + +
+
+

New product development · Systems engineering + AI agents

+

Software and AI change what we build.
And how we build it.

+

Software and AI are changing both the systems we develop and the way we develop them. Executable models, AI agents and repeatable workflows let teams explore designs, test assumptions and deliver smaller increments. The engineering challenge is to turn that pace into better systems—across software, electronics and physical design.

+

We develop, operate and improve the engineering environment alongside the product.

+
+ +
+ +
+
+

Develop the system.
Develop how we engineer it.

+ Conceptual approach +
+
+
+
+ +
+

Product system

+

Software · electronics
Physical design · AI

+
+

Understand use

+

Model
and experiment

+

Integrate
and validate

+
+
+

New product ambitions
change the engineering work

+

Decide what to test
and what to build next.

+

New engineering capabilities
expand what we can try

+
+
+ +
+

Engineering
environment

+

People · models
Tools · AI agents

+
+

Develop methods and models

+

Work with
AI agents

+

Automate
and evaluate

+
+
+
+

Executable engineering

+

Executable engineering puts models, analyses and checks to work in repeatable workflows. AI agents can carry out tasks within that environment, using tools and responding to results, with engineers directing and evaluating the work.

+
+
We build the machine that builds the machine.
+
+
+ +
+
+

From a product question to the next experiment.

+ Conceptual workflow +
+

Can an AI-enabled monitoring device recognise faults reliably enough to be useful, within its power and latency limits?

+
+
+

Model + prototype

+

Turn the question into an experiment.

+

Engineers define relevant fault scenarios. An AI agent prepares and runs a simulation, inspects the results and revises the analysis; engineers check the assumptions.

+
+
+ +

Run + compare

+

Evaluate the product’s AI.

+

Compare candidate detection models on representative data. Test missed detections, false alarms, latency and power on the target hardware.

+
+
+ +

Learn + release

+

Make the next change smaller.

+

Use the results to revise the model, sensing setup or software. When release criteria are met, ship a small software increment and use operating feedback to shape the next experiment.

+
+
+

The workflow is part of the engineering result. Retain the model, dataset, configuration and evaluation code so the team can rerun the experiment after the next change.

+
+ +
+
+

01 / Modelling and exploration

+

Make ideas
executable.

+

Use code, simulation, data-driven models and physical prototypes to explore behaviour. AI agents can help implement and explore models; engineers choose the abstraction, check predictions and test where the model stops being useful.

+
+
+

02 / Teams and workflows

+

Engineer the
workflow too.

+

Give teams responsibility for the models, tools and data they rely on. Automate repeatable analysis, testing and release preparation. Make progress visible through demonstrated behaviour, unresolved questions and dependencies, so engineers and leaders can decide what to improve next.

+
+
+

03 / Release and feedback

+

Release often.
Learn from use.

+

Small software releases keep the feedback loop moving. Automated tests, AI evaluations and operating data help judge quality. Electronics, mechanical changes and physical validation have their own cadences; frequent software delivery must respect those constraints.

+
-

Published v2 articles

-
{v2Chapters.map(chapter => )}
-

Explore the published lessons

-

The original twelve lessons remain available while the new curriculum is developed. They focus on a deliberately limited single-sensor teaching model. The new multidisciplinary demonstrations and recorded agent workflows are planned, not yet implemented.

-
- {chapters.map((chapter, index) => )} + +
+

Explore the argument

+
+ {chapterPreviews.map(chapter => ( +
+

Chapter {chapter.number} · Preview

+ Start with {chapter.title} +
+ ))} + +
+ All published lessons +
+

Published v2 articles

+ +

Original course

+
    + {chapters.map(chapter =>
  1. {chapter.title}
  2. )} +
+ Explore the full learning path +
+
+
-

Inspect engineering sources · See the repository

- + + diff --git a/site/src/pages/learn/index.astro b/site/src/pages/learn/index.astro index fec2c2a..de08dec 100644 --- a/site/src/pages/learn/index.astro +++ b/site/src/pages/learn/index.astro @@ -1,17 +1,27 @@ --- import Layout from '../../layouts/Layout.astro'; -import { chapters, v2Chapters } from '../../data/chapters'; +import { chapters, v2Chapters, chapterPreviews } from '../../data/chapters'; import { v2Parts } from '../../data/v2-curriculum'; const base = import.meta.env.BASE_URL; ---

Learn · Curriculum transition

-

Learn to engineer with AI — and maintain control.

-

The new thirteen-chapter journey will connect planning, engineering knowledge, prototyping, progressive specifications, AI agents, integration and engineering evidence.

+

Develop the system. Develop how you engineer it.

+

Explore how executable models, software-driven workflows and AI agents change systems engineering—from an uncertain product idea to useful improvements in operation.

+
+

Start with Chapter 1

+

The opening chapter is a reader preview of the revised content and dark chapter layout.

+ {chapterPreviews.map(chapter =>

{chapter.title} →
{chapter.summary}

)} +

V2 course structure

Planned curriculum. The full sequence below is planned; available v2 articles are linked separately below. Go to the published lessons for working examples.

-
{v2Parts.map(part =>

{part.title}

    {part.chapters.map(title =>
  1. {title}
  2. )}
)}
+
{v2Parts.map(part =>

{part.title}

{part.message}

    {part.chapters.map(title =>
  1. {title}
  2. )}
)}
+
+

A shared vocabulary from Chapter 1

+

The Chapter 1 preview introduces systems engineering, executable engineering, software-driven workflows and AI-assisted engineering. It explains what AI agents do and distinguishes AI used in engineering from AI in products.

+

Chapter 7 will develop agentic engineering through delegated tasks, tool use and evaluation, explaining large language models (LLMs) as part of the underlying technology. Later chapters will apply these terms to models, delivery, physical validation and the engineering environment.

+

Published v2 articles

{v2Chapters.map(chapter => )}

Published lessons — original course

@@ -23,6 +33,7 @@ const base = import.meta.env.BASE_URL; .parts{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,21rem),1fr));gap:1rem;margin-bottom:3rem} .parts h3{margin-top:0} .parts li{margin:.35rem 0} + .course-language{margin-bottom:3rem} .current{padding-left:1.5rem} .current>li{margin:1.5rem 0} .current h3{margin:0} diff --git a/site/src/pages/learn/v2/01-new-engineering-paradigm.astro b/site/src/pages/learn/v2/01-new-engineering-paradigm.astro new file mode 100644 index 0000000..120ea2e --- /dev/null +++ b/site/src/pages/learn/v2/01-new-engineering-paradigm.astro @@ -0,0 +1,145 @@ +--- +import ChapterLayout from '../../../layouts/ChapterLayout.astro'; +const base = import.meta.env.BASE_URL; +--- + +
+
+

Part I · Engineering in the Age of AI / Chapter 01

+

The New Engineering Paradigm

+

Software and AI change the systems we can build—and the work of building them. How do we turn that new pace into useful engineering progress?

+
+ About this chapter · Reader preview +

This pilot applies the revised site direction. The monitoring example and agent workflow are conceptual, not a simulation or a recorded agent run. The original lessons and working coverage lab remain available.

+

Content and layout revised 15 November 2026. Repository and revision history · Original Chapter 1

+
+
+ +
+

An operations team wants to detect developing equipment faults before they interrupt production. A small monitoring device might help. But which faults matter, where can the sensor be mounted, and what would an operator do with its warning? The product is still a set of questions.

+

The team can model signal behavior, prototype an enclosure, try an AI classifier and test an early software version. Each activity can move quickly. The harder task is deciding what those results mean for the system—and what to investigate next.

+ +
+

Two systems develop together.

+
+

One product question. Two kinds of engineering work.

Conceptual example
+

Can we recognize a useful fault signal on the equipment as it is actually installed?

+
+

The product system

+
    +
  1. Sensor + mountingCapture the physical signal
  2. +
  3. Software + product AIInterpret what was observed
  4. +
  5. Operator + responseAct on a useful warning
  6. +
+
+

↓ Product questions shape the experiments↑ Findings guide the design

+
+

The engineering environment

+
    +
  1. Models + test fixturesRepresent conditions and alternatives
  2. +
  3. Tools + AI agentsRun analyses and inspect results
  4. +
  5. People + methodsEvaluate findings and choose next work
  6. +
+
+
The product has to work in use. The engineering environment helps the team discover what works, investigate what does not, and carry that learning into the next design.
+
+

This is a systems engineering problem: develop the whole system across disciplines, people and operating conditions. Sensor electronics, mechanical installation, software and the operator's task all affect whether a warning is useful.

+

It is also work on the engineering environment. A new mounting concept may require a better model or a different test fixture. Once the team can repeat that experiment, the next comparison becomes easier to make and explain.

+

We develop, operate and improve the engineering environment alongside the product.

+ +

Follow a finding into the next piece of work.

+

Illustrative situations · Expand a finding to see its consequences.

+
+ 01 / PHYSICAL BEHAVIORThe signal changes with the mounting. +
+

Develop the product

Compare mounting options before committing to the enclosure. Check whether the signal remains useful under the intended installation conditions.

+

Develop how we engineer it

Revise the model's mounting assumptions and adapt the test fixture. Keep the signal-processing workflow so the next experiment can reuse it.

+
+

The useful gain: the next design comparison starts from what the team has learned about the physical system.

+
+
+ 02 / PRODUCT AIThe classifier misses an unfamiliar operating condition. +
+

Develop the product

Investigate the missed condition and the consequence for the operator. Revisit the classifier, sensing approach or intended range of use.

+

Develop how we engineer it

Add representative cases to a separate evaluation set. Compare future candidates against these cases and the conditions already understood.

+
+

The useful gain: an observed weakness becomes a repeatable evaluation for subsequent candidates.

+
+
+ 03 / SOFTWARE DELIVERYA firmware change alters sampling behavior. +
+

Develop the product

Evaluate the changed behavior against the current electronics and sensing assumptions before releasing the increment.

+

Develop how we engineer it

Add a repeatable interface check and retain the tested configuration. Run the check on later changes and schedule physical tests where the change requires them.

+
+

The useful gain: frequent software delivery gets earlier feedback about a system dependency.

+
+
+ +
+

Put the models to work.

+

A model is more useful to the investigation when the team can change an input, run it and compare the result. A test becomes more useful when it can run again after a change. A workflow becomes more useful when the next person can use it without reconstructing every step.

+

We use executable engineering for this approach: models, analyses, tests and parts of the engineering workflow can be run, evaluated and improved. The name describes a way of working; it does not make every engineering judgment executable.

+

Software-driven workflows carry this beyond software development. A mechanical engineer can run a parameter study. An electronics engineer can evaluate a signal chain. A test engineer can process measurements and compare configurations. Repeatable execution makes another investigation practical while preserving enough context to interpret it.

+

A digital thread maintains the relationships that matter: this model uses that assumption; this experiment tests that configuration; this finding informs that decision. The benefit is that the next investigation can build on the reasoning, rather than rediscovering which result belongs to which design.

+
+ +
+

AI changes the work and the product.

+

AI-assisted engineering covers AI used in engineering work, from helping an engineer examine an idea to carrying out a delegated task. An AI agent can use tools, inspect their results and adapt its next steps toward a defined objective. We call this way of working agentic engineering. Engineers still frame the task and evaluate the work.

+
+
+

AI in the engineering environment

+

Investigate a design question.

+

An agent could implement alternative signal-processing models, run them against specified cases, inspect the outputs and revise a candidate. The engineer needs to examine the model, comparison and remaining uncertainty.

+
+
+

AI in the product

+

Provide a product capability.

+

A classifier could help the monitoring device distinguish a fault signal from normal operation. Its usefulness depends on the data, equipment conditions and consequences of a missed or false warning.

+
+
+

These are different uses of AI. The classifier need not be an agent or use a large language model (LLM). An LLM is a model technology behind many assistants and agents; it is one part of the surrounding tools and workflow. A fixed script that reruns tests is automation, even if an AI helped write it.

+

Useful agent work also changes the team's preparation. Models need usable inputs. Tools need clear interfaces. Results need context. Making those available lets people and agents investigate with the same engineering resources, while keeping the interpretation open to review.

+
+ +
+

Increase the pace. Respect the system.

+

Faster engineering means shortening the time between a question, an experiment and a useful decision. It also means delivering smaller improvements more frequently when the system can support them. Software releases, model revisions and physical prototypes contribute different kinds of feedback.

+
+
SoftwareChange → check → release → observe
+
ModelsRevise assumptions → run alternatives → compare
+
Electronics + mechanicsDesign → fabricate → integrate → test
+
System in useObserve behavior → evaluate usefulness → revise intent
+
Different feedback cycles, not a common release clock. This schematic assigns no durations.
+
+

Testing and evaluation belong inside these loops. Verification asks whether specified expectations are met; validation investigates whether the system is suitable for its intended use. Frequent software checks support delivery, while physical behavior and use still need relevant evidence.

+

This changes how teams organize and follow the work. Alongside completed tasks, ask which behavior has been demonstrated, which uncertainty remains and which dependency is holding up the next decision. A failed prototype can advance understanding. More generated code does not, by itself, establish product maturity.

+
+ A software release passes every automated check. What have we learned about the mounting? +

Only what those checks actually evaluate. If they do not represent mounting behavior, they provide no new evidence about it. Use their results to advance the software work, then identify the model or physical experiment needed for the mounting question.

+
+
+ +
+

The engineering takeaway

+

We build the machine that builds the machine.

+

The second machine is the people, methods, models, tools and workflows that make engineering possible. Develop it through real product questions. Reuse what already works, add what the next investigation needs, and improve the environment as the team learns.

+

The monitoring team now has several possible next steps: understand the mounting, improve the classifier, or test what an operator needs. Which uncertainty deserves attention first—and which work is ready for commitment? That is the question for Chapter 2, Planning Under Uncertainty.

+
+ +
+

Inspect an example or go deeper

+ +

Executable engineering is this tutorial's working description. The monitoring situations illustrate an approach; they are not measured product results or evidence of a running agent.

+
+
+ +
+
diff --git a/site/src/styles/chapter-reading.css b/site/src/styles/chapter-reading.css new file mode 100644 index 0000000..8c66354 --- /dev/null +++ b/site/src/styles/chapter-reading.css @@ -0,0 +1,125 @@ +:root { color-scheme: dark; --bg:#0d1011; --panel:#151b1e; --text:#f1f3ef; --muted:#b9c2c5; --rule:#384144; --gold:#f1d67b; --teal:#9ed8cb; --mono:'IBM Plex Mono',Menlo,Consolas,monospace; font-family:Inter,Arial,Helvetica,sans-serif; color:var(--text); background:var(--bg); line-height:1.75; -webkit-text-size-adjust:100%; } +* { box-sizing:border-box; } +body { margin:0; } +h1,h2,h3,p,figure { margin:0; } +a { color:inherit; text-underline-offset:.25em; } +a:hover { color:var(--gold); } +:focus-visible { outline:2px solid var(--gold); outline-offset:5px; } +::selection { background:var(--gold); color:var(--bg); } +.reading-shell { width:min(91%,80rem); margin-inline:auto; } +.site-header { display:flex; justify-content:space-between; align-items:center; flex-wrap:wrap; gap:1rem; padding-block:1.5rem; border-bottom:1px solid var(--rule); } +.brand { border-left:3px solid var(--gold); padding-left:.75rem; font-size:.875rem; font-weight:700; text-decoration:none; letter-spacing:-.02em; } +.site-header nav { display:flex; gap:1.4rem; font:.7rem/1.6 var(--mono); text-transform:uppercase; } +.site-header nav a { text-decoration:none; padding-block:.5rem; } +.reading-grid { display:grid; grid-template-columns:14rem minmax(0,1fr); gap:4rem; padding-block:3rem 4rem; } +.course-sidebar { align-self:start; position:sticky; top:2rem; max-height:calc(100dvh - 4rem); overflow-y:auto; padding-right:.5rem; font-size:.75rem; } +.course-home { display:inline-block; color:var(--teal); margin-bottom:1.75rem; } +.course-navigation details { padding-block:.85rem; border-bottom:1px solid var(--rule); } +.course-navigation summary { font-weight:600; line-height:1.5; } +summary { cursor:pointer; padding-block:.3rem; } +.part-message { font-size:.75rem; color:var(--muted); margin:.75rem 0; } +.course-navigation ol { margin:.5rem 0 0; padding-left:1.8rem; } +.course-navigation li { padding:.45rem 0 .45rem .25rem; color:var(--muted); } +.course-navigation a { text-decoration:none; } +.course-navigation [aria-current="page"] { color:var(--gold); font-weight:600; } +.course-navigation small { display:block; font:.6rem/1.5 var(--mono); color:var(--muted); margin-top:.25rem; } +.on-this-page { margin-top:2rem; } +.on-this-page a { display:block; padding:.35rem 0; color:var(--muted); text-decoration:none; } +.eyebrow { font:.7rem/1.6 var(--mono); text-transform:uppercase; letter-spacing:.06em; color:var(--teal); } +.mobile-course { display:none; } +main { min-width:0; } +.chapter-opening { padding-bottom:2rem; } +.chapter-opening h1 { font-size:clamp(2.4rem,4.2vw,4rem); line-height:1.08; font-weight:600; letter-spacing:-.055em; max-width:18ch; margin:1rem 0 1.5rem; text-wrap:balance; } +.standfirst { font-size:1.2rem; line-height:1.65; max-width:61ch; color:var(--muted); } +.chapter-info { margin-top:1.4rem; font-size:.75rem; color:var(--muted); } +.chapter-info summary { width:fit-content; } +.chapter-info p { max-width:75ch; margin-top:.6rem; } +.chapter-body { font-size:1rem; } +.chapter-body section { margin-top:3.5rem; scroll-margin-top:2rem; } +.chapter-body p { max-width:70ch; margin-block:1rem; } +.chapter-body h2 { font-size:clamp(1.6rem,2.2vw,2rem); letter-spacing:-.035em; font-weight:600; line-height:1.25; max-width:32ch; margin-bottom:1.2rem; text-wrap:balance; } +.chapter-body h3 { font-size:1.2rem; line-height:1.4; letter-spacing:-.025em; } +.chapter-body strong { color:var(--text); font-weight:600; } +.chapter-body > p,.chapter-body section > p { color:var(--muted); } +.chapter-body section:first-of-type { margin-top:1.5rem; } +.chapter-body .diagram { margin-block:2rem; padding:1.5rem 1.75rem; background:var(--panel); border:1px solid var(--rule); border-top:2px solid var(--teal); } +.figure-heading { display:flex; align-items:center; justify-content:space-between; flex-wrap:wrap; gap:.5rem; } +.figure-heading small { font:.65rem/1.5 var(--mono); color:var(--muted); } +.chapter-body .diagram-question { font-size:1.15rem; max-width:50ch; margin:1rem 0 1.75rem; } +.system-lane { margin-block:1rem; } +.system-lane h3 { font:.7rem/1.5 var(--mono); text-transform:uppercase; letter-spacing:.04em; color:var(--teal); } +.system-lane ol { display:grid; grid-template-columns:repeat(3,minmax(0,1fr)); list-style:none; padding:0; margin:.6rem 0; gap:1.6rem; } +.system-lane li { padding:.8rem 0; border-top:1px solid var(--teal); position:relative; font-size:.875rem; line-height:1.5; } +.system-lane li:not(:last-child)::after { content:'→'; position:absolute; right:-1.25rem; top:.75rem; color:var(--teal); } +.system-lane li small { display:block; font-size:.75rem; color:var(--muted); margin-top:.25rem; } +.environment-lane h3 { color:var(--gold); } +.environment-lane li { border-color:var(--gold); } +.environment-lane li:not(:last-child)::after { color:var(--gold); } +.chapter-body .exchange { display:flex; justify-content:space-between; gap:1rem; max-width:none; border-block:1px solid var(--rule); font:.7rem/1.6 var(--mono); padding:.85rem 0; margin:1rem 0; color:var(--muted); } +.exchange span:first-child { color:var(--teal); } +.exchange span:last-child { color:var(--gold); } +.diagram figcaption { font-size:.8rem; color:var(--muted); margin-top:1.5rem; border-top:1px solid var(--rule); padding-top:1rem; } +.chapter-body .principle { border-left:2px solid var(--gold); padding:.3rem 0 .3rem 1rem; color:var(--text); font-size:1.15rem; margin-block:1.75rem; } +.finding { border-block-start:1px solid var(--rule); } +.finding:last-child { border-block-end:1px solid var(--rule); } +.finding summary { padding:1rem 0; font-weight:500; } +.finding summary small { font:.65rem/1.5 var(--mono); color:var(--teal); margin-right:.75rem; } +.finding-grid { display:grid; grid-template-columns:1fr 1fr; gap:1.5rem; padding:.5rem 0 1.2rem; } +.finding-grid > div { border-left:2px solid var(--teal); padding-left:1rem; } +.finding-grid > div:last-child { border-color:var(--gold); } +.finding-grid h3 { font:.65rem/1.5 var(--mono); text-transform:uppercase; color:var(--teal); } +.finding-grid > div:last-child h3 { color:var(--gold); } +.chapter-body .finding p { font-size:.9rem; margin:.5rem 0; color:var(--muted); } +.chapter-body .finding .finding-insight { color:var(--text); font-size:.85rem; padding-bottom:1rem; } +.concept-note { font:.7rem/1.6 var(--mono); color:var(--muted); } +.ai-comparison { display:grid; grid-template-columns:1fr 1fr; gap:2rem; margin-block:2rem; } +.ai-comparison > div { border-top:2px solid var(--gold); padding-top:1rem; } +.ai-comparison > div:last-child { border-color:var(--teal); } +.ai-comparison .eyebrow { color:var(--gold); margin:0 0 .75rem; } +.ai-comparison > div:last-child .eyebrow { color:var(--teal); } +.ai-comparison p { font-size:.9rem; color:var(--muted); } +.cadences { border-block:1px solid var(--rule); padding-block:.5rem; margin-block:1.75rem; } +.cadence { display:grid; grid-template-columns:8.5rem 1fr; gap:1rem; padding:.85rem 0; font-size:.85rem; } +.cadence + .cadence { border-top:1px solid var(--rule); } +.cadence strong { font-weight:500; } +.cadence span { color:var(--muted); } +.cadence i { color:var(--teal); font-style:normal; padding-inline:.25rem; } +.cadences figcaption { font:.65rem/1.6 var(--mono); color:var(--muted); padding:.6rem 0; } +.reasoning-check { border-top:1px solid var(--gold); background:var(--panel); padding:1.5rem; margin-top:2rem; } +.reasoning-check summary { font-weight:600; } +.reasoning-check p { font-size:.9rem; } +.chapter-body .sources { font-size:.8rem; padding-top:1.5rem; border-top:1px solid var(--rule); } +.sources ul { padding-left:1.25rem; color:var(--muted); } +.sources li { margin:.5rem 0; } +.chapter-next { border-top:1px solid var(--rule); margin-top:3rem; padding-top:1.5rem; display:grid; grid-template-columns:1fr 1fr; gap:2rem; font-size:.9rem; } +.chapter-next > div:last-child { text-align:right; } +.chapter-next small { display:block; font:.65rem/1.6 var(--mono); color:var(--muted); margin-bottom:.5rem; } +.site-footer { display:flex; justify-content:space-between; flex-wrap:wrap; gap:1rem; border-top:1px solid var(--rule); padding-block:1.5rem; color:var(--muted); font-size:.7rem; } +.skip { position:absolute; top:-5rem; left:1rem; padding:.6rem 1rem; background:var(--panel); z-index:10; } +.skip:focus { top:.5rem; } +@media (max-width:1000px) { + .reading-shell { width:min(90%,56rem); } + .reading-grid { display:block; padding-top:1.5rem; } + .course-sidebar { display:none; } + .mobile-course { display:block; border-bottom:1px solid var(--rule); margin-bottom:2rem; font-size:.8rem; } + .mobile-course > summary { padding:.75rem 0; color:var(--muted); } + .mobile-course .course-navigation { padding:1rem; } + .mobile-course .course-home { margin-bottom:.5rem; } +} +@media (max-width:600px) { + .site-header { align-items:flex-start; flex-direction:column; gap:.6rem; padding-block:1.2rem; } + .site-header nav { gap:1.4rem; } + .chapter-opening h1 { font-size:2.65rem; } + .standfirst { font-size:1.08rem; } + .chapter-body { font-size:.96rem; } + .chapter-body .diagram { padding:1.2rem; } + .system-lane ol { grid-template-columns:1fr; gap:.6rem; } + .system-lane li { padding:.65rem 0 .8rem; } + .system-lane li:not(:last-child)::after { content:'↓'; top:auto; bottom:-.6rem; right:0; } + .chapter-body .exchange { flex-direction:column; gap:.4rem; } + .finding-grid,.ai-comparison { grid-template-columns:1fr; gap:1.25rem; } + .finding summary small { display:block; margin:.25rem 0; } + .cadence { grid-template-columns:1fr; gap:.2rem; } + .chapter-next { gap:1rem; } + .brand { font-size:.8125rem; } +}