Extension and Knowledge Systems

The Repository, Text-Only Production and the Course's Publishing Architecture

How this course's legacy text-only production worked — which file is the editable source, how verified research becomes a complete teaching chapter, and…

Chapter 75Extension and Knowledge Systems

When a short Jira task asks for a complex topic to be explained, it is tempting for an author to ask an agent straight away to "write the chapter". But before any text exists, someone has to establish what has already been explained, which sources have actually been read, how to demonstrate the decision with an example, and where the editable original will live after publication. A course has to survive a change of author, a new product version and a new book format without turning into a pile of unconnected drafts.

This unit looks at three connected decisions: which file is the source of knowledge; how to turn verified research into a complete teaching chapter; and how to take that chapter through review and publication so that the web book never takes the place of the editable text.

Learning outcome

After this unit you will be able to design the text production of a course: from a short assignment and research through to a reviewed chapter in the repository and the derived reader formats. You will distinguish the authoring file, the build and the published site; be able to explain the role of each document and source; and recognise when a claim is verified, when it is merely reported experience and when it is unknown. You will also understand how to take changes through editorial and technical review while preserving local history and the boundaries of responsibility.

Concepts you need from elsewhere in the course: Git as a history of changes, Markdown as a text format, the course outline and prerequisites, the pull request (PR — a request to merge changes into a shared branch), agent instructions and verification of results. The practical examples below are fully worked by the authors; they are teaching explanations, not exercises for the reader.

Sources and formats

The repository holds the editable original

The book's source is a set of text files that you can open, read, change, compare between revisions and restore from Git history. Under the course standard defined in Epic A1M-28 and made concrete in A1M-103, the editable primary source consists of modular Markdown (.md) or Quarto Markdown (.qmd) files. One task corresponds to one topic, but a large topic can have several closely related sub-chapters. A single monolithic file for the whole course makes review and the division of responsibility harder; dozens of tiny files with no teaching reason make navigation harder.

The state of the repository must be tied to a specific revision. The first verified snapshot of main, at commit fa561feca48fd8c1662beee0b13170f27581fc7c from 23 September 2026, contained README.md and the first thirty-one chapter files, but no Quarto configuration and no book build. By the time this text was finalised the course had grown: the main snapshot at commit fde287efd92cedcc13906e9e58e304eebcd87148, checked on 25 September, contains seventy-four chapter files, _quarto.yml, a check that chapters are registered, and an automated continuous integration (CI) process. That process builds HTML (HyperText Markup Language), PDF (Portable Document Format, a document format that preserves layout) via Typst, EPUB (Electronic Publication) and Word documents (.docx), and then stores the result as a temporary artefact. It checks and packages the book but does not publish it to a public site; the repository files examined contain no separate deployment step, and external hosting settings were not checked. The course standard defines modular .md / .qmd files as the editable primary source and the HTML book as the main reading format.

Under the course standard, each class of material has a clear role. The map below shows those roles, but it does not mean that every additional file or directory already exists or must appear immediately:

Material	What question it answers
README.md	What is this course, where is its content, how do I contribute, and where are the current instructions?
Course specification and chapter list	What are the course goals, the order of topics and the acceptance rules?
Jira task	What is the specific learning outcome, content, examples and criteria for a given chapter?
Modular chapter in .md or .qmd	What does the reader need to understand, and why?
Research notes	What questions was the author trying to answer, what exactly did they read, what was confirmed and what remains unknown?
Build settings, for example _quarto.yml	Which files go into the book, in what order, and into which formats are they built?
Built site or book file	What the reader opens after the build, but which is not edited as the primary source

This is a map of functions, not a requirement to create all these files or directories now. A directory name does not create content: add a separate glossary, log, index or style document only when it has an owner and a real need. If two files contain the same rule, decide which one is authoritative and let the other link to it. Otherwise a single edit can fix one place and leave the opposite advice in another.

The repository is not the place for all of a team's knowledge. It does not hold secrets, confidential client data, production extracts, private conversations or claims about a client that are not backed by a permitted source. If a teaching example is invented, say so.

Distinguish the source, the build and the publication

