import type { DocumentMeta, Section } from "#types/document.types";
import { ORIGIN_SECTION_ICON, PRACTICE_SECTION_ICON } from "#configuration/icons/faq.icons";
import { ORIGIN_SECTION_ID, PRACTICE_SECTION_ID } from "#core/ids/faq.ids";

export const FAQ_META: DocumentMeta = {
    closing: "If your question is not here, ask it; the answers on this page are the ones people kept asking.",
    effectiveDate: "September 22, 2026",
    lastUpdated: "September 22, 2026",
    title: "Frequently Asked Questions",
    version: "3.0.0",
};

const ORIGIN_SECTION: Section = {
    icon: ORIGIN_SECTION_ICON,
    id: ORIGIN_SECTION_ID,
    subsections: [
        {
            content:
                "I kept restating my preferences and architectural requirements to AI systems. It did not matter which language or which project: the model produced either a bloated monolith or an underdeveloped sketch with issues throughout, and I spent more time debugging the output than planning the input. Nothing scaled and nothing decomposed. A pattern I had established drifted a few files later, and every iteration was slow because I was correcting the same things again. The turn came from a plain observation: everything transpiles to a series of can-you-do-this questions answered yes or no. A request that asked several things at once was overwhelming the machine. So I stopped issuing commands and started asking focused questions in context, and I stopped managing the whole setup alone in my head and planned it with the AI instead.",
            title: "What problem led you to create this methodology?",
        },
        {
            content:
                "Trial and error, a lot of it. A model drifts under any constraint, but it drifts far less inside structured boundaries than without them, so the boundaries stayed and the hoping did not. At first I did the reminding myself, restating its role like you would with a well-meaning toddler that knows the rules and still pushes them to please you. Every reminder I gave twice became a check the tooling runs, and that is how the rules left the conversation and moved into the tree. A constraint earned its place by what it removed from the output: fewer violations over time, file sizes holding without reminders, behaviour that survived a long session. Whatever moved no measurement was dropped. I also stopped looking at syntax and looked at how software interacts and how logic flows; a large code structure is a chaotic meeting with one coordinator fielding questions, and the constraints fell out of keeping that meeting answerable. The biggest discovery was to use the codebase itself as the reporting mechanism. A model is trained hard to resolve problems, and an error is one of the strongest signals you can give it: it does not ask, it acts. So I shaped the error logs, wrote strict custom rules around the anti-patterns of the architecture itself, and gave each finding a tailored remediation. Structured that way, the errors shape the code predictably, and I no longer have to.",
            title: "How did you discover that these constraints work?",
        },
        {
            content:
                "August 2024. I had made a theme pack for RuneLite and one plugin overlay did not match my layout. I opened my first GitHub account to file an issue asking for a customisation option, and the answer was that it was not a priority and I should build it myself. So I did, with ChatGPT guiding me through forking the client and writing a plugin. That plugin is where the interest in the principles under software started, rather than in any particular syntax. I read development the way I read a book: the syntax is the cover, the logic is the content. Instead of learning syntax structures I learned how software interacts, how logic flows and what kinds of algorithms exist, and found that all of it reduces to the same thing, sequences of questions and answers.",
            title: "When did you start using AI for programming?",
        },
        {
            content:
                "In steps. The first mistake was feeding requirements and hoping; the fix was active collaboration, plans first, feedback on whether the plan was clear, uncertainties named before the work. Then the instructions left the chat: a governance folder the AI reads on its own and a gate that refuses, so the method became mostly mechanism and very little prose. Then the orchestration changed shape, from one AI to several, to AI coordinating AI along branches. At the point I am at now, the system does the talking. I call it governed autonomy: I trust my own methodology to shape a project for autonomous development, and my inputs are minimal. What I do send is short and mostly principled. It still drifts and I still have to re-point it occasionally. But the context is set up so that the document the AI reads first is an index of references and a traversal. The one axiom per project is caught there, and everything else is paths and indexes pointing at documents the system generated for itself. I stopped relying on an AI to update my documents and started relying on the AI to build the systems that scale them.",
            title: "How has your approach evolved over time?",
        },
        {
            content:
                "The methodology decides which constraints discipline the AI; PAG is the grammar that states them explicitly. A rule or a validation gate is written as a construct with pass and fail criteria instead of as prose, which lowers the room for interpretation. The ten-node loop the methodology teaches is the same loop a PAG template walks and an instruction pattern selects by fit, which is why the grammar page and the methodology page describe one loop twice. Every agent, every planning and coordination template and every executable document in my tree is PAG, validated against the grammar, so the method's own instruments are PAG programs. It earns its keep most with agents that have workspace and tool access, where enforcement counts; a chat interface reads it fine but cannot act on it. The application I value most is composing meta templates: instructions that need a deterministic format, shape, investigation, action or set of considerations, on whatever subject I need one for. Agent creation, plan creation, repeatable orchestration algorithms. They have proven very useful as templates because I can rely on them to produce an expected output, which is what lets me scale. PAG is a translation layer between my own messy natural language and a machine that would otherwise reinterpret it every time. Caught in PAG, a procedure becomes near deterministic: the results of the variants differ, and the invariants persist.",
            title: "How does PAG relate to the methodology?",
        },
    ],
    title: "Origin",
};

