Idea: Provide domain term context

@JohannesKlauss i just took a closer look.

So the way I'm thinking about this rn is to extend the .github/pr-lens.yml to accept a glossary. something like:

# .github/pr-lens.yml
names:
  - name: Ledger
    means: The billing service. Owns plan changes and talks to Stripe.
    match: [app/api/billing/**, lib/plans.ts]
  - name: Tollbooth
    means: Our Stripe wrapper. Nothing else calls Stripe directly.
    match: [lib/stripe.ts]
  - name: Org
    means: What the code calls a workspace. One Stripe customer per Org.
  - name: Tier
    means: What the code calls a plan. Free, Pro or Team.

This context is then used for every generated map and preserved.

is this enough to fit your use case?

If yes, we could make it easy to tweak and edit in the canvas directly:

https://github.com/user-attachments/assets/c355aa6d-a2a6-44a6-a45d-5064ad93a61a

or directly from a PR:

https://github.com/user-attachments/assets/84cf3064-0e69-4a89-be20-f64b5c4ea5a5

it may be possible (i need to research) to also automatic source some of these e.g., from catalog-info.yaml entry, a CODEOWNERS line, a code comment etc. and show it in the canvas directly

https://github.com/user-attachments/assets/7ad73229-48df-4973-aae2-15d785b74168

NB: the videos are all prototype from me messing around on what a potential UX for this could look like. They're rough ideas and UIs

If possible I think referencing a markdown file fmin the repo would be the most flexible solution, mostly because then Agents that code can pick up the same source. I.e. we hold a CONTEXT.md in the repos root where we explain domain terms, how they relate to each other and what terms should be avoided when talking about a specific part of the system. It aligns agents with the way we talk about the product and code. These terms sometimes map 1 to 1 to a component, but sometimes they are more broadly just part of the domain language.

I.e. this is an excerpt from a CONTEXT.md

## Language 
  
 **Journal**: 
 One dated issue of a Title, published as a PDF. 
 _Avoid_: Edition — that is iKiosk's API term for the same thing; iKiosk is legacy and shuts off end of 2026, so "Edition" is tolerated only at the iKiosk adapter boundary (e.g. `IkioskEdition`). 
  
 **Title**: 
 A periodical (magazine or newspaper) that publishes Journals.

make sense. this might even be easier to implement.

but is CONTEXT.md too loose a file name? as I suppose a lot of other "context" may go there - not related to domain terms per se

perhaps in .github/pr-lens.yml we could do

  glossary: /file-path

this way we wouldn't care about the file name per se. could be anything. it'd be more flexible (we'd do a quick scan against prompt injection, but otherwise should be fine)

@ohansFavour FYI, i think this should give us the most flexibility. We'd need to adapt for other forges (bitbucket, gitlab) but conceptually:

  # .github/pr-lens.yml
  glossary: docs/CONTEXT.md#Language   # any markdown file, optional heading
  names:                                # only for services that need path binding
    - name: Ledger
      match: [app/api/billing/**]

Internally:

1. We read the glossary from the base branch for fork PRs, from the head otherwise.
2. We do (1) without stuffing it into the prompt, and just let the drawing agent read the file as needed
3. Perhaps we add a footer reference on the canvas to the glossary terms applied (unsure how the UI should look yet)

this way we wouldn't care about the file name per se. could be anything. it'd be more flexible (we'd do a quick scan against prompt injection, but otherwise should be fine)

Yes, this is what I was going for, just pass a file path to the config. Prompt injection didn't cross my mind, would it make sense to somehow conform to some sort of a scheme for the glossary to mitigate this attack vector?

@JohannesKlauss i think we may be able to run quick classifications over prose with Jev. I'll run some experiments, if its reliable, that'd be great as it'll make things arguably agent-friendly (good ol' markdown)

I'd assume that even with a schema, any string property could still open us up for injection (so we need to figure it out either way)

btw thanks for submitting this issue! it'll have real world +ve impact once fixed