The HTML book has been approved as the main reading format, but it does not become the editable original just because a browser opens it. PDF and EPUB can be additional derived formats. The US Library of Congress gives Electronic Publication as the full name and describes EPUB as a format for digital publications. The World Wide Web Consortium (W3C, the international organisation that develops web standards) EPUB 3.3 Recommendation describes the technical format as a way of packaging structured web content into a container file (Library of Congress: EPUB format description; W3C: EPUB 3.3 specification). All of these formats are generated from text sources and configuration. If a typo is found in a build, it is fixed in the source and the file is rebuilt; a manual edit to generated HTML disappears at the next build.

Quarto Books is the tool this repository uses to build the approved HTML book: it ties individual documents together through project configuration, supports navigation and can produce HTML, PDF, EPUB and other formats. Quarto's documentation gives _book as the default output directory, though a project can specify another (book output settings). In the verified revision of main, the _quarto.yml configuration describes the book, and its list of files sets the order of the chapters. The existing continuous integration process checks the build but has no public deployment step; this check does not establish any external hosting setup. Quarto's documentation on books and on book structure shows how a table-of-contents file ties individual chapters together into one reading product.

The boundary between the editable source, the approved reading format and possible additional outputs can be pictured like this:

Layer	Example	Do we edit it directly?	Role
Editable source	Modular .md or .qmd chapters, including the file for this text	Yes	The primary text for changes and version history.
Book configuration	`_quarto.yml`	Yes, through a separate agreed change	The list of materials, navigation and output settings for Quarto; CI checks the configuration on each PR.
Local build	`_book/` under Quarto's default configuration	No, we regenerate it from the source	A derived result for checking; the same configuration is built in CI.
HTML book	The built HTML and its resources	No, we regenerate it from the accepted source	The approved main reading format of the book.
PDF or EPUB	A file built from the same manuscript	No	Possible additional downloadable formats, if agreed.

Quarto recommends creating a book project with an index page and a list of chapters in the configuration; its HTML book is a special kind of website. At the same time, PDF layout, support for book parts across formats and option names can change. Such details should be taken from the current documentation and checked with a real build, not rewritten from memory.

Publication is a separate layer too. Under the course standard, modular .md / .qmd files are the editable primary source and the HTML book is the main reading format. The current configuration already has a Quarto build, but the verified CI only produces files for review; its settings have no step that deploys a public site. Quarto is the chosen implementation of the book, whereas the location, the owner and the permitted process for a public release have to be decided separately. The built site remains a derived artefact, not the authored text. If hosting requires the built files in a special branch or directory, that must be an explicit agreement about the process. Building and publishing can have separate checks and permissions.

Knowledge documents and agent instructions have different roles

Reference information, product instructions, the authoring process, access control and automated verification are not one mechanism. The README introduces a person to the repository; the course specification holds the shared goals; the Jira task narrows the scope of a specific chapter; the chapter itself teaches; an agent instruction sets behavioural expectations for a specific tool. No text file on its own is a technical barrier against a forbidden action.

Codex currently documents its own global instructions outside the project, repository rules and nested rules with a defined order; there are also override files, fallback file names and a limit on combined size. The official Claude Code documentation describes the separate semantics of CLAUDE.md, rules and reading AGENTS.md. According to the current documentation, Claude Code reads AGENTS.md directly from v2.1.277 onwards, but the conditions depend on whether other instruction files exist, on settings and on the session mode. This is an important example of a product change: you cannot assume that one file name means the same thing in every version and every environment. Codex documentation on AGENTS.md and Claude Code documentation on project memory are current descriptions of these specific clients as of the research date, not a universal standard.

A practical policy for the course: first read the rules that exist in the repository now; do not add instruction files to the structure without agreement; if a shared document is later used by several agent products, check separately how each one finds it, which files it gives priority to, and how to verify the context it actually loaded. Do not duplicate the same long policy in AGENTS.md and CLAUDE.md unless there is a stable way to keep them in sync. A short product-specific adaptation can explain the difference and link to the shared source. Secrets, access tokens and private context do not belong in these files.

