Learn URL structure with BaseHalf and AI

A URI is easier to check when the five parts live on their own cards, the RFC sits in the same folder, and an agent can see both the notes and the practice answers. We made an ordinary Desktop folder, put six short Markdown notes and a local copy of RFC 3986 into it, and opened that folder in BaseHalf. The window title became url-structure. The sidebar listed every file. Each file became a card. We started Claude Code in the Agent Area on the right, with the practice card selected.

The folder on disk was Desktop/basehalf-learn-sessions/url-structure/. These were the files on the canvas:

url-structure/
  00-goal.md
  01-components.md
  02-authority-and-no-authority.md
  03-percent-encoding.md
  04-practice.md
  rfc3986.txt
  sources.md

What each card held

00-goal.md set the boundary: parse a URI into scheme, authority, path, query, and fragment; tell a URI that has an authority from one that does not; percent-encode a space as %20 under RFC 3986; and check four practice cases against that RFC.

01-components.md kept the five-part diagram from RFC 3986 §3: scheme, authority, path, query, and fragment. The scheme and the path are required; the path may be empty. Authority is present only when the hierarchical part begins with //. The fragment is split off before the rest of the URI is dereferenced; the user agent uses it, not a scheme-specific process on the server. The note also records §1.1.3: a URL is the subset of URIs that also describe how to locate the resource, and this folder stays with the generic syntax and the word "URI".

02-authority-and-no-authority.md wrote the authority as [ userinfo "@" ] host [ ":" port ]. The host is an IPv6 literal in square brackets, an IPv4 address, or a registered name. The user:password form in userinfo is deprecated. A URI does not have an authority just because it contains an @: mailto:[email protected] has no //.

03-percent-encoding.md kept % plus two hex digits, with %20 as the US-ASCII space, and the reserved set that includes +. It also said that treating + as a space is a convention of application/x-www-form-urlencoded, not of the generic syntax.

sources.md linked RFC 3986 (Berners-Lee, Fielding, and Masinter, January 2005, STD 66), with the local copy rfc3986.txt, and MDN's What is a URL?. Those were the sources for the folder, not the model.

Upstream on the practice note

The practice note listed the three concept cards and sources.md in its upstream list. On the canvas, lines from 01-components, 02-authority-and-no-authority, 03-percent-encoding, and sources ran into 04-practice. The file began with:

upstream:
  - 01-components.md
  - 02-authority-and-no-authority.md
  - 03-percent-encoding.md
  - sources.md

That list sticks in the file. Selection does not: it lives in .bh/cache/selection.yaml only while BaseHalf is open. We selected the practice card, and the status bar showed 04-practice, before asking Claude Code to grade it.

The four practice cases

The practice card asked for a short answer and a one-line reason in each case, preferring the cards and RFC 3986 over a remembered rule.

1. Parse the RFC 3986 §3 example foo://example.com:8042/over/there?name=ferret#nose into scheme, authority, path, query, and fragment.

2. Parse mailto:[email protected] from RFC 3986 §1.1.2. Does it have an authority? What is the path?

3. Parse ldap://[2001:db8::7]/c=GB?objectClass?one from the same section. What is the host? Where does the query start, and does the second ? begin a new component?

4. You want the path to contain the two words a and b with a space between them, under https://example.com. What URI does RFC 3986 produce? Is https://example.com/search?q=a+b the generic-syntax encoding of a space between a and b in the query?

Our answers:

1. Scheme foo, authority example.com:8042, path /over/there, query name=ferret, fragment nose. This is the component diagram in RFC 3986 §3.

2. No authority: there is no // after the scheme. The path is [email protected]. RFC 3986 §3.3 uses mailto:[email protected] as the same kind of example, with path [email protected].

3. The host is the IPv6 literal 2001:db8::7, written in brackets, so the authority is [2001:db8::7]. The query starts at the first ? and is objectClass?one. The second ? is data inside the query; RFC 3986 §3.4 allows ? there and does not start a new component.

4. The URI is https://example.com/a%20b. A space is not unreserved, so it is percent-encoded as %20. https://example.com/search?q=a+b is not the generic-syntax encoding of a space: + is a reserved sub-delim. Treating + as a space is a form-encoding convention, not RFC 3986.

What Claude Code actually said

Treat the reply as a draft. In this session Claude Code (v2.1.323, shown in the window as Opus 5.5 with xhigh effort, Claude Ultra) said all four answers were correct, that it had checked each one against the three notes and the local rfc3986.txt, and that it had not edited any files. The run lasted 1 minute 9 seconds. The practice files on disk kept the same timestamps they had before the session.

It walked the first case back to the diagram in §3. For the second, it quoted §3.2: the authority is preceded by //, and this mailto URI has none. It also quoted §3.3 accurately: mailto:[email protected] has the path [email protected], and foo://info.example.com?fred has an empty path. It disagreed with the authority note, not with the practice answer. The note said §3.3 gives mailto:[email protected] the path [email protected]. That mailbox appears only in the §1.1.2 example list; §3.3 uses [email protected]. The conclusion is the same, but the note's citation is loose. We checked the local RFC: that distinction is right.

For the third case it agreed the query is objectClass?one and quoted §3.4: the query starts at the first ?, and ? may represent data inside the query. It said the wording about the host was a little loose. In the RFC grammar, IP-literal includes the square brackets, so the host subcomponent is [2001:db8::7], and 2001:db8::7 is the IPv6 address inside it. We checked that ABNF; the tighter wording is right. It also noted, though we had not asked, that the path is /c=GB.

On the fourth case it agreed with the conclusions and asked for a tighter reason. "A space is not unreserved, so it is percent-encoded" does not follow on its own, because reserved characters are not unreserved either, and they may still appear unencoded. §2.1 says a data octet is percent-encoded when its character is outside the allowed set or is being used as a delimiter, and it uses %20 as the encoding for space. That is the firmer base for the path https://example.com/a%20b. We checked §2.1; the example is there.

It also agreed that + is a reserved sub-delim, and quoted the last paragraph of §2.2: if a reserved character is found in a URI component and no delimiting role is known for it, it must be read as the corresponding US-ASCII data octet. Under the generic syntax, a bare + is therefore a literal plus, and the generic-syntax encoding of a space in that query would be ?q=a%20b. It then flagged a sentence in our percent-encoding note: RFC 3986 never mentions application/x-www-form-urlencoded, and that phrase is not in the local copy. The claim that + is treated as a space under form encoding came from the note, not from the RFC, and should be checked against a source that actually defines that convention. Claude Code said it did not open the MDN link in sources.md. We agree the RFC does not mention form encoding. We had written that sentence from the usual HTML form convention, not from RFC 3986, and we should not have presented it as if the RFC said it.

What this session can and cannot show

Four worked cases are a start, not a complete reading of RFC 3986. We did not walk relative resolution, normalization, or the security notes in §7. The model can misquote a section or a line number; the local RFC is the check, and in this run the section quotes we verified held. A later session can take the same folder, tighten the two notes, and keep going from there.