refactor references to become context

[olimorris]

Description

This refactor will ultimately see references become context.

Originally when I added this at the turn of the year, references were simply files or buffers that were referenced in the chat buffer. As we walk the roadmap to modes, references doesn't capture the fact that these items are in fact context that's shared with an LLM. Sure, they're references, but the better understood term is context and I believe now is the time to make this change. It should be noted that the chat buffer has displayed items under a block quote of Context for quite some time. So this felt like a huge disconnect when internally they were called references.

I will ensure that Prompt Library references are mapped over to the new context table without breaking anyone's custom prompts.

Changes so far:

• chat.context becomes chat.buffer_context. Much more explicit and clearer on what it is
• references.lua becomes context.lua
• opts.reference becomes opts.context_id for a chat buffer message
• chat.references:add is now chat.context:add
• chat:add_reference is now chat:add_context (although the former still works)
• references is replaced by context for custom prompts (although the former still works)

Checklist

• I've read the contributing guidelines and have adhered to them in this PR
• I've updated CodeCompanion.has in the init.lua file for my new feature
• I've added test coverage for this fix/feature
• I've updated the README and/or relevant docs pages
• I've run make all to ensure docs are generated, tests pass and my formatting is applied

[cloudflare-workers-and-pages]

Deploying codecompanion with    Cloudflare Pages

Latest commit:	a74236c
Status:	✅  Deploy successful!
Preview URL:	https://b028dd0e.codecompanion.pages.dev
Branch Preview URL:	https://refactor-references-become-c.codecompanion.pages.dev

View logs

[olimorris]

@ravitemer - Heads up that this is likely going to break codecompanion-history. I've put some deprecations in place but maintaining a chat.references class was proving to be too problematic.

Moving forward, I'm keen to ensure that I can remain nimble in being able to change CodeCompanion as I see fit, yet not compromise you and your endeavours. Perhaps the logical step is to only ever create a new release when you're confident your side is up to date.

[ravitemer]

@olimorris Thanks for the heads up! 🙏

The refactoring from "references" to "context" makes a lot of sense and is much more intuitive to understand. The terminology now perfectly reflects what these items actually represent - context shared with the LLM.

I've successfully migrated the codecompanion-history extension to work with the new context API while maintaining backward compatibility for existing chat histories.

Really appreciate how thoughtfully you've structured this change with deprecation warnings. The API evolution feels natural and well designed! 🚀