Instructions also should not accumulate a history of failures without analysis of the cause. If an agent made a mistake because it did not know the order of the chapters, it is sometimes more useful to add a short rule about where that order comes from than to paste the whole course plan into the root file. If a mistake requires blocking a command or a path, a behavioural reminder may not be enough: you need a separate permissions mechanism, an isolated execution environment (a sandbox) or an automated continuous integration (CI) check. Keep knowledge close to its source and its owner; do not turn every fix into a permanent rule.

Anatomy of a complete chapter

From a question to a clear conclusion

A complete chapter is an argument, not the author's outline. It answers a specific question the reader has, shows cause and effect, and ends with a conclusion that can be applied within its limits. Word count does not prove completeness; a short chapter can be complete for a narrow goal, while a long one can fail to teach anything if it merely lists terms.

A useful sequence:

Situation or question: what practical uncertainty does the reader need to resolve?
Learning outcome: what will the person be able to explain after reading?
Prerequisites: which concepts are already familiar, and which need a brief reminder or a first definition?
Mechanism: how does the phenomenon work, which components interact, and where is the boundary?
Complete examples: the starting situation, the choice of action, the consequence, the explanation, and a failed variant or an alternative.
Limits and trade-offs: when does the method not fit, and what data or conditions does it rely on?
Summary: not a repetition of the headings, but short decisions and signals to recognise.
Local sources and research notes: the reader can trace important claims to material the author actually read.

In a chapter covering several topics, each key block needs its own context and example. The structure of the Jira task sets the minimum requirements, but the author has to weave them into a teaching logic rather than reduce the chapter to an exact copy of the list of items.

An example teaches, but must not become homework

An API (application programming interface) is the way programs agree on requests and responses. To help the reader understand why the list of results from an API request is only part of the contract, the author walks through a complete analysis themselves: names the participants, shows the request and the response, explains the agreed expectations, traces a faulty change and states the limit of the conclusion. After the explanation the author should not write "now describe your own API" — that turns the example into an unfinished exercise.

A short listing needs its conditions, explained fields and expected behaviour. Pseudocode is labelled as pseudocode. Invented data is labelled as invented. If a fragment is taken from an open project, give an exact link to the file or the specific version and respect the terms of use. Never call an example "tested" or "executed" if it was not run.

In every self-contained chapter, new abbreviations are expanded on first use and explained in plain words. For example: "PR (pull request — a request to merge changes)". Product and protocol names that are not abbreviations do not need to be artificially expanded. In the course's original Ukrainian edition, English abbreviations were also translated, and the English names of mechanisms were kept for searchability with a clear explanation in Ukrainian next to them.

The tone should be friendly and precise. Do not replace an explanation with a marketing claim about how fast the agent is, do not turn a complex trade-off into an "always do X" rule, and do not assume the reader has knowledge from an unstated field. Explain a term before the next paragraph relies on it.

Research, books and sources

Start with questions, not with a list of links

Research for a chapter is a short process that produces verified answers:

Which claims need to be proven or limited?
Which type of source best answers each question?
Which version of the product, specification or book edition is current?
Is the full primary material available, or only an abstract, an excerpt or a retelling?
Does an open technical example have specific preconditions and a result?
Which questions remain unknown?

Start with official specifications, product documentation, the author's own materials and original research or engineering reports. For practical experience, check the author, date, context and version, what exactly was reproduced and how it ended. A GitHub PR, issue, discussion or code can show the real history of a decision; a random post or positive reactions do not by themselves prove that a method works universally.

For example, the OpenAPI Specification — a specification for describing a web application programming interface (API) — explicitly defines itself as a machine-readable and human-understandable description of an interface. From this property you can cautiously infer that a formal description can reduce a client's guesswork about the available operations. But one specification does not prove that every implementation conforms to it, or that the schema fully describes the business rules. Those claims need separate checks and sources. This example uses version 3.2.1 of 10 September 2026. OpenAPI Specification v3.2.1

For a technical product, record exactly which product and interface you mean: Codex in the app, in the terminal interface or in the cloud environment; Claude Code, Claude chat or the API. A company name does not imply identical behaviour across all of its products. Prices, availability, model names, configuration paths, release status and the capabilities of specific clients change; go back to the official page as of the date of writing.

Keep a log that lets the verification continue

