Documentation
¶
Overview ¶
Package manual is what codeaf knows about itself, embedded in the binary.
Everything codeaf can say about its own capabilities, mechanisms and reasons has to come from somewhere. The design docs are the wrong somewhere: they are on disk rather than in the binary, they are written to persuade rather than to answer, and they go stale the moment a build lands. Improvisation is the worse somewhere — a model asked "how does boost work" will always produce a fluent answer, and there is no way for the user to tell a remembered one from an invented one. So the pages here are the single authoritative source, they ship inside the binary, and the completeness tests beside the feature registries fail the build when a landed feature is not among them.
TWO PRODUCTS, TWO FOLDERS, NO MIXING (corpus.go says why at length):
- pages/ is the RESIDENT — the employee that keeps working while the terminal is closed. Read through this package's own functions, which is the shape internal/head and internal/tui already call.
- chat/ is the V3 CHAT — the conversation surface in internal/tui3 over the engine in internal/session. Read through Chat.
A page belongs to exactly one of them. When a mechanism genuinely exists in both products it is written twice, in each one's own vocabulary, because the two answers are not the same answer: the resident's is about work that outlives the window and the chat's is about the session you are sitting in.
Index ¶
- Constants
- func Context(query string, k int) string
- func Cued(message string) bool
- func Cues() []string
- func Mentions(term string) bool
- func ModelSectionOpen(page string) string
- func Page(name string) (string, bool)
- func Pages() []string
- func PersonSectionOpen(page string) string
- func Render(sections []Section) string
- func RenderWhole(sections []Section) string
- type Corpus
- func (c *Corpus) Context(query string, k int) string
- func (c *Corpus) Cued(message string) bool
- func (c *Corpus) Cues() []string
- func (c *Corpus) Listing() string
- func (c *Corpus) Mentions(term string) bool
- func (c *Corpus) Page(name string) (string, bool)
- func (c *Corpus) PageSections(name string) []Section
- func (c *Corpus) PageTitle(name string) string
- func (c *Corpus) Pages() []string
- func (c *Corpus) Search(query string, k int) []Section
- func (c *Corpus) SearchBoth(query, personsWords string, k int) []Section
- func (c *Corpus) Section(page, heading string) (Section, bool)
- func (c *Corpus) Sections() []Section
- type Say
- type Section
Constants ¶
const ( // DefaultResults is how many sections one question is answered from. Four // is a topic and its neighbours; more is a document, and a model handed a // document quotes the wrong half of it. DefaultResults = 4 // SectionBodyCap bounds one section's text where it is rendered for a // model. Pages are written to sit well under this; the cap exists so a // future long page degrades by truncation rather than by budget. SectionBodyCap = 2400 )
const Pitch = pitchProse + "\n\n" + pitchCatalog
Pitch is codeaf's account of what it is and what a person can say to it, in its own voice. It lives here rather than in a page because it is the one piece of the manual two surfaces need at once: the head carries it in its stable prompt so the model can answer "what can you do?" without being told which words trigger that question, and the ? overlay lists its catalog so the screen and the answer cannot drift apart. Authored once, read twice.
It is deliberately a constant. The head's system message is the cache prefix every routing call is billed against, so anything inside it that could be computed at run time is a cache miss waiting for a state change.
Variables ¶
This section is empty.
Functions ¶
func Context ¶
Context is the one-call shape both the belt tool and the router's grounding path want: search, then render, or nothing at all.
func Cued ¶
Cued reports whether a message reaches for the resident manual's own vocabulary. It is half of the head's self-question trigger.
func Cues ¶
func Cues() []string
Cues is the derived vocabulary itself, for tests and for anything that wants to see what the trigger will fire on.
func Mentions ¶
Mentions reports whether a term appears anywhere in the resident's manual. The completeness tests are written against it, so a feature that lands without a page fails the build rather than becoming something codeaf improvises about.
func ModelSectionOpen ¶
ModelSectionOpen is the start of the label Render writes for the model — `[permissions · ` — kept beside PersonSectionOpen so a test that meant the person's door cannot quietly pass on the model's shape, or the other way round.
func PersonSectionOpen ¶
PersonSectionOpen is the start of the label RenderWhole writes for one page — `## permissions · ` — so the command-line door and every test that reads what a person saw share one spelling. The model's bracketed form is ModelSectionOpen; the two must never be swapped, because a person reading `codeaf manual "…"` is reading Markdown headings and the belt tool is reading brackets.
func Render ¶
Render turns sections into the block a model reads. Page and heading stay attached so a quoted answer can be traced back to the page that authorized it. It belongs to no corpus — sections carry their own provenance.
func RenderWhole ¶
RenderWhole is Render for a person rather than for a model: a Markdown heading over each section — the page and the heading it came from, so a quoted line can be traced back to the page that authorized it — and NOTHING CUT under it.
Render's SectionBodyCap is a budget, and it is the model's: a context window is paid for by the token, so a long section degrades there by truncation. A person reading their own manual is paying for none of that, and a page cut short on the surface where the whole of it is free would be a limit wearing a reason it does not have.
Types ¶
type Corpus ¶
type Corpus struct {
// contains filtered or unexported fields
}
Corpus is one indexed folder of pages. It is built once, on the first question asked of it, and never changes afterwards: the pages are embedded in the binary, so a corpus that has been read is a corpus that is already right.
func Chat ¶
func Chat() *Corpus
Chat is the v3 chat surface's manual: what it can do, how a mechanism works, and why it behaved the way it did. It is a separate corpus from the resident pages and cannot reach them, which is the point — see corpus.go.
func (*Corpus) Context ¶
Context is the one-call shape a tool wants: search, then render, or nothing at all.
func (*Corpus) Cued ¶
Cued reports whether a message reaches for this corpus's own vocabulary. It is half of the self-question trigger, and it lives here because the words worth recognizing are exactly the words the pages are titled with — a list nobody has to maintain twice.
func (*Corpus) Cues ¶
Cues is the derived vocabulary itself, for tests and for anything that wants to see what the trigger will fire on.
func (*Corpus) Listing ¶
Listing is every page in this corpus, one per line, in reading order: the name a person types to open it, then the title the page gives itself. The name comes first and the column is aligned because the names are what the line is for — the title is there to choose by.
func (*Corpus) Mentions ¶
Mentions reports whether a term appears anywhere in this corpus. The completeness tests are written against it, so a feature that lands without a page fails the build rather than becoming something the product improvises about.
func (*Corpus) PageSections ¶
PageSections returns one page's sections in reading order, and nothing when there is no such page. The scan is linear over the corpus because a manual is a few thousand sections held in memory and read once per lookup; an index would be a second structure to keep true for no gain anybody could measure.
func (*Corpus) PageTitle ¶
PageTitle is the title a page gives itself: its own `# ` line. The search stops at the first `## ` because everything past that is a section rather than a title, and the pages run to hundreds of kilobytes. A page with no title line is named the way this package names one anywhere else — its file name, with the dashes read as spaces.
func (*Corpus) Search ¶
Search ranks this corpus against a question. k at or below zero asks for the default; the result is ordered best first and is empty only when the question shares no word with any page.
func (*Corpus) SearchBoth ¶
SearchBoth ranks this corpus against the question a model composed AND the words the person themselves used, and answers the best k of the two together. It is Corpus.Search when the person's words are empty or are not a question at all, so a caller with nobody to quote loses nothing by asking for both.
func (*Corpus) Section ¶
Section returns one section of one page by its heading. The heading is matched the way a person types one back — the `## ` and the capitals are forgiven, nothing else is — because a near miss that returned a neighbouring section would read as though the heading asked for existed.
type Section ¶
Section is one addressable piece of a manual: a heading and the prose under it. The preamble of a page — everything above its first heading — is a section too, titled by the page's own title.
Source Files
Directories