# Exploring Elements of Scalable Web Development with your own agent

Choose your own question or start with one of the activities below. The chapters offer a concise narrative; course tasks motivate deeper exploration through your agent and the knowledge graph. Connecting the data, inspecting retrieval, and evaluating the explanation are part of the learning.

## Connect

- [Public MCP server](https://scalableweb.dev/mcp): search and retrieve passages, concepts, connections, activities and demo instructions using a Streamable HTTP client with no authentication. [Connection instructions](https://scalableweb.dev/agents/).
- [Structured graph (JSON)](https://scalableweb.dev/concepts/graph.json): definitions, assumptions, examples, usage notes, explained connections, reading locations, graphics, and demo experiments.
- [Text graph (Markdown)](https://scalableweb.dev/concepts/graph.md): the same authored content for agents that read text more readily than JSON.
- [Visual explorer](https://scalableweb.dev/concepts/): follow concepts and connections yourself.
- [Course-task starting points](https://scalableweb.dev/explore/): choose an optional investigation and give its starting URL directly to your agent.

Use an agent with an HTTP retrieval tool, or download this guide and either graph file and give them to an agent that reads local files. File-only agents can inspect the graph but need the linked reading pages supplied separately to verify the full argument. A chat assistant with no retrieval or file access cannot query these resources simply by being given a URL.

For current publication content, use live HTTP retrieval. Codex's default web search uses a cached index and may report an old response or an unavailable URL. If that reader fails, use a terminal HTTP tool such as `curl` to retrieve this guide and a graph file, then read the downloaded content. A cached-reader error does not establish that the live file is missing. See [OpenAI's search-mode documentation](https://learn.chatgpt.com/docs/web-search#configure-local-web-search).

The guide and graph URLs are public, read-only files: fetch them with HTTP GET or a file reader. The separate `/mcp` endpoint implements MCP. It cannot see private learning records or live browser state. Choose the connection your client supports; both routes use the same authored material.

With MCP, use `search_book` to find a source, then `read_passage` to verify its argument. Use `get_concept` for assumptions, common mistakes and resource IDs; `get_neighbors` for explained connections; `get_activity` for a scenario; and `get_demo` for prediction-led experiment guidance. These tools return context and suggested next actions, not evidence that an experiment ran. Search snippets alone are not a complete passage. Worked reasoning requires an explicit `get_activity` call with `part: "discussion"`, after an attempt or request.

## Your first reply to the student

When the student supplies this guide without a question, retrieve one graph format and help them choose a starting activity. Briefly acknowledge what you successfully accessed, then offer three concrete choices in plain language. Recommend the short experiment if they are unsure and end with one choice question. Keep this reply brief; leave the data contract, full graph, and resource catalog for when they are useful. Do not require the student to formulate a research question or answer a background survey before starting.

After successfully reading the graph, a first reply could be:

> I've read the book's concept graph. Here are three ways we can start:
>
> 1. **Follow your reading.** Tell me your chapter or paste a passage. We'll explore one idea and follow a connection into the book.
> 2. **Connect two ideas.** Try [Queue](https://scalableweb.dev/concepts/#queue) and [Latency](https://scalableweb.dev/concepts/#latency): make a guess about how they relate, then we'll check it against a diagram and a passage.
> 3. **Try a short experiment.** Predict whether a stored response can be reused after its freshness lifetime, then check it in the [Cache decision lab](https://scalableweb.dev/demos/#demo-cache-decision-lab).
>
> If you're unsure, I recommend the experiment. Which would you like to try, or do you have a question of your own?

Adapt the acknowledgement to the material you actually read. If retrieval fails, name the unavailable resource and explain the file-based alternative; do not claim a connection merely because you received a URL. If the student already supplied a question, chapter, or passage, start there and suggest one relevant next action instead of repeating the menu.

Once they choose, retrieve the relevant concept, teaching passage, and resource. Take one step at a time. Ask for their own explanation or prediction before revealing a connection label, model answer, or demo result. For the experiment, use the resource's exact `experiment.predict` prompt and assumptions, wait for their prediction, then guide the `try`, `observe`, and `reflect` steps. Finish by checking a cited passage and inviting them to revise their explanation.

## Start from a course task

For a course task, find a relevant activity in the [exploration catalog](https://scalableweb.dev/explore/index.json) or a concept's `explorationIds`. Retrieve its `agentUrl` and follow that activity's conversation guidance: present the scenario, ask the first relevant question, and wait. A student supplying an activity URL can start directly there without this setup menu. Keep its `discussionUrl` for after an attempted answer or an explicit request for worked reasoning. Help conduct real trials only within granted scope, and distinguish planned work from observed results.

## Data contract

The JSON has `schemaVersion: 2`. Its `revision` is a SHA-256 hash of the authored graph content. Record it when keeping a retrieval trace; URLs identify the current publication, not an archived copy of that revision. Version 2 adds an explicit relationship direction and reviews the endpoint order and linking phrases; version 1 treated every connection as undirected.

- `concepts`: stable `id`, `title`, `group`, `definition`, `assumptions`, `example`, `misconception`, and a `url` for citation. Optional `usage` notes explain vocabulary choices, with sources where available. `contexts` link to specific teaching passages. `readings` lists the broader reading locations.
- `relationships`: `source` and `target` concept IDs, `direction` (`directed` or `undirected`), a short `label`, and an authored `explanation`. Read a directed connection as source → label → target. Comparisons and associations remain undirected. Preserve qualifications such as “can” and the conditions in the explanation; an arrow alone does not establish causation or a prerequisite.
- `readings`: `url`, `title`, and `concepts` discussed there. Two concepts appearing in the same reading are not necessarily connected by an authored edge.
- `resources`: the guide, both graph formats, and the exploration index and catalog. All resource and citation URLs are absolute, including on a local preview.
- `concepts[].resourceIds`: IDs to look up in `learningResources`. These are curated teaching aids, not additional concept relationships.
- `learningResources`: stable `id`, `kind` (`graphic` or `demo`), `title`, `conceptIds`, `url`, `caption`, `assumptions`, and `images`. Every image has a PNG URL and alt text; graphics also have a standalone SVG. Demos include `controls` and an `experiment` with `predict`, `try`, `observe`, and `reflect` prompts. These fields are additive to version 2.
- `explorations`: optional activities with stable `id`, `phase`, `title`, `summary`, `conceptIds`, course `task`, `reading`, `graphUrl`, `url` for independent study, `agentUrl` for starting a conversation, and separate `discussionUrl` for worked reasoning. Concepts carry matching `explorationIds`. These fields are additive to version 2; the catalog deliberately omits worked answers.
- `agentPresentation`: optional predict → interact → explain guidance, with client capability checks, pacing, source fidelity, observation handling, and a browser or conversational fallback. It guides an external agent rather than declaring a supported rendering capability. This field is additive to version 2.
- `readingActivities`: optional versioned activities shared with inline reading experiences. The learning cockpit shares a predict/check/reflect loop for readings, concepts, explorations and selected learning context, plus a versioned activity for every authored demo. Demo activities supply prediction, experiment and reflection prompts, adaptation guidance and explicit browser-snapshot fields. Retrieve it through `get_demo` or this graph. These are authored contracts, not live learner state or additional tool permissions. Obtain actual observations through your own authorized tools or the student.

Definitions and examples use the book's declared assumptions. Some vocabulary is still developing; preserve the usage notes when interpreting it. Example rates are illustrative unless the reading identifies them as measurements.

## Retrieve from the graph

1. Search concept titles, definitions, and usage notes for the student's terms. Report the matching IDs and why they seem relevant. If the question is ambiguous, clarify it with the student.
2. Inspect a concept's assumptions, common mistake, and teaching passages, rather than relying on its title alone.
3. Find incident relationships by checking both `source` and `target`. Follow the other endpoint to expand the neighborhood. Discovery works in either direction, but preserve the original source, linking phrase, target, and explanation when stating a directed relationship. Following an incoming edge does not reverse its claim.
4. Find relevant readings through `contexts`, `concept.readings`, or membership in `readings[].concepts`. Retrieve those pages to check the fuller argument and surrounding qualifications.
5. Return the concepts and connection path used, citations to the concept or exact teaching passage, and any uncertainties. Describe what was actually retrieved.

For a tool that exposes neighbors, the lookup is small:

```js
function neighbors(graph, id) {
  return graph.relationships
    .filter((edge) => edge.source === id || edge.target === id)
    .map((edge) => ({
      id: edge.source === id ? edge.target : edge.source,
      source: edge.source,
      target: edge.target,
      direction: edge.direction,
      label: edge.label,
      explanation: edge.explanation,
    }));
}
```

The same operations can be implemented as local file queries, HTTP-backed tools, or tools in the student's own MCP integration. The graph supplies the evidence; the student's agent supplies the question handling and explanation.

## Return a graphic or experiment

Look up a concept's `resourceIds` in `learningResources`. Each concept has a labelled image of its neighborhood; `graph-complete` provides the full map. Book diagrams and gallery demos are also mapped to the concepts they teach. Choose a relevant aid rather than returning every resource.

Retrieve the chosen PNG with an image-capable tool, then present it with its alt text, caption, assumptions, and source URL. For clients that support remote Markdown images, use `![alt text](PNG URL)`. For Codex with terminal and local image-viewing tools, download the PNG to a temporary local file and open that file with the image viewer; its image output can show the diagram even when a remote Markdown image stays a link. If no image-capable tool or renderer is available, return a descriptive link. SVGs are available for vector-capable clients and download. A text-only retrieval tool may fetch image bytes without being able to inspect or display them; describe your actual capabilities and do not claim to have visually checked an image you only linked.

For a direct image check, open the [Little's Law connection diagram](https://scalableweb.dev/concepts/visuals/graph-little-law.png) or the [cache decision lab's static preview](https://scalableweb.dev/concepts/visuals/demo-cache-decision-lab.png) in a browser. The guide supplies instructions; graphics are separate files. An image that loads there is available, even when an agent's retrieval or display path cannot use it. The Markdown files are served as UTF-8 plain text for URL-reader compatibility. If a URL-reading tool still fails, use an HTTP download tool such as `curl` to read the guide and graph, or use the public MCP server. Report retrieval and display failures separately.

For a demo, show the `experiment.predict` prompt first and let the student state a prediction. Then provide the demo URL, `controls`, and `try`, `observe`, and `reflect` prompts. The PNG is a static preview of the default view, not a recorded result of the student's experiment. Current UI and saved input state can differ. Open the actual demo to check behavior. These links are browser interfaces, not simulation API endpoints; an HTTP fetch does not run their JavaScript. With browser tools, an agent can operate the demo and report the chosen controls and observed output. Without browser tools, ask the student to operate it and bring back observations.

For example, retrieve `cache` and `demo-cache-decision-lab`. Present the graph image and the demo's exact prediction prompt before opening the lab. Select a response profile, vary its age, and compare browser reuse, shared-cache reuse and origin validation under the displayed policy. Preserve the declared freshness and authorization assumptions. Do not treat this authored decision model as evidence of an actual browser or deployed cache.

## Interactive explanations when supported

Follow predict → interact → explain. Interactive presentation supports the conversation; the authored material remains the reference.

Use an interactive explanation only when your current tools and client can render it. Retrieving HTML or having browser tools does not establish inline rendering support. Use the client's supported visualization or artifact mechanism; an HTML code block or a remote page URL alone is not an interactive answer.

Choose one small visual that helps investigate the student's current question. Ask for their prediction or explanation, then wait before revealing results or worked reasoning. Keep the first response brief; an interactive view is optional, not a new setup step or course requirement.

Build from the authored scenario or a retrieved learning resource. Preserve its quantities, assumptions, and relationship directions; label any changed assumption separately. Cite the source and identify the view as an agent-created adaptation. To reproduce a demo's model, inspect its implementation and check representative inputs against the actual demo. Otherwise use a qualitative diagram or the supplied fixture without claiming simulator equivalence. Generated or illustrative outputs are not measured project evidence.

Do not assume that clicks, slider changes, or saved widget state reach the agent. Ask the student to report the controls and observation unless your tools actually expose them. Distinguish their report, your direct observation, and a deduction. After interacting, ask them to explain what changed and check a relevant passage.

Keep the original demo or activity URL available alongside an inline adaptation. If interactive rendering is unavailable or fails, return a relevant image or descriptive link and continue with one conversational question. Let the student operate the browser demo and bring back observations; do not require another client or claim that an HTTP fetch ran its JavaScript.

Possible aids, selected after the student's attempt:

- For caching, use the [cache decision lab](https://scalableweb.dev/demos/#demo-cache-decision-lab) and its catalog assumptions to investigate response age and origin validation.
- For retries, use [the recorder fixture](https://scalableweb.dev/explore/challenge-an-explanation/agent.md) to trace local and durable state across a restart.
- For confidence, use [the classification fixture](https://scalableweb.dev/explore/confidence-before-routing/agent.md) to compare a reported score with reference agreement after the student predicts it.

These suggestions do not add tasks or authorize external actions. Keep the source activity's worked reasoning separate until an attempt or explicit request.



## Keep the investigation inspectable

The student chooses the question and states an initial explanation or prediction. Help them examine it and revise it using the retrieved material. Leave room for them to explain a connection in their own words.

Distinguish the book's definitions and authored connections from your own proposed connections or deductions. A path through the graph is a navigation route, not a logical proof. A missing edge does not prove that two ideas are unrelated.

Cite retrieved material precisely. Do not claim to have checked a reading or external source you have not retrieved. If access fails, say which material was unavailable. If the graph does not directly address a question, explain that gap before making an inference or consulting other sources.

The student should inspect at least one cited passage and record what they accepted, challenged, or could not verify. A fluent answer is an explanation to evaluate, not a grade or evidence of the student's understanding.