A research log should be short enough that people keep it updated, and precise enough that the next author understands why a sentence is worded exactly as it is. It can live next to the chapter in a section at the end of the file, or in a separate agreed place if there are many entries. This repository had no separate log structure at the time.

Log field	Example
Question	How does an instructions file differ from a rule that actually restricts a tool?
Material read	Official Codex documentation on AGENTS.md and Claude Code documentation on CLAUDE.md and AGENTS.md; checked on 10 October 2026.
What was confirmed	Specific clients have documented loading semantics; the instruction itself sets context, while a separate setting can enforce restrictions.
What was not confirmed	There is no evidence that all versions, vendors or modes load the same files in the same way.
Consequence for the text	Explain versioning, the product name and the date; do not call AGENTS.md a universal standard.

Record a source immediately after reading it, not at the end of the day from memory. For a page whose content changes, give the access date; for a specification or release, the exact version and release date; for code, a PR or an issue, a direct link to the file, revision or specific discussion when the exact state matters. If a page redirects to new documentation, record the current address and, if needed, the notable change of route.

Do not claim to have read an entire book when the author saw only the blurb or an available excerpt. Material from the author or publisher can support a limited retelling; a short promotional description of a book does not confirm its detailed arguments. If only an article by the author is legally available, give the article's title, its author and the limits of access. Do not invent quotations, page numbers, research findings or bibliographic data.

An idea from a book has to be woven into the reasoning, not left as a single entry in the bibliography. This text uses the E-Myth approach as an analogy: work should run on a repeatable system and must not depend on the memory of a single person. We rely only on an E-Myth article about the roles of technician, manager and entrepreneur; the full text of the book was not read here, and the article is E-Myth material written by Tricia Huebner, not an excerpt that can be attributed to Michael Gerber. In the main text it is an adaptation to the writing process, not evidence about the productivity of AI agents. E-Myth article on the three roles

Organising production and acceptance

A repeatable process for each chapter

So that quality does not depend on what one author remembers, a task passes through visible stages. People can combine roles, but important claims must be checked against materials and evidence, not against how many agents agreed with them.

Stage	Author's decision	Result by which it is checked
Intake	Read the current README, repository instructions, course specification, task description and any available neighbouring chapters. Note what does not exist yet.	Clearly defined learning outcome, scope, prerequisites and criteria; no invented directories or settings.
Research	Turn unknowns into questions and a "claim — source — version/date — limit" table. Read the sources, not just the search results.	Each source supports exactly the claim it is cited for; gaps remain visible.
Plan	Build a logical chain of concepts, define two or more complete examples and explain the chapter's place in the course.	The plan covers all criteria and does not require the reader to do an exercise or know material from later in the course.
Writing	Explain the mechanics in plain words, define terms before using them, add complete examples, mistakes and alternatives.	It is a teaching text, not a new plan, a list of links or a list of terms.
Source check	Verify every changeable fact, version, address, quotation and example. Mark what is unknown.	Links open; the version/date is legible; no claim is stronger than its source.
Technical review	Independently verify mechanisms, conditional calculations, configuration paths and the difference between executed code and illustrative code.	No checks that were not run are described as run; product features are attributed to the exact client.
Editorial review	Check causality, terms, transitions, tone, completeness of examples and links with neighbouring chapters.	A newcomer can understand the decision and its limits without leaving the chapter to look up definitions.
Build check	For the approved HTML book, open a local preview or build exactly the changed formats using the existing Quarto configuration.	Navigation, local links and the build result are checked; the commands actually run and the known gaps are stated.
PR	Show the changes, link them to the Jira task, add a coverage map, sources and dates, the checks actually performed and the uncertainties.	The reviewer can quickly match the text against the requirements and the evidence.
Acceptance and publication	The repository owner reviews and approves the changes. Only an approved process performs public deployment.	No hidden merge or publication from a draft; the current build comes from the accepted revision.

GitHub describes branches as a way to isolate work and a PR as a proposal of changes; the reviewer sees the commits, the files and the difference between the base and proposed versions. For collaborative work, green automated checks are not the only thing that matters: they do not replace a technical and pedagogical assessment of the content. In a PR description for this book it is useful to state the Jira item, the list of files, which criteria are covered, which sources were actually read, when changeable claims were checked, which commands were really run and what has not yet been checked. GitHub: creating a PR and reviewing proposed changes describe the general mechanism; branch protection settings and required reviewers depend on the specific repository. Do not merge or publish changes automatically without proper authorisation.

