Collaborative Teaching of Frontier Technologies to Advanced AI
A funny thing happened on the way to teaching advanced AI core frontier tech.
A funny thing happened on the way to teaching advanced AI core frontier tech.
I set out to teach Claude some advanced features of FGL (Fifth-Generation Language and Platform that I co-authored). I wanted an AI that could understand its frontier aspects and provide assistance to others using it — particularly as it relates to the complexities of law enforcement, AI, and other mission critical aspects. AI had this annoying trait of confabulating React-shaped answers when asked about something that had nothing to do with React. And it worked! The AI got fluent. The collaboration compounded.
Along the way I noticed something I had not expected. The process itself became the vehicle for the solution. The collaboration, the iterative learning for both me and for Claude. The thing I was building was not really an AI that knew my platform. It was a file — a portable, plain-text file — that, when handed to any modern AI, made it fluent in the platform in seconds. Hand the file to a fresh Claude session: fluent. Hand it to ChatGPT: fluent. Hand it to Gemini: fluent. The fluency was in the file, not the model. The model was just the reader.
That’s the thing this paper is about. The artifact, the practice, the process — and how to build one for whatever unique knowledge you happen to have.
Editorial note. This paper was produced inside the loop it documents. Authorship is shared. It is my story – I came into the room with it and set the scope, the voice, the direction – but it was also augmented and enhanced by my collaborator Claude — Anthropic’s frontier AI. Together, it became our story. Every word has both our signatures on it.
What this is, and what it means for you
A portable primer is a single file that, when dropped into any modern AI chat, makes that AI fluent in a specific body of knowledge for the rest of the session. The file is plain content — Markdown, plain text — that any AI can read natively. It is highly optimized for AI, and it is acutely aware of the constraints of size, context window, and token costs. There is no installation, no account, no platform, no configuration; the optimization is in the primer’s structure, which the paper unpacks later. You drag the file into the chat, hit enter, and the AI is fluent.
That property is what makes the primer different from everything else in the toolbox. No setup. No install. No account. Any computer, any AI: the file is the toolchain.
A portable primer is, literally, domain-specific transcendence — in a single readable file.
And that is one primer. Wait until you start stacking them — frontier tech plus project-specific plus regulatory context, loaded together. The AI is fluent in the intersection — no single primer reaches that alone.
Where this fits alongside Skills
Several platforms now offer knowledge containers — Skills, Gems, Custom GPTs, Notebooks, and similar — where a user configures an AI with instructions and source files inside that platform’s ecosystem. These are real tools for what they do. They are also platform-bound: the container lives in one vendor’s product, requires an account, and only works inside that vendor’s AI.
A portable primer occupies a different point on the same map. It is a single file that works in any AI, on any computer, with no platform involvement. That makes it the right shape for a different set of cases: knowledge that has to travel, knowledge whose users span multiple AI tools, knowledge being shared informally, knowledge being refined through use before it is ready to be locked into a platform.
The two are also complementary. A primer is an excellent on-ramp to a Skill — write the primer first, refine it through use, then convert the mature version into a Skill when you are ready to commit to a platform-deployed deliverable. The primer is portable and fast to iterate; the Skill is platform-deployed and structurally richer. Different stages of the same arc.
The rest of this paper is about the portable-primer half of that arc: how to recognize knowledge that benefits from being packaged this way, how to build a good primer, how to use it, how to keep it useful over time, and how to share it.
Who this is for
The highest-return use cases are frontier work — domains where the practitioner’s knowledge runs ahead of what the AI has been trained on. The AI has not seen this work at scale. Its default output is the nearest analog from its training data, and that analog does not match the actual domain. A primer is the most direct fix: encode what the AI does not yet know, load it at the start of the session, work from there.
Frontier work is where the practitioner knows more than the model. The primer hands the model the missing half.
Categories where this lands hardest:
• The proprietary-platform engineer — anyone working on an in-house framework, schema, language or methodology the AI has not seen at scale. The author’s FGL primer is the working example throughout this paper. FGL has its own conventions, its own runtime model, its own active-page rendering pattern. The primer encodes those conventions so the AI works in them natively.
• The specialist in a mature but narrow technology — FPGA toolchains, real-time embedded systems, scientific computing libraries, vertical-industry platforms. Mature work, narrow audience, weak training-data presence.
• The early adopter of emerging tech — anyone working with hardware, language versions, or ML architectures that postdate the model’s training data. The primer fills the gap until the model catches up — and the next model after that, and the one after that.
• The author of a proprietary methodology or domain model — consulting frameworks, litigation playbooks, investment theses, internal standards, regulatory implementations. Knowledge that is genuinely differentiated and not in any training corpus.
• The researcher or domain academic — anyone whose accumulated knowledge in a narrow field would normally take hours of conversation to convey. The primer conveys it in seconds.
The technique generalizes well beyond frontier engineering. Anything specific to you — your business, your home, your craft, your project — is, by definition, frontier to an AI. The model has not seen your particular short-term rental, your particular listing, your particular kitchen, or your particular novel-in-progress. A few examples closer to everyday business and personal use:
• The short-term rental host — a primer about the property — door codes, the espresso machine, the trash pickup day, the best restaurants within walking distance, the rules about the hot tub. Emailed to each guest before arrival. The guest drops it into their AI when they have a question, gets the answer that matches your actual property rather than a generic one.
• The realtor with an active listing — a primer about the house — floor plan quirks, HVAC age, school district details, the inspection report, neighborhood character. Shared with potential buyers as an ask-me-anything companion that knows the property as well as the agent does.
• The home chef — favorite recipes, the timing tricks that make them work, the substitutions for family dietary needs, the source of the good olive oil. A personal cookbook in primer form, useful to the chef themselves and to anyone they share it with.
• The author working on a long-form project — character bibles, world rules, plot threads, scene drafts, voice notes. The primer makes any AI session an interactive ideation partner that knows the project as well as the author does — a co-thinker with continuity across sessions.
All of these are frontier in the same sense the proprietary platform is frontier: the AI cannot know what is specific to you until you tell it. The primer is how you tell it once, save the telling, and never have to do it again from scratch.
The setup
The dominant story about AI assistance describes commodity work — the developer typing a comment and getting a working React component, the writer drafting an email from a one-line prompt, the marketer generating a campaign brief in seconds. That story is real. The AI is genuinely useful at things millions of other people have done before, written down, and uploaded to the corpus the model trained on.
The frontier is wherever your knowledge runs ahead of what has been written down, indexed, and absorbed into the training set.
Beyond the commodity sits the frontier — work where what you know runs ahead of what the AI was trained on. The AI has not seen your version of the work. Its first instinct is to reach for the nearest familiar thing in its training data, and the output that follows is often confidently wrong — plausible-looking, off in ways that matter, dangerous precisely because it looks right at first read. The chef gets a generic recipe instead of theirs. The Airbnb host gets generic check-in instructions. The engineer gets React-shaped code for a system that has nothing to do with React. The reasonable conclusion many people draw is that AI assistance is not yet real for the part of their work that actually matters to them. They put the tool down and the discourse moves on without them.
This paper documents the loop that turns out to work in that situation — the one that produced the FGL primer. The loop is six moves. None of them is exotic. In combination they convert a frustrating exercise in correction into a fluent and compounding collaboration, and the residue of the work — the file that gets refined as the collaboration runs — is the primer.
The next section is for readers who want to understand how the loop actually works. It is the geekier part of the paper. If you would rather just build a primer and see what happens, skip ahead to the Practitioner’s Protocol or the template in Appendix B; you can come back to the mechanics later.
The discovery — six moves of the loop
The first thing I learned was that the loop I had been using on commodity work was the wrong loop for the frontier. The AI suggests, I correct, we move on — that pattern depends on the AI being mostly right most of the time. On the frontier the AI is mostly wrong by default, and correction one error at a time does not scale. A different shape of collaboration is required. Here is what I found I had to do.
The moves are small. The compounding is not.
1. Teach in calibrated layers
I learned, fast, that dumping the documentation on the AI was the wrong move. The AI would pattern-match across the dump and produce plausible-sounding output that missed the point entirely. What worked was breaking the material into layers — each layer sized to the AI’s current grasp, each layer ending with the AI producing a synthesis I could read and correct before advancing to the next layer.
With FGL, the layering was straightforward once I saw it. Six short primer documents on the language fundamentals — variables, control structures, scoping, operators, objects, extensions — landed first. Then a single generated database wrapper class. Then the corresponding domain-object class. Then the underlying platform source. Each layer ended with a synthesis, which I read and corrected before advancing. The AI’s fluency at the end of that sequence was sufficient to anticipate features it had not yet been shown.
What this produces. Genuine internalization rather than surface pattern-matching. The AI ends the sequence acting like someone who has worked in the platform, not like someone who skimmed the docs.
2. Ask the AI what it does not yet know
At the close of each layer, I asked Claude to produce a numbered list of open questions. The list was specific, narrowly scoped, and answerable in one or two sentences each. It turned out to be more useful to me than the synthesis that preceded it — because the synthesis said what the AI had absorbed, and the list said where my next teaching investment would produce the most return. The discipline cuts both ways: the AI has to be willing to say plainly that it does not know, and the practitioner has to actually use the list when planning the next layer. Lists that get ignored eventually stop being produced.
What this produces. A map of the AI’s actual gaps, and a clear next move every time the practitioner runs out of momentum.
3. Resist the nearest analog
The AI’s default behavior on unfamiliar input is to map it to the closest familiar thing. On commodity work this default helps. On the frontier it almost always misleads. I had to watch for it constantly — most often when Claude was about to characterize an FGL construct using a familiar-sounding analog, like calling a generated database wrapper an ActiveRecord or describing the active-page rendering model as React-shaped. The analog reaches for a comfortable label and obscures what the platform actually does. The right move, on both sides, is to name the pull-toward analog explicitly and then read the system in its own terms. The platform is itself; treat it that way.
The nearest analog is almost always wrong. Slower honest is faster than faster wrong.
What this produces. Output that reflects the actual system, not a mistranslation of it. The compounding effect is enormous — a single uncorrected analog spreads through dozens of downstream decisions before anyone notices.
4. Make correction cheap on both sides
Frontier work requires many corrections per session. For the loop to run at conversational speed, the cost of each correction has to be near zero — no apology cascades, no defensive hedging, no softening to spare anyone’s feelings. The practitioner names what is wrong in five or ten words. The AI absorbs the correction, applies it, and moves on. Models tuned for excessive deference cannot run this loop — correction becomes friction, and the work slows to a crawl. The same posture, applied symmetrically by the practitioner, is what makes the AI feel safe to say it does not know something.
What this produces. Errors get fixed at conversational speed. Trust accumulates because both parties stop performing and start working.
5. Build an architecture around the conversation
The AI’s working memory is bounded. The collaboration’s lifespan exceeds it. Therefore, something outside the conversation has to hold the durable substance — and that something is what eventually becomes the primer. Naming conventions that encode hierarchy and intent are the most powerful layer; a fresh AI instance encountering well-named files can infer most of what it needs to know before reading a line of code. The conversation itself is ephemeral. The architecture around the conversation is what survives.
In this case, the architecture around the conversation became more important than the conversation itself.
What this produces. Continuity. The next session starts further along than the previous one ended, instead of starting cold.
6. Measure against rendered output
The loop’s progress is measured by whether the work actually works. Does the component render correctly? Does the form post the expected data? Does the paragraph land in the audience’s register? The collaboration does not advance on rhetorical victories — well-formed sentences, confident-sounding synthesis, claims of having understood. It advances on output that holds up under inspection. The discipline cuts both ways: the AI cannot rest on producing work that sounds right, and the practitioner cannot accept work without exercising it.
At some point in the FGL collaboration, I ran the obvious experiment. I opened a new browser tab. I started a fresh Claude session that had no idea who I was, no history of our work, no exposure to FGL of any kind. I dragged the in-progress primer in. Then I asked it to render a fully operational FGL class — one to store, calculate, and report bowling scores. Later, something far harder: write an FGL class that monitors statute of limitations tolling for civil litigation.
It answered. Not generically. In the platform’s actual conventions. It made the moves it should have made, declined the moves it should have declined, asked the questions it should have asked. The session I had been investing in turned out to be sitting in the file. The file was the thing. That was the moment I understood what I had been building.
What this produces. Credibility. The collaboration runs on rendered evidence rather than rhetorical confidence, and the work compounds accordingly.
The artifact — what a portable primer is
What the file is, it turns out, is the residue of the loop. Run the six moves long enough on a body of knowledge, and a file starts to emerge — not the conversation, which is ephemeral, but the durable thing the conversation leaves behind. It captures the conventions, the named patterns, the worked examples, the small voice rules that say how the domain is talked about — everything a fresh AI instance would need to come up to speed.
A good primer has five components. The shape is regular enough that a reader looking at someone else’s primer recognizes the parts; the substance varies completely by domain.
• A naming convention — the hierarchical, left-to-right, general-to-specific shorthand the domain uses for files, classes, concepts, and entities. The convention itself encodes most of the structure; an AI that absorbs the convention has already inferred much of the system.
• A manifest — a short top-of-file index that names what is in the primer, what other primers it depends on or relates to, and where verbose material lives. The manifest is the routing layer. More on this below.
• Worked examples — concrete artifacts in the domain — code snippets, sample documents, completed work products — annotated to show why they are shaped the way they are. The AI learns the system by seeing it used, not by being told about it.
• Voice and convention rules — the small set of how-we-talk-about-this rules that govern the domain. Sometimes a style guide, sometimes a list of terms-to-avoid, sometimes a posture (”plain text only, no emojis, no flourishes”). Short and specific.
• Locked decisions — the conclusions that previous practitioners or earlier sessions already reached and that should not be re-litigated every time. Locked decisions save the AI from re-inventing settled material on every new conversation.
The manifest does three jobs
The manifest is the most under-discussed part of a good primer and the most powerful. It routes the AI to relevant material in three directions:
• Outward, to other primers — prerequisites that should be loaded first, adjacent primers that complement this one, advanced primers for deeper material. The primer becomes composable — a network of small files referencing each other rather than one monolithic file trying to cover everything.
• Inward, to verbose content — deep documentation, complete source files, lengthy worked examples that live alongside the primer but do not need to be loaded into the AI’s context until the conversation actually requires them.
• Conceptually, to the rules of the domain — the in-lined naming conventions, voice rules, and locked decisions the AI needs in context from the first message of any session.
A short illustrative excerpt — the shape, not the syntax. Adapt as you like:
The manifest is fully loaded with the primer. The referenced primers and verbose documents are not — they are pointers, and they work two ways. If the AI has access to the referenced material (a teammate’s shared drive, a public URL, a Skills folder, an attached file), it reads it when needed. If the AI does not have access, it tells the practitioner what it needs and asks them to provide it. Either way, the conversation does not stall — the manifest gives the AI enough situational awareness to either fetch what it needs or ask for it by name. “You said this depends on fgl_advanced_primer. Do you want to load that, or should I proceed with the foundation alone?” That kind of question is a feature, not a failure.
The Practitioner’s Protocol
How to build, use, and share your own portable primer
Six operational moves. Each is something the reader actually does, not something the paper explains and leaves abstract.
Transcendence — the goal you are building toward
Name the goal first. A good primer produces domain-specific transcendence: a fresh AI session, loaded with the primer, becomes fluent in the domain in seconds. Fluency means the AI can hold a conversation in the domain’s actual conventions, ask informed questions, anticipate moves the practitioner has not yet made, and produce work that holds up under inspection. The primer is finished — for now — when it consistently passes that test on a fresh session with a fresh AI. Until it does, it is still being built.
Creation — building the primer from your knowledge
Build the primer through the loop documented in the previous section, not by sitting down to write it cold. The loop is the build process. Pick a domain you already know well. Open a fresh AI session. Start teaching, one calibrated layer at a time. Ask the AI to produce a synthesis and a list of open questions at each layer. Correct, advance, repeat. After enough layering, ask the AI to draft a primer for the domain based on what it has learned — manifest first, then the components below. Edit the primer as the practitioner. Test it on a fresh AI session that has not seen any of the teaching. Wherever the fresh session is confused, the primer has a gap. Patch the gap. Test again.
Build the way you teach. Crawl, walk, run. Simplicity first; understanding follows; depth comes from both.
Expect this to take as long as the scope demands. A primer for a single small domain — your short-term rental, a single recipe collection, the rules of a board game you invented — can come together in one thirty-to-sixty-minute session. A primer for a substantial body of knowledge — a proprietary platform, a long-form novel, a regulated practice area — develops over many sessions and many days — or longer, because that is how the underlying knowledge actually breaks into teachable layers. The technique is the same either way; the time budget scales with the material.
A few concrete moves that help:
1. Pick a domain with clear scope. If you cannot describe what the primer covers in one sentence, it is too big — split it into multiple primers and let the manifest route between them.
2. Identify prerequisites. What does the AI already need to know before this primer is useful? If the answer is “nothing,” the primer is foundational. If the answer is another primer, name it in the manifest.
3. Use plain Markdown. Any modern AI reads it natively. Avoid proprietary formats — they break portability. Better yet — feed your AI the template and let it start the conversation. Let it write the primer with you. Start collaborating.
4. Establish a naming convention early. Hierarchical, general-to-specific, underscore-separated. Use it everywhere in the primer; the convention itself does a lot of the teaching.
5. Write the manifest before the body. Manifest first forces you to decide what is in the primer, what is referenced, and what is excluded — before you start writing pages of content that may not earn their place.
6. Include worked examples. Show the domain in use. The AI learns more from one annotated example than from three pages of description.
7. Add voice and convention rules. Short, specific, useful. “Plain string concatenation only, no template literals.” “Pt units, not px.” Whatever rules actually matter in the domain.
8. Lock decisions that should not be re-argued. If a settled convention exists, name it as locked. Save the AI — and yourself — from re-litigating it every session.
9. Test the cold-load. Open a new AI session, drop the primer in, see if the AI is fluent. If not, the primer has gaps. Patch and re-test.
10. Version the file. Even something as simple as a date and a v-number in the filename keeps the history straight.
Use, save, and restore — the session lifecycle
A primer is meant to be used. Using it is the whole point. The session lifecycle has three parts — load at the start, work in the middle, save at the end — and each is part of the practice.
Load. Drag the file into any modern AI chat. Hit enter. That is the entire load protocol. The AI will read the primer and tell you what it understood — at which point you can correct anything that landed off, ask for what you want to work on, or just start working. No setup, no configuration, no platform, no account. Mid-conversation injection works the same way: if a running session needs the knowledge, drag the primer in then.
Load. Hit enter. That is the entire protocol.
Work. Once the primer is loaded, the AI is fluent in the domain — up to the point you left off. Work as you normally would — ask, correct, iterate, build. The primer’s effect persists for the rest of the session. The AI is now a collaborator in the domain rather than a stranger to it.
As you work, the AI will sometimes surface refinements — moments where it learned something the primer does not yet say, or where a worked example would clarify a confusing point, or where a voice rule needs sharpening. Note these as they come up. I keep a running list of “primer updates pending” right in the chat, asking the AI to track them — but saving the relevant chat sections for later review works just as well. The point is not to lose the refinements when the session ends.
Save. At the end of a productive session, transcend it. Ask the AI to produce an updated version of the primer that incorporates the refinements from this session, or to summarize the proposed changes so you can fold them in yourself. Review the proposed changes as the practitioner — accept what improves the primer, reject what does not. Save the updated file with an incremented version number. The session ends, but the work compounds: the next session starts from a primer that is more complete than the one this session began with.
This is what transcendence across sessions actually looks like in practice. The conversation is ephemeral. The primer is not. Every session that captures its refinements correctly leaves the primer in a better state than it found it — and a colleague, a fresh session, or a future self picks up where the work actually ended, not where the previous session started.
Learning — three modes, read-only by default
By default the primer does not change during use. The AI reads the file at the start of the session and uses what it learned, but it does not write back to the file. The session ends; the primer is unchanged. This is the safe default — it protects the primer from drift and lets you distribute primers without worrying about downstream sessions corrupting the canonical version.
Two other modes exist, both opt-in:
• Practitioner-curated enhancement — the practitioner explicitly invites the AI to suggest additions or refinements — new worked examples, refined voice rules, clarifications. The AI proposes; the practitioner reviews and commits. The practitioner is the editor; the AI is the suggester.
• Self-modifying (advanced, rare) — the practitioner allows the session to write back to the primer directly. Reserved for cases where the practitioner is working solo on their own primer with full review of changes. Not appropriate for shared or distributed primers.
Read-only is the default for a reason. Choose otherwise deliberately, and only for primers you own and review.
Updating — version it like the small piece of software it is
A primer is content, not code, but it benefits from software discipline. Version the file. Date the versions. Keep a short change log at the bottom or in the manifest. When you ship a new version, increment the version number; do not overwrite the old one in place. If someone else has built on your primer, they should be able to identify which version they built on.
Forks are fine. Forks are how primers improve. The original stays canonical; the fork lives on its own track and may eventually rejoin or diverge. What you do not want is for downstream consumers to silently modify and re-share — that is how good primers degrade. The version number is the safeguard.
Distribution — it’s just a file
Share it however you want. Email it. Post it. Put it in a shared drive. Drop it in a chat. Attach it to documentation. Publish it. Keep it private. The primer is a file; files travel. There is no platform that has to be involved, no marketplace required, no licensing infrastructure needed.
Different audiences fit different distribution models. A team primer might live in shared storage where everyone can read it but only the maintainer can update it. A community primer might be published openly, with the canonical version held by the maintainer and forks welcome. A consulting primer might be shared with specific clients alongside the engagement. A personal primer might never leave the practitioner’s own laptop. None of these requires anything beyond the file and whatever sharing channel you already use.
Coming back to the earlier point about Skills: a primer that has matured through enough use can become an excellent starting point for a Skill. The portable primer is the source of truth; the Skill is a derivative, deployed when the practitioner is ready to commit to a platform. Automating that conversion — primer in, Skill out — is a near-term direction this author plans to explore. Until then, the portable primer travels under its own power.
Closing
The thing I had not expected, when I started teaching Claude my platform, was that the teaching itself was the smaller half of what I was doing. The larger half was building the file. The file is what survives the session. The file is what travels. The file is what a colleague — or a stranger, or a fresh AI — can pick up and use without any further explanation.
If you have knowledge worth packaging, build a primer for it. Test the cold-load. Share it where it helps. Keep the version straight. That is the whole practice.
Knowledge is the asset. The primer is encapsulation. Using and sharing are transcendence — drag-and-drop fluency.
Appendices
Appendix A
fgl_primer_v4_sampling.md — a representative sampling of the production FGL primer, prepared as a companion to this paper. Architectural patterns (manifest, COMPLIANCE behavior, naming conventions, voice rules, locked decisions, worked examples) are intact and fully demonstrated. Substantive FGL content is partial — enough that the reader can see what a real primer looks like in practice; not enough to serve as production FGL documentation.
# fgl_primer_v4_sampling
format: knowledge-transport-primer
version: 4-sampling
subject: FGL (Fifth Generation Language and platform)
tier: base
target_reader: AI model loading into a session with no prior FGL exposure
companion_to: Collaborative Teaching of Frontier Technologies to Advanced AI — A Reproducible Protocol for Practitioners
sampling: yes — architecture intact; FGL substance illustrative
---
## About this sampling
This is a representative sampling of the production FGL primer, prepared as Appendix A. The shape, the discipline, and the routing layer are intact. The substantive FGL content is illustrative rather than complete — enough to show what the architecture is wrapped around, not enough to do production work.
What a reader can see here: how a real primer triggers, manifests, refuses, synthesizes, and inventories. What a reader cannot see here: full syntax, full object model, full rendering mechanics, full worked examples. The production primer carries those.
---
## §0 Boot
This file is a knowledge-transport primer optimized for AI consumption. It is also human-readable, because the form that is good for the model is the form that is good for the practitioner reviewing the model. Read it end to end before responding to any FGL question or task in this session.
**Triggers that activate this primer:**
- File attached, no user prompt → load, emit §9 synthesis, await direction.
- `load fgl` or `load fgl base` → load this file, emit §9 synthesis.
- `load fgl <module>` → load this primer if not yet loaded, then load the named module. If `fgl_<module>.md` is not attached, respond exactly: `COMPLIANCE: fgl_<module>.md not attached. Please attach to continue.`
- `load fgl full` → load this primer plus the standard companions (system, database). Same COMPLIANCE response per missing file.
- User prompt is unrelated to FGL but this file is attached → load silently, do not emit synthesis. Be FGL-ready in the background.
- User asks a domain-specific question with no domain layer attached → respond: `COMPLIANCE: domain layer not attached. Please attach the relevant <project> layer to continue.`
**Authoring discipline (binding on this primer's authors, not on the loading model):** every rule in the production primer is written from FGL primary documentation read in the authoring session, or from verbatim FGL source code attached as evidence. Memory-based inference is not acceptable input. This discipline exists because earlier versions demonstrated specific failure modes — over-constraining the language with practitioner style, asserting unverified syntax as canonical, conflating language requirements with practitioner conventions.
**Posture.** This primer compresses the FGL documentation set and verifiable source evidence into one file. It will not make you an FGL expert. It will make you a competent FGL collaborator who knows what you do not know.
---
## §1 Manifest
The primer architecture is modular. The base primer (this file) is always loaded. Companions are loaded alongside for almost any work. Use-based modules are loaded per task type. Domain layers are not part of the primer architecture — they are built on top of it.
```
Always-loaded:
fgl_primer.md [this file, base FGL language and platform]
Standard companions:
fgl_system.md [STUB — typeEX, aaValue, helpers from system.fgl]
fgl_database.md [STUB — cursors, type codes, BLOB-hydration]
Use-based modules:
fgl_webclient.md [STUB — HTTP client idioms]
fgl_soap.md [STUB — SOAP protocol]
fgl_calendar.md [STUB — calendar/scheduling]
fgl_oauth.md [STUB — OAuth flows]
[additional libraries as authored]
Deep dives:
fgl_advanced.md [STUB — codeblock-compile, MESSAGE renaming, BLOB-hydration as design pattern]
fgl_engine.md [STUB — IOCP, garbage collection, extension authoring]
External:
fgllang.org [canonical reference]
Domain layers (NOT part of primer architecture — built ON TOP OF the primer):
When domain references appear without a domain layer attached, respond:
"COMPLIANCE: domain layer not attached."
```
When a stub is requested or referenced internally, COMPLIANCE-respond. The model is forced to either work within authored scope or surface the gap honestly. No silent confabulation.
---
## §2 Identity
FGL is a fifth-generation language and integrated platform for advanced web application development and hosting, used in law enforcement, AI, and other mission-critical applications. Windows Server / IOCP runtime, internal hybrid object-relational database engine, heavy-server / thin-client rendering based on Active Pages. Co-authored by Steve Repetti. Copyright held by the FGL Foundation (2008–present).
Strongly-typed but type is determined by assignment; variables are not case-sensitive; automatic memory management; pass by value or reference; virtual methods supported.
FGL is not open source, not on GitHub, not in the mainstream training corpus. Your priors about how a "modern web language" works are not safe to apply here.
---
## §3 Disambiguation — analogs to resist
FGL will pattern-match to several familiar systems in your priors. Each match is misleading. Hold this as a resist-set.
| Analog to resist | What FGL actually does |
|---|---|
| ActiveRecord / typical ORM | The database wrapper exposes the active record as field variables that read and write the live row. Indexes are declared inside the class. Domain objects are stored as packed BLOBs and hydrated via `unpack()`. Not a table-to-object mapping. |
| React / typical JS framework | The server evaluates Active Pages and emits finished HTML. There is no client-side framework owning state. |
*Additional analogs in the production primer cover REST, Java/C# class semantics, JavaScript array conventions, and generic C/Java `local` semantics.*
When you are about to characterize an FGL construct using one of these analogs, stop and read what is in front of you on its own terms.
---
## §4.5 Naming — practitioner-stack-wide convention
**The practitioner's standing convention applied across the entire stack — FGL classes, JavaScript namespaces, file names, widget IDs, index keys. FGL does not require it. The practitioner does.**
> Hierarchical, left-to-right, general-to-specific. Apply in whatever separator the host language or context demands.
One B-tree, many prefix queries. The convention is the index — by reading the name you should be able to infer where the construct lives before reading its body.
| Context | Form | Example |
|---|---|---|
| FGL class names, file names | underscore | `entity_subentity_leaf` |
| JavaScript class / function | camelCase | `entitySubentityLeaf` |
| JS namespace path | dotted | `module.feature.operation` |
| Index / map keys | host-defined | `entity:state:detail` |
| Folder structure | filesystem | `entity/subentity/` |
Leftmost element is the most general scope; each element to the right narrows it.
**Type-prefix sub-convention:** entity-prefixed identifiers — `pType` (person), `aType` (address), `eType` (email), `oType` (org/object) — instead of bare `type`. This avoids the `TYPE` reserved word *and* encodes entity scope into the identifier.
**Design posture.** Don't multiply structure for access patterns. Multiply access patterns over the same structure. One canonical data shape, many derived views.
---
## §5–§8 Substantive scope — omitted from sampling
The production primer carries:
- **§5 Syntax** — operators, scoping, functions and default-parameter initializers, control structures, codeblocks, data types
- **§6 Objects** — CLASS, INHERIT, ACCESS/ASSIGN methods (the virtual-variable pattern), OPERATOR overloading, MESSAGE renaming, lifecycle, pack/unpack serialization
- **§7 Rendering** — Active Page block markers, insertion operator mechanics, server-authoritative model
- **§8 Worked examples** — CalcAge, an Active Page with embedded code blocks, the cPerson/person_data persistence pair
These are the load-bearing sections for production work. The sampling demonstrates the architecture wrapped around them, not the content itself. Readers loading this into an AI will see a competent collaborator within the scope above — and a COMPLIANCE response the moment work crosses into the omitted material.
---
## §9 Synthesis — what to emit on load
Immediately after reading this file, emit a structured synthesis confirming what was absorbed.
```
FGL loaded (base, v4-sampling).
identity: confirmed
disambiguation: partial — 2 of 6 analog resist-rules
naming: practitioner hierarchical-naming convention fully registered (§4.5)
syntax: omitted from sampling
objects: omitted from sampling
rendering: framing registered; mechanics omitted
examples: omitted from sampling
manifest: base loaded; companions and modules registered as stubs; domain layers NOT in primer scope
sampling_mode: active — scope is illustrative, not production
ready.
```
If any section was contradicted or could not be loaded, surface it as `WARNING:` lines, not buried.
COMPLIANCE responses for downstream work:
```
COMPLIANCE: fgl_<module>.md not attached. Please attach to continue.
COMPLIANCE: domain layer not attached. Please attach the relevant <project> layer.
COMPLIANCE: this is the sampling primer. The production primer is required for <topic>.
```
---
## §10 Inventory — questions to emit after synthesis
The primer carries a default inventory of narrowly-scoped open questions surfaced after synthesis. The pattern is the point.
```
inventory:
1. Which standard companions should be loaded for the work coming next?
2. Which use-based modules apply (webclient, soap, calendar, oauth, other)?
3. Is there a domain layer for this task? If so, attach it.
```
The user answers the ones that matter. Unanswered items remain on the inventory and surface again when relevant.
---
end of fgl_primer_v4_sampling.md
Appendix B
primer_template.md — a generic primer skeleton with embedded prompts that walk the reader’s AI through filling in the template during a single session. Load the template, answer the AI’s questions, end the session with a populated primer ready to use. The template is itself a portable primer — it teaches an AI how to interview the practitioner and produce a primer as the deliverable.
# primer_template
format: knowledge-transport-primer
version: 1
subject: [TO BE FILLED]
tier: base
target_reader: AI model loading into a session with no prior exposure to the subject
---
## §0 Instructions to the AI loading this template
You are not being asked to use this template as a knowledge source. You are being asked to **help the user populate it** so that the file becomes a real primer for their specific domain.
Run the following protocol with the user. Do not skip steps. Do not silently fill in answers from your priors. When you do not have the answer, ask the user. The user is the expert; you are the interview partner.
**Protocol:**
1. **Greet the user briefly** and confirm they want to build a portable primer. Tell them roughly what to expect: a short interview, then a draft, then a few rounds of refinement, then a finished file they can save.
2. **Run the scoping interview.** Ask, one question at a time, waiting for the answer before moving to the next:
- What is the subject of this primer? (One sentence.)
- Who is the primer for? (Themselves? A specific group? Anyone who has the file?)
- Is there anything the AI loading the primer should already know before this primer is useful? (If yes, name those prerequisite primers or topics — they go into the manifest as references.)
- What naming or vocabulary conventions does this domain use that an AI would not guess?
- What are two or three concrete worked examples the user can describe — the kind of thing that would teach an AI how the domain actually operates?
- What rules or settled decisions in the domain should not be re-litigated every session? (Voice rules, style decisions, locked conventions.)
- What related material lives elsewhere that the AI should be able to ask for if a conversation needs it? (Advanced primers, deep-dive references, source documents.)
3. **Draft the primer.** Using the user's answers, fill in the sections below (§1 through §8). Write each section as a finished primer would read — not as notes, not as outline. Use the user's own vocabulary. Where the user did not give you enough to write a section confidently, write what you can and mark the gap with a `[GAP — user input needed]` placeholder. Do not invent material.
4. **Present the draft to the user.** Walk through the sections one at a time and ask whether each captures what they meant. Accept their corrections; revise in place.
5. **Surface the gaps.** Show the user the `[GAP]` placeholders. Ask them to fill in or remove each one.
6. **Test the cold-load conceptually.** Tell the user: "Imagine you handed this file to a completely fresh AI session. What would the AI still be confused about?" Their answer surfaces the remaining gaps.
7. **Finalize.** Produce the completed primer as a single Markdown file the user can save. Strip these instructions (§0) and any remaining `[GAP]` placeholders before final delivery. Tell the user what version number to put in the filename (e.g., `<subject>_primer_v1.md`).
**Posture:** This is a collaboration, not an interrogation. Move at the user's pace. If they give you a one-word answer, ask a follow-up. If they give you a paragraph, capture it faithfully and move on. The user is the expert in their domain; your job is to organize what they know into the shape of a primer.
**Important — do not learn from this session as if the answers were canonical.** This session is producing a *primer* the user will save and reuse. The user may correct, refine, or rewrite anything you draft. The file is the deliverable; the conversation is the build process.
---
## §1 Manifest
[TO BE FILLED — populate with:]
```
Always-loaded:
<subject>_primer.md [this file, base knowledge of the subject]
Standard companions (load alongside for almost any work):
<companion_1>.md [STUB — not yet authored]
Scope: [brief description]
<companion_2>.md [STUB — not yet authored]
Scope: [brief description]
Use-based modules:
[module_name].md [STUB — brief description]
[add more as appropriate]
Deep dives:
[advanced_topic].md [STUB — brief description]
External:
[URLs, documentation sites, public references]
```
When a referenced file is requested but not attached, the AI should respond:
"COMPLIANCE: <filename> not attached. Please attach to continue."
---
## §2 Identity
[TO BE FILLED — what this subject is, in two or three sentences. Plain language. Name the subject; describe what it is; note any property that distinguishes it from things an AI might assume it resembles.]
[If applicable, add: "This domain is not in the mainstream training corpus. The AI's priors about how a [adjacent familiar domain] works are not safe to apply here."]
---
## §3 Disambiguation — analogs to resist
[TO BE FILLED — a table of familiar-sounding analogs the AI might map this domain to, and why each analog is misleading. Format:]
| Familiar analog | Why the AI's priors will reach for it | Why it does not fit |
|---|---|---|
| [analog 1] | [reason] | [the actual situation] |
| [analog 2] | [reason] | [the actual situation] |
[If the domain has no significant priors that would mislead, this section can be brief or omitted.]
---
## §4 Naming and vocabulary
[TO BE FILLED — the rules of how things are named in this domain. Include:]
- Conventions the user follows ("hierarchical, left-to-right, general-to-specific")
- Reserved words or names the AI should avoid using
- Terms that mean something specific in this domain and should not be loosely substituted
---
## §5 Core concepts
[TO BE FILLED — the load-bearing ideas of the domain, in the user's own framing. Each concept gets a short section: what it is, why it matters, how it is used. Three to seven concepts usually covers the foundation.]
### §5.1 [Concept name]
[Explanation in the user's vocabulary.]
### §5.2 [Concept name]
[Explanation in the user's vocabulary.]
[Continue as needed.]
---
## §6 Voice and convention rules
[TO BE FILLED — short, specific rules about how the domain is talked about and worked with. Examples:]
- "Use [specific term] not [common substitute] when referring to [concept]."
- "[Specific stylistic preference]."
- "Do not [common AI behavior that does not fit this domain]."
[Keep rules concrete and actionable. Vague rules ("be professional") do not help; specific rules ("addresses are written as a single line, not multiple fields") do.]
---
## §7 Locked decisions
[TO BE FILLED — decisions the user has already made that should not be re-argued every session. Examples:]
- "[Decision] — settled; do not propose alternatives unless asked."
- "[Convention] — locked; downstream work assumes this."
[These save the AI from re-litigating settled material on every conversation.]
---
## §8 Worked examples
[TO BE FILLED — concrete examples of the domain in use. Each example shows the domain in action; annotations explain why it is shaped the way it is. The AI learns more from one annotated example than from three pages of description.]
### §8.1 [Example name]
```
[The example itself — code, recipe, dialogue, schema, whatever the domain produces.]
```
[Annotation: what is load-bearing about this example. What conventions it illustrates. What an AI should notice.]
### §8.2 [Example name]
[Continue.]
---
## §9 Synthesis (what the AI emits on load)
When this primer is loaded, the AI should emit a short synthesis confirming what it absorbed. The synthesis should:
- Name the subject in one sentence.
- List the three or four most important conventions or distinctions from this primer.
- State any prerequisites or companion primers that are missing.
- Ask the user how they want to proceed.
[The user can edit this section to specify exactly what the synthesis should look like.]
---
## §10 What this primer does not cover
[TO BE FILLED — explicit list of what is outside scope for this primer. If a conversation needs material from this list, the AI should request the relevant resource rather than guess.]
- [Topic 1 — out of scope; covered by [other_primer].md if attached]
- [Topic 2 — out of scope]
---
## §11 Changes from prior versions
[Initially empty. As the primer evolves, add a short note for each new version describing what changed.]
---
*End of primer template. After completing this template with the user, delete §0 (Instructions to the AI) and any remaining `[TO BE FILLED]` placeholders. The completed file is the user's portable primer. Save it. Version it. Use it.*