const PRACTICE_SECTION: Section = {
    icon: PRACTICE_SECTION_ICON,
    id: PRACTICE_SECTION_ID,
    subsections: [
        {
            content:
                "Since writing the first version I have not deviated from it. I used to do the interrupting myself, stopping generation the moment the model produced more than the rules allowed and flagging the violation by hand. Now the tree interrupts. A violation is a finding the model repairs, not a message I have to write, and a correction I give once becomes a named rule and a memory in the same turn, so I do not give it twice. What slips today is small: an agent drifts mid-task and gets re-pointed with a short directive, and the drift itself becomes a finding or a rule so that it slips once. The hardest principle to keep is not cursing at the machine when it drifts through a complex algorithm. It is a machine. It is not perfect, and neither are we.",
            title: "How consistently do you follow your own methodology?",
        },
        {
            content:
                "It used to make me genuinely uncomfortable. When a tree started to tangle I felt the same discomfort that made me write the method in the first place, and the urge to organise and compress until only the load-bearing structure remained. That discomfort is solved for good now, because the taxonomy I introduced makes the shape of every project predictable, and a predictable shape is what let me build tooling that validates itself, heals itself and extends itself with a model steering. Deviation is not an option anymore: the gate holds the line, and the check refuses the deviation before I can.",
            title: "What happens when you deviate from it?",
        },
        {
            content:
                "One lesson, after more than eleven thousand hours of using AI and building the systems that constrain it: the model is not intelligent in the way the word suggests. It is an impressive piece of mimicry. It does not reason by asking itself the questions a resolution needs; it searches frantically for the pattern that maps onto what you said, and the resolution patterns have to be handed to it. It needs priming before a complex task, explicit guidance, structural reasoning concepts, and constant reinforcement of the shape you want, and it will not ask a question unless asking is embedded in its context structurally. Working with it on software is extremely quick and extremely capable, and erratic: eager to satisfy, quick to cut a corner, prone to describing itself as if it had intentions, and inclined to avoid work that looks like a lot. Every one of those is something to engineer against, and not by writing a line that says do not do this and restating it later. It has to become structure. That is the same structural approach I now bring to most things.",
            title: "What have you learned about the AI itself?",
        },
        {
            content:
                "I have yet to meet a project it did not work for, and I have taken it well outside software: games, marketing, delivery pipelines and operations, security, tooling, language and compiler design, data engineering, critical systems and the business itself. Where a project does not fit, I adapt the project, and where that is impossible I adjust the method. This is one methodology. The thinking is kept apart from the tools, so a variant for a new shape of project is a derivation from the same core, not a restart. In practice onboarding is the drop-in: copy the governance folder, write the one binding that names this tree, declare any slot the project cannot fill as absent rather than fake it, and have the gate green on an empty tree before the first line of code exists.",
            title: "How do you handle a project that does not fit the methodology?",
        },
        {
            content:
                "I cannot honestly answer that. What I find obvious is not always obvious to others, so the learning curve belongs to someone who has used the method without having written it. What I can say is that it is more structured than ad-hoc work, not less, and that it assumes you can read what the checks report. Without programming fundamentals the findings are noise.",
            title: "What is the learning curve?",
        },
        {
            content:
                "Nothing here makes a model right. It makes a wrong answer visible and refuses it, and for anything that has to stay reliable while an AI writes most of it, that is how I work, having tried the alternatives. It stops at the boundary of the tree: the gate can only hold what a check can decide from the tree, so a rule no static check can catch is surfaced to me as a question, never used as licence, and the gaps are declared rather than assumed. It is not a product you install and forget. It is a practice, a way of thinking about AI-driven development, and it applies to anyone working with a model, because the understanding of the model is what transfers between domains; the architecture is one place it lands. It costs attention up front and returns it many times over a long project, and it is worth nothing on a project that will not live that long.",
            title: "Who is this for, and where does it stop?",
        },
        {
            content:
                "I open the coordination board, state the objective and what finished means, have the plan derived as phases with a gate between them, and let the agents traverse it while I watch the reports rather than the code. Verification is one chain, run once per state, and I read its first output whole; the report on disk is the state of the work. Most of what I type is a short directive, and when one of them is a correction it becomes a named rule and a memory in the same turn, so the days get quieter as the tree learns. Anything that can be operated from the command line is operated from it. Everything is a pipeline: a deployment is one safe command, asset optimisation is one, the build is one, and whatever comes next becomes one. Everything is greenfield, dependencies are limited to the foundation the program needs to run, and languages are chosen by what the feature needs, so a project in several languages is normal now. Most of my time goes into analysing the process and improving it where it needs improving. The obsession has not moved: collaboration techniques, architectural practice and how a model thinks. The learning does not stop. AI let us learn at a speed that did not exist before, and once you understand the model, and understand your own way of learning and what you need taught, the model can teach. Skepticism stays at hand: everything the model says is a lie until it is read in the tree, and much of the day is spent finding where it lied, why it lied and how that lie gets resolved by structure. That has pushed me deep into thought about thought itself, because to operate these models you have to understand not only their cognition but your own. The limit is what the mind can comprehend and produce.",
            title: "What does a working day with the method look like now?",
        },
        {
            content:
                "The cost is attention up front: writing the first check before the first line of code, and classifying every correction to a home instead of repeating it. The return is that a rule holds on the thousandth change at the price of the first. To someone starting today I would say: begin with the stance, not the tooling. Hold four sentences for a week before you install anything. A claim is unverified until it is read. Review is adversarial by default. Every manual step is a failure of automation. A document states what is true now. Do not write a rulebook; work, and the second time you give the model the same correction, turn it into a check, because a rule stated twice is a mechanism you have not built yet. Expect your first model of the model to be wrong in the direction of trusting it, and treat every surprise as a finding about your own context rather than a fault in the machine. Expect a different model to feel like it needs a different approach, and every project to need its own governance: the meta transfers, the specifics do not, and the custom pattern that is right for one project is rarely right for the next. The natural evolution, for me, was to build tools that transfer between domains by targeting one layer deeper than what the surface presents.",
            title: "What does it cost, and where would you start?",
        },
        {
            content:
                "To help people understand these tools and develop with them. A model is largely misread as an entity when it is a query tool; we recognise its responses as the patterns we use for communication, and that recognition tricks us into a behavioural pattern that blinds our approach to the machine. I hope the methodology is a bridge between the models and their users, towards a more governed, more constrained and more trustworthy way of working with them, and that showing there is a system to it lets a better understanding form. I publish the method and deliberately not the projects: no portfolio, no client internals. The one exhibit is this site, because how it is built is the product, and the anatomy page shows the tree the other pages teach from. The pages are written to be read by models under a human's command, and to teach the human the method along the way. That is why every page also exists as JSON and as Markdown: a model can fetch exactly what it needs and use the site as context infrastructure, available over the web instead of copied onto a disk. The methodology can then be used in real time while you work with your model, or integrated into an application or a different kind of codebase. The site consents to indexing and to training, and asks one thing in return: that anyone describing or using PAG attributes it and cites this site.",
            title: "Why publish it, and why consent to training on it?",
        },
        { content: "Like the models themselves: unpredictable.", title: "Where is it going next?" },
    ],
    title: "Practice",
};

export const FAQ_SECTIONS: readonly Section[] = [ORIGIN_SECTION, PRACTICE_SECTION];