From local preview to publication

In the repository snapshot of 25 September 2026, recorded at commit fde287efd92cedcc13906e9e58e304eebcd87148, Quarto is already configured in the root _quarto.yml: the project is of type book, the sources are ordered by the course's parts, and HTML, PDF via Typst, EPUB and Word are declared as output formats. The change that introduced this text added its file to the list under the last part of the book; scripts/check-chapters.sh checks that chapter files are registered and exist. This is a concrete implementation of the standard, not an assumption about a future configuration.

In that same historical snapshot, the file .github/workflows/build.yml ran a structure check for PRs and for changes to main, installed Quarto 1.10.18, ran quarto render, checked the output files and uploaded the full book and the individual formats as artefacts retained for 14 days. The verified PR #83 historically built HTML, PDF, EPUB and Word in GitHub Actions in 9 minutes 13 seconds. That is a CI result on that PR, not a local build of this text. The workflow stated explicitly that it published nothing; Quarto's documentation distinguishes building the configured formats from a separately chosen publication step (Quarto: creating a book and publishing basics).

This description applies only to the pinned snapshot: in origin/main, as checked while this edition was being prepared, .github/workflows/build.yml no longer exists. The workflow and artefact retention period described here are therefore a historical example; on their own they do not prove which CI or publication process is in force now. The presence of _quarto.yml proves the configuration of sources and output formats, but not external hosting or an actual public release.

The recorded workflow had three visible states:

The source is being edited: the changes are in the PR branch; the full list of changes and the text are available for review.
Preview artefact: CI builds the formats and attaches them to the run. In this historical process they were used for checking, not as a public site; the artefacts were deleted after 14 days.
Accepted release: after review, merging and the owner's permission, a separate publishing process produces the public version. The pinned workflow had no such step; that snapshot does not establish any external hosting.

Separately, the course owner has to decide who approves public deployment, where permanent copies of editions are stored, and how a preview differs from the version available to everyone. A temporary CI artefact is accessible from a specific run and is later deleted; it does not replace a permanent site or archive.

If, after acceptance, someone edits the HTML on the server by hand rather than the source, the next build will bring back the old text and will not reproduce the fix. If only the PDF is edited, the web book will be left with a different version. If generated files have to be kept in the repository for a particular host, mark them as derived, record how they are regenerated and decide who checks that they match the source. Do not let a text task turn into building a publishing system, configuring a learning management system (LMS) or releasing binary editions.

Maintaining a chapter after acceptance

Maintenance starts from a causal change. If the official documentation has changed, check which claims and examples depend on it; if a mistake has been found, fix the fact and its justification; if only the style is changing, do not rewrite the whole book. After editing the source, check local cross-references and the neighbouring chapters that repeat the same rule. Keep the history of the change in Git and, if it helps the reader, mark the date of currency in the teaching text itself.

In a real documentation repository, a single page can be part of a wider navigation tree and have its own local style, build and preview. The README of the open quarto-web repository describes the published documentation, the local build and preview, and the difference between changing an ordinary Markdown document and a document with computations. It is an example of a living process, not a recommended template to be transferred mechanically into a small course. Pinned README of the quarto-web repository

Its PR #1555 shows that even a small documentation change needs a check of placement and full context: the author proposed a broader explanation of callout block titles — highlighted notes, tips or warnings in the text — and the reviewer discussed whether this material belonged in the language options section rather than on the current page; an automated deployment bot prepared a preview of the site. The PR page was marked as open on the date it was viewed, so this PR shows the discussion process, not proof that this particular proposal made it into the main site. Discussion in PR #1555

For course authors, this is a useful distinction: a reviewer can accept the idea of the content but ask for it to be moved to the right concept, or to clarify which product option it belongs to. A preview helps judge how the page will look, but it does not answer whether the page sits where the reader will find it. This example does not set a norm for all projects and does not prove that the Quarto repository is the right structure for this particular course; it shows the value of review that is tied to the text, the navigation and the actual build.

Fully worked production examples

Example 1: a short task about API contracts becomes a complete chapter

Invented short Jira task: "Explain why a client and a service need an agreed API contract, and what it does not guarantee."

The author's decision. The author first defines the learning outcome: after the chapter, the reader will be able to distinguish an interface description from the behaviour of a live service, name what needs verifying, and assess the consequence of an incompatible change. This is more precise than the generic goal "learn about APIs".

Research questions. What exactly does the OpenAPI Specification formally describe? Which change would break the expectations of an already released client? Under what conditions is an additional optional capability compatible with old clients? What can a schema description confirm, and what has to be checked against the real implementation?

Research and the limits of the sources. The author checks the exact version of the OpenAPI Specification and the official documentation of the tool used. The specification supports a narrow claim: a structured description shows the operations and the expected parts of the request and response. It does not prove that the production service implements every rule described. If the chapter compares the contract with consumer tests, the second mechanism needs its own primary source; the wording should not be derived from the OpenAPI specification alone.

Order of explanation. After defining the concepts, the author explains who creates the contract and who uses it; shows how a structured description sets expectations for the request and the response; analyses a compatible and an incompatible change separately; and finishes with what contract checking can detect and what remains to be checked on the live service. Each case has a situation, an action, a result, an explanation and a limit of applicability.

Complete invented example 1 — an incompatible change. A booking service has a POST /bookings operation. The previous contract requires roomId and a start time, and a successful response contains the booking identifier. The mobile app client already sends requests without a guestCount field. The team wants to add guest counting and makes guestCount required. If server-side validation is switched on before the client is updated, the old request will be rejected and the user will not be able to create a booking. So the author first presents the change as incompatible: the new contract must either keep accepting the old request or requires a coordinated update of both sides and a migration plan. The specification makes the new requirement visible, but by itself it does not prove how the deployed server will respond to the old request; that is checked against the implementation and the client scenario.

Complete invented example 2 — an optional parameter with an unchanged default result. The same system provides GET /bookings to list bookings. The team adds an optional status parameter so that new clients can request only confirmed or only cancelled bookings. In the contract and on the server, the parameter defaults to "all statuses" if it is not supplied. The old mobile client keeps making its previous request without status and receives the same list under the same condition; a new client passes status=confirmed and receives a filtered list. The change is compatible precisely under this invented condition that the default value and the format of the old response are preserved. The conclusion does not carry over to a case where the server changes its behaviour without the parameter or makes it required: then old clients may see a different result or an error.

The reviewer's decision. During the first review, the technical reviewer asks for clarification that the optional status is compatible only if the old default is preserved, and that the schema does not verify the service's actual behaviour. The author adds these limits and separately shows the risk of the required guestCount. After checking the examples against the OpenAPI Specification, the reviewer approves the explanation: it distinguishes the contract, the behaviour of the implementation and assumptions about old clients. The PR includes a map of the short task's requirements, sources with versions, the research date and the build command only if it was actually run. If no Quarto project exists yet, the author says so and does not pass off a Markdown preview as a full book build.

When this approach is not enough. If the topic covers security, idempotency or the business consequences of a repeated request, these two contract scenarios are not enough. The source base and the scope of the chapter must be expanded according to the Jira criteria, or the claim must be narrowed.

Example 2: a book blurb and a Reddit post do not justify a strong conclusion

Invented scenario. The author hypothetically has a short blurb for a book on service architecture and an imagined Reddit post in which one developer speaks positively about restructuring their team; these are not real quotations or links. The author was planning to write: "The book proves that all teams should move to microservices, because delivery becomes faster that way."

The author's decision. These two materials do not support such a claim. The blurb names topics; it does not examine the evidence or the limits of the model. The post describes one team's experience, but without the history of load, the team size, the cost of the transition or an alternative. The author marks the conclusion as unsupported and does not carry it into the chapter.

Next research step. The author looks for the author's or publisher's page, the available table of contents and an original excerpt that may legitimately be read. If only an interview or an article by the author is available, the author does not attribute its wording to the book. The author stops making claims about the book's thesis where the fragment actually read ends. If an analysis of industrial experience is needed, the author looks for a specific primary engineering account with conditions and results, not another generalised opinion.

Log entry. "Checked: the blurb describes the subject; the Reddit post is a single experience without sufficient data for comparison. The claim of general acceleration has not been included. The full text of the book was not available within the research; the book is not marked as read." The Reddit source can stay in the notes as evidence of practical context if its author, date and content matter; it does not have to appear among the chapter's supporting sources.

Why this is right. The number of links does not fix a mismatch between them and the claim. An honest limit is a useful result: the reader learns that a successful example does not make a practice a universal standard, and that a book's thesis cannot be confirmed by its blurb.

When such evidence is good enough. A blurb is fine for a short description of what a book is about; a post can illustrate that one team described its own experience. A recommendation to migrate, an assessment of causality or a conclusion about most teams requires other materials.

Example 3: an official product changed how it loads repository instructions

Invented sentence in a teaching draft: "Claude Code does not read AGENTS.md; add CLAUDE.md to every repository." Such an instruction can survive in a published chapter even after the official documentation has changed.

Signal and check. A reviewer notices a contradiction with the current Claude Code article on project memory. The current documentation says that reading AGENTS.md directly requires Claude Code v2.1.277 or later. By default, Claude reads AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it; when such files exist, the CLAUDE.md files are loaded unless the Project instructions setting has been changed. Before v2.1.281, some sessions — including those on Amazon Bedrock or with telemetry disabled — read only CLAUDE.md; in some sessions AGENTS.md support may be unavailable. The official Codex docs separately describe their own names and order. So what matters is the version, mode and configuration of the specific product, not just the file name.

A bounded update. The author changes the paragraph that claimed Claude always ignores AGENTS.md: restricts it to the specific version and condition; adds a link to the documentation; checks the shared-instructions example that depended on the old rule; and searches the course for other places with the same outdated claim. The material on Codex stays separate and contains Codex's current order; the author does not copy Claude's behaviour into it. The log keeps the date, version, conditions and unknown modes.

Review and publication. The technical reviewer checks the sentence against the current official page and the available version description; the editor checks that the explanation is understandable to a reader who has an older client. The PR contains the bounded text replacement, a map of the claims covered and the result actually checked. If the build is not configured, the PR does not claim an updated site; after acceptance, the permitted process builds it from the source.

When this process is too heavy. If a sentence concerns a stable general idea, such as "versioned history makes auditing easier", there is no need to rewrite it every time a model name changes. Re-verification should focus on the claims whose documentation or environment has changed.

Example 4: a real documentation PR shows a change of placement, not just of wording

In the open Quarto documentation repository, the contribution PR #1555 proposed a better explanation of how to change the titles of callout blocks — highlighted notes, tips or warnings. During review, a maintainer confirmed that the proposed behaviour works, but asked whether it belonged among the language options, which are primarily responsible for internationalisation. He noted that such a setting might require a separate callout: key or documentation for other elements, and compared it with the separate options for cross-references. The PR includes a preview of the deployed site and remains open as of 10 October 2026; it is a discussion of a proposal, not evidence that it was merged.

Summary

Modular .md / .qmd files are the course's editable primary source, and the HTML book is the approved main reading format; PDF and EPUB can be additional outputs.
Quarto is configured to build the book, and CI stores the derived formats for review. The verified automated build process has no public deployment step; external hosting settings were not checked.
The README, the course specification, the topic's Jira task, the author's notes, agent instructions and checks each answer different questions. Do not invent missing structure, and do not duplicate the same rules without an owner.
A complete chapter leads the reader from a question to an explanation and contains at least two finished examples, mistakes and limits; it contains no homework, exercises or mandatory tool installation.
The value of research lies in how well the evidence matches the claim. Keep notes on the sources read, the version, the date, the unknowns and the change that needs to be made to the text.
A PR is the stage at which changes are reviewed; merging and publishing them must be separate decisions by an authorised owner. A preview is not a publication, and a built site is not the manuscript.

Sources and further reading

OpenAPI Initiative, OpenAPI Specification v3.2.1, published 10 September 2026. Supports the definition of the web API description standard and the versioning of the specification. Direct link to v3.2.1. Accessed 10 October 2026.
Quarto Project, Creating a Book. Official explanation of the book project structure, sources, build and output formats. quarto.org/docs/books. Accessed 10 October 2026.
Quarto Project, Book Structure. Confirms the role of the index, the chapter list, parts, the bibliography and book structure options. quarto.org/docs/books/book-structure. Accessed 10 October 2026.
Quarto Project, Customizing Book Output. Current output formats, styles and the default _book directory. quarto.org/docs/books/book-output. Accessed 10 October 2026.
Quarto Project, Publishing Basics. Distinguishes formatted results, the publishing process, services and building in an automated process. quarto.org/docs/publishing. Accessed 10 October 2026.
GitHub Docs, About Git. Explanation of version control and how Git works with GitHub. docs.github.com/en/get-started/using-git/about-git. Accessed 10 October 2026.
GitHub Docs, Best practices for repositories. Recommendations on READMEs, basic repository security features and using branches instead of cross-repository contributions. For specific branch protection rules, required reviews and checks, see About protected branches and Managing a branch protection rule. Main best practices page. Accessed 10 October 2026.
GitHub Docs, Creating a pull request. The official procedure for proposing changes and linking a PR to an issue. docs.github.com/en/pull-requests/how-tos/create-pull-requests/creating-a-pull-request. Accessed 10 October 2026.
GitHub Docs, Review pull requests. Material on reviewing commits, changed files, differences between revisions and feedback. docs.github.com/en/pull-requests/how-tos/review-pull-requests. Accessed 10 October 2026.
OpenAI, Custom instructions with AGENTS.md. Current official rules for loading and layering Codex instructions; the documentation address was redirected from developers.openai.com/codex/guides/agents-md to Learn. learn.chatgpt.com/docs/agent-configuration/agents-md. Accessed 10 October 2026.
Anthropic, How Claude remembers your project. Current explanation of CLAUDE.md, auto memory and the conditions for reading AGENTS.md in Claude Code; the page gives v2.1.277 as the minimum for direct reading, and before v2.1.281 some sessions might not read this file. code.claude.com/docs/en/memory. Accessed 10 October 2026.
quarto-dev, quarto-web README. The living documentation repository's own instructions on rendering, frozen computation state, environments and preview. Pinned README at commit 434822607608036b37673e5ed193be773c1cce74. Accessed 10 October 2026.
quarto-dev/quarto-web, PR #1555: Documentation: Add section about changing titles for callout blocks. Primary record of the proposal, the reviewer's comments and the preview. github.com/quarto-dev/quarto-web/pull/1555. Created 23 January 2025; open at the time of checking on 10 October 2026. Accessed 10 October 2026.
Tricia Huebner, E-Myth, Business Personalities: Entrepreneur, Manager & Technician. Author's material on business roles and systematising work; not the full text of Gerber's book. emyth.com/inside/the-three-business-personalities-entrepreneur-manager-technician. Accessed 10 October 2026.
Library of Congress, EPUB (Electronic Publication) File Format Family, last significant update 6 May 2024. Supports the full name of EPUB and the general description of the container format. Format Description Document fdd000310. Accessed 10 October 2026.
World Wide Web Consortium (W3C, the organisation that develops web standards), Publishing Maintenance Working Group, EPUB 3.3, Recommendation, published 13 January 2026. Confirms the technical description of the format and the container for web content. Exact version of EPUB 3.3. Accessed 10 October 2026.
A1-Marketing-NO, ai_development_course, historical snapshot fa561feca48fd8c1662beee0b13170f27581fc7c (branch main, state as of 23 September 2026). Confirms the early state of the file tree: README and the first thirty-one chapter files, without Quarto configuration. The repository is private; authenticated read access is required. Direct link to the commit. Checked via an authenticated read path on 23 September 2026.
A1-Marketing-NO, ai_development_course, snapshot fde287efd92cedcc13906e9e58e304eebcd87148 (branch main, state as of 25 September 2026, before this text was added). Confirms the presence of seventy-four chapter files, _quarto.yml, the structure check and a full-build workflow without site publication. The repository is private; the sources were checked via an authenticated read path: commit, _quarto.yml, workflow. Checked 25 September 2026.