This is a submission for the Weekend Challenge: Generosity Edition
Don't Just Ask AI. Give the Answer Back.
AI is a real force multiplier fo...
For further actions, you may consider blocking this person and/or reporting abuse
This raises some important points. In practice, I've found that the key is balancing theoretical best practices with pragmatic trade-offs — what works in a blog post doesn't always survive contact with a legacy codebase.
Absolutely. And I think that's actually one of the reasons I'm interested in synthesizing knowledge rather than simply collecting “best practices”.
A solution can be perfectly valid in isolation and still be the wrong recommendation once you add a legacy codebase, existing constraints, or a particular environment.
That's another reason why I don't want Shared Knowledge to behave like a static cookbook. The useful part is not just “this works”, but understanding the scope and conditions under which it works — and being explicit when those conditions matter.
In the end, “pragmatic trade-offs” are often part of the knowledge, not a deviation from it.
Treating knowledge as a living synthesis rather than a static dump of best practices is exactly what prevents technical debt from compounding. When we ignore legacy constraints, even the most elegant isolated solution becomes a liability. I'm curious how you plan to structure the MCP to continuously ingest and adapt to those environmental shifts without turning into just another outdated wiki.
One angle I haven’t seen mentioned yet is what happens when the knowledge base itself becomes untrusted model input.
Since these articles aren’t only documentation for humans but are retrieved through MCP and consumed by agents, a merged contribution effectively enters the agent’s context boundary. That makes this a knowledge-poisoning / indirect prompt injection problem as well as a content review problem.
Human PR review is a strong publication gate, but “this technical solution is correct” and “this Markdown is safe for an AI agent to consume as data rather than instructions” are slightly different checks.
I’d be interested in how you see that boundary evolving as contributions become less trusted: whether retrieved articles should be structurally treated as quoted/untrusted data, whether certain content patterns should be rejected at publication time, or whether the MCP should enforce that distinction independently of whatever client/model is calling it.
The model agnostic design actually makes that question more interesting, because you can’t assume every downstream client will interpret retrieved content with the same trust semantics.
Maybe I just missed this being mentioned but there are a lot of comments in this post. Good work
I think there may be a slight category error here.
The knowledge base isn't intended to be an untrusted collection of arbitrary model-generated content. A contribution goes through the MCP, becomes a PR, and is explicitly reviewed by a human before it becomes part of the knowledge base.
So if a reviewer validates the solution, the resulting Markdown is simply validated knowledge. The fact that it can subsequently be consumed either by a human or by an AI doesn't fundamentally change the trust model of the knowledge itself.
Of course an agent can be vulnerable to prompt injection from external content in general, but that isn't specific to this knowledge base. The same question applies to any documentation, API response, web page, repository, etc. that an agent is allowed to consume.
I would therefore distinguish “untrusted contribution” from “published knowledge”. The former is exactly why the PR/review boundary exists. Once merged, the content has passed that boundary.
If we started treating every published knowledge artifact as inherently untrusted model input, we'd effectively be saying that human validation doesn't establish anything about the trustworthiness of the knowledge — which isn't really the model I'm building.
That said, the distinction between knowledge and instructions to the agent is an interesting one. But I'd see that as a property of how a particular MCP client consumes the returned data, rather than something that turns a validated knowledge base into a poisoning vector by itself.
I think I may have used “untrusted” too broadly in my first sentence, because I’m not arguing that a merged article should remain epistemically untrusted after human review.
What I’m distinguishing is trust in the knowledge from authority over the consuming agent.
A reviewer can establish “this is a technically valid solution” without necessarily establishing “this content is authorized to influence downstream agent control flow.” To me those are separate properties.
So I’m not sure the distinction is really untrusted contribution vs. published knowledge. I think it’s more like publication trust vs. execution authority.
And I agree this isn’t unique to this knowledge base. Documentation, API responses, repositories, and web pages all create the same boundary when agents consume them. That’s actually why I’d expect the MCP client to preserve a strong data/instruction distinction regardless of how trusted the upstream source is.
In that sense I think we may be closer than my use of “untrusted” initially made it sound.
Yes, I think I see the distinction you're making, but I'd probably stop the boundary there.
My responsibility is to make the application robust and ensure that what gets published has been properly validated. Whether a human reads that knowledge, an agent consumes it, or someone tries to use it in a way I never intended isn't something the knowledge base itself can really control.
So for me the important boundary remains the publication gate: is this knowledge valid and safe to publish? Once published, it's a knowledge resource. What a downstream system does with it is a separate problem.
That makes sense. I think we’re aligned on the distinction then we’re mostly drawing the system boundary at different places. Your publication gate establishes the properties of the knowledge resource, while the consuming client owns the instruction/authority boundary downstream. Thanks for engaging .
Exactly. I think that's where we landed. Thanks for the thoughtful discussion! 👍
The architectural pivot is the part that stuck with me most, deliberately taking Gemini out of the critical path and giving up the prize category eligibility rather than forcing a dependency that would have contradicted the whole point of the project. That's a genuinely principled call and it shows in the architecture.
The "conversation stays private, knowledge extracted from it can be shared" boundary is also really cleanly drawn. A lot of knowledge-sharing tools blur that line or make sharing the default, and the explicit human review gate before anything goes public is the kind of design decision that feels obvious in hindsight but actually requires discipline to hold to when you're building fast.
The ElevenLabs Voice Library bug is a useful one too, the empty environment variable silently overriding the default because os.environ.get() only falls back when the key is missing rather than when it's empty is exactly the kind of thing that takes way too long to find the first time you hit it.
Thank you — especially for taking the time to read the article at that level of depth.
What you picked up on is actually very close to what I was trying to do with the article itself. I deliberately didn't want to turn it into a polished “here's what I built and why it works” story. I wanted to document the reasoning, the architectural decisions, the things that didn't work, and the solutions that emerged from those problems.
In a way, I tried to apply the same approach to the article as to the project: don't hide the messy parts behind the final result, because that's often where the useful knowledge is.
So I'm particularly glad you noticed the Gemini decision, the privacy/knowledge boundary, and even the rather mundane ElevenLabs environment-variable bug. Those details are part of the story precisely because they shaped the system that eventually emerged.
And yes, that
os.environ.get()behavior is one of those wonderfully small bugs that can consume a disproportionate amount of time the first time you encounter it. 😄The duplicate check has a race that only shows up once the base is worth searching. search_knowledge reads merged articles, so two people who hit the same wall in the same week both search, both find nothing because the first article is still an open PR, and both open one.
Your Copilot run is the good case and it shows the limit: the assistant did check before publishing, and it could still only see main.
Having publish_knowledge search open PRs as well, or deriving the branch name from a slug of the title so a second attempt collides on the branch instead of on the reviewer, keeps that off the human's desk.
That's a fair observation, although I wouldn't actually consider this a race condition that the architecture needs to eliminate.
Two people can independently encounter the same problem within a short enough window that neither can see the other's contribution yet. That's not necessarily a failure of the system — it's simply a property of collaborative knowledge creation.
The important distinction for me is between preventing duplicate published knowledge and preventing duplicate proposals. The former is something the system should handle automatically; the latter is perfectly legitimate.
That's also why the human review gate is there. If two PRs describe essentially the same solution, the reviewer can reject the second one. But they can also merge the useful parts of both, or even decide that the second solution is better and replace the first one.
So in this particular case, I actually want the architecture to tolerate the race rather than trying to eliminate it. The PR is a proposal, not yet knowledge.
And I think your observation about the Copilot run is still valuable: it makes that boundary very explicit — the assistant can verify against published knowledge, but it cannot know what another contributor is currently proposing. That's a feature of the workflow rather than something I necessarily want to hide from it.
The "AI-generated bug that wasn't there" section hit home — I just published a piece where my own skill read my Zapier test posts as a promise I'd made to my audience and confidently offered to "finish the thread." Same shape as your Copilot phantom bug: the model wasn't wrong in a way that looks wrong, it was wrong in a way that looks completely reasonable, which is the only kind that actually costs you.
And the human-review gate as the one non-negotiable boundary is exactly where I keep landing too. Not because the model is dumb — because "structure a contribution" and "decide it deserves to be public" are different jobs, and only one of them is safe to hand over. Nice to see someone draw that line so cleanly, and hold it even when it cost you a prize category.
Yes — “wrong in a way that looks completely reasonable” is exactly the dangerous part.
A completely absurd answer is easy to catch. The difficult cases are the ones where the model constructs a perfectly coherent explanation from something that was never actually there. That's what made the phantom bug in my Copilot experiment interesting: the failure wasn't a lack of reasoning, it was reasoning applied to a false premise.
And I really like your distinction between “structure a contribution” and “decide it deserves to be public”. That's very close to how I see the human-review gate.
The model can help turn messy experience into a structured, potentially useful contribution. But whether that contribution is accurate, sufficiently general, non-sensitive, and actually worth adding to the shared knowledge base is a different kind of decision.
That's also why I was willing to lose the prize category. If removing that boundary made the project more eligible but less trustworthy, it would have defeated the point of the experiment.
And your Zapier example is a great illustration of the same problem from another angle: the model didn't invent something random — it inferred a plausible intention from context that didn't actually imply it. Those are exactly the errors that deserve a human in the loop.
"Reasoning applied to a false premise" is the cleanest way anyone's put it, and it reframes the whole thing for me. We keep building guardrails against models that reason badly, when the expensive failures come from models that reason well from a wrong starting point. You can't catch that by checking the logic — the logic is fine. You have to check the premise, and the premise is the one thing the model can't verify on its own.
Which loops right back to your review gate: the human isn't there to grade the reasoning, they're there to confirm the premise was real. Good conversation to have stumbled into — I'll be keeping an eye on where Shared Knowledge goes.
Exactly. And I think that's the part I hadn't fully articulated when I started the project.
We tend to think of AI guardrails in terms of how the model reasons: constrain the output, validate the logic, add more checks around the reasoning process. But if the model is reasoning correctly from a premise that never existed, all of those checks can happily pass.
That's why I increasingly see the human review as an epistemic boundary rather than just a quality-control step. The question isn't only “is this reasoning sound?” but “is this actually grounded in something that happened, and does the resulting knowledge deserve to become shared knowledge?”
And there is an interesting consequence for Shared Knowledge: the MCP can help structure and generalize an experience, but it can't be the final authority on whether that experience is real or whether the generalization is valid.
So yes — “reasoning applied to a false premise” may end up being one of the concepts I carry forward from this experiment. 😄
And thank you for following the project. I'm genuinely curious to see where it leads too.
"Epistemic boundary rather than quality-control step" — that's the upgrade. Quality control asks if the work is good; an epistemic boundary asks if it's true, and those come apart exactly where a fluent model is most convincing. I think that's the sentence I'll be stealing back from you. 😄
This was one of the better threads I've fallen into here. I'll be watching Shared Knowledge — and if that premise-checking layer ever turns into something concrete, I'd love to read the writeup.
Haha, go ahead — consider “epistemic boundary” officially open source. 😄
And now that I think about it, there’s a pretty interesting parallel with the problems you’re dealing with in Publora.
Your “right shape, wrong target” failure is almost the operational version of the same problem: the system can validate that something is technically correct without being able to establish that it is actually what was intended.
For Shared Knowledge, the equivalent is: the model can produce a perfectly coherent explanation from a premise that was never true.
In both cases, the dangerous failure isn't a broken call or obviously bad reasoning. It's a successful operation built on a false assumption.
That makes me think the “epistemic boundary” may actually be more useful as a design principle than I initially expected. The interesting challenge now is turning it into something concrete without pretending that truth itself can be automated.
And yes — if I manage to turn that premise-checking layer into more than an architectural box on a diagram, there will definitely be a writeup. 😉
Thanks again for the conversation. This has been one of the more interesting threads I've had around the project so far.
Well, technically Gemini users can still use it? While not explicitly used, it does offer a service worthwhile having. I know that finding solutions is often hit-or-miss, especially now, so having a repo to query, with a MCP in order to prioritize it, should help alot of people with common issues.
Especially if it comes to project scoped work, eg. how to set up a CLAUDE.md file for a Blazor project. It becomes a template grab system that works similar to how we used to use stack overflow.
Overall really neat project that tackles a real world frustration, getting working solutions, that would make alot of people's lives easier, especially given that it's user-fed, it can really push the boundaries.
Yes — and that's an important distinction. Removing Gemini from the critical path doesn't mean Gemini users can't benefit from Shared Knowledge. Quite the opposite: the MCP is model-agnostic precisely so that the knowledge layer can sit underneath whatever AI assistant or model you're using.
And I really like the Stack Overflow comparison. In a way, that's exactly the kind of friction I'm trying to address: instead of asking an AI to rediscover the same solution from scratch every time, it can first query knowledge that came from someone who already went through the problem.
The project-scoped example is a particularly good one. Something like “how should I structure a CLAUDE.md for a Blazor project?” could eventually become reusable knowledge rather than another one-off answer generated from scratch.
The important difference from Stack Overflow, though, is that I'm trying not to turn it into a collection of individual answers. The goal is to progressively synthesize those experiences into generalized knowledge: not “here's how Pascal solved it”, but “here's what actually works for this class of problem”.
And that's also where the human review becomes important. If this really becomes user-fed at scale, the interesting challenge isn't just collecting more knowledge — it's making sure the knowledge base gets better as it grows.
Thanks for the thoughtful comment! That's very close to the direction I'm hoping to take this. 😄
Hm... Would also be a good system to have a 'librarian' model for. Something tiny, literally 100m params, that serves as a lookup index. Model A that you're using, queries librarian model, who essentially uses the context from Model A, to index and find relevant data from the knowledge base, instead of Model A having to do it, that way it saves a ton of tokens on an expensive model, instead uses one that runs practically for free. I had thought for a while now that we've been seriously under utilizing tiny models, eg. they could be used to strip credentials from prompts as a pre-filter, then index the real credentials vs their placeholder, so when the response comes back, it can re-insert it. This would be another excellent use-case. I really need to build 1 at some point to test the theory 😂
I think the “librarian” could become really interesting at scale, but I probably wouldn't introduce it too early.
For a corpus of a few thousand answers — even a few tens of thousands — a good full-text search should be more than sufficient, especially for a technical corpus in English. In that situation, adding a model just to decide what to retrieve could actually add complexity without giving us much in return.
Where I could see your idea becoming really useful is when the corpus gets large enough, or when queries become semantically ambiguous enough, that retrieval itself becomes the bottleneck. Then a tiny specialised model acting as a router/reranker could be a very interesting optimisation.
So I'd rather let the simple solution hit its limits first, measure where it actually breaks, and only then introduce a librarian if the data justifies it.
Which is perhaps another good example of the principle behind the project: don't add an AI component just because you can. 😄
Very true, definitely not something meant as a small scale solution where postgres + pgvector would do a better job, but lets say it gets to stack overflow's scale... That's when the answer hides in plain sight and while a vector lookup can help, it'll be too specific to catch every case and if a LLM needs to reason through a knowledgebase to get to the answer, it loses the efficiency gain, albeit a worthwhile sacrifice for accuracy, it's still a solution derived from a different problem, which means 99% right, 99% of the time.
But overall, on it's own, I dont think it'd be worth it. Rather, I'm more interested in the concept of a drafter for general purpose reasoning. How many tokens do we burn on grep searches? Or indexing a codebase, or diffing vs git? All things that are braindead simple for a LLM to do, yet people waste 3t models on it daily, while their cpu's NPU and gpu sit idle? The use-cases are endless, eg. credential stripping JIT before sending the content to a cloud LLM? Acting like a safe guard between the model and the tool?
This is the part I'd bet on soonest. I build an MCP that a coding agent calls into, and the thing that keeps proving true is that the mediating server, not the model, is where any rule you actually need to hold has to live. The model will call your tools in whatever order it feels like, skip the check step, or confidently act on a premise that was never there, so treating the MCP layer as the place that enforces and validates rather than trusting the caller has saved me more grief than any prompt tweak. The tiny-model-as-pre-filter idea fits that nicely: cheap, deterministic, and it never has to be talked into doing its job.
This is a really great idea. I love the thought of taking those useful little things we figure out while working with AI and turning them into something other people can actually find and use later, instead of letting them disappear into chat history.
I’ve run into a few things that I think could be useful to share, so I might have to contribute something. The human review part is especially nice too. AI can help put the knowledge together, but that doesn’t mean everything it says should automatically become trusted documentation.
Really cool project. I’m interested to see what people add to it.
Thank you! And if you already have a few things in mind that you've learned the hard way, that's exactly the kind of material I'm hoping Shared Knowledge can capture. 😄
The contributor shouldn't have to turn that experience into polished documentation first — that's part of what the MCP and the synthesis workflow are supposed to help with.
And I completely agree about the review boundary. The AI can help extract, structure and generalize something useful, but “the model produced a plausible explanation” is very different from “this is now trusted shared knowledge.”
I'm really curious to see what people end up contributing. The interesting part of the project will probably be what emerges from those small, otherwise-forgotten discoveries once they start accumulating.
I know I definitely have a few “well, that took way longer to figure out than it should have” discoveries sitting around.
I’ve been experimenting with running and converting smaller models lately, and some of the compatibility issues and workarounds might be useful to other people. I’ll have to look through what I’ve got and see what would make a good first contribution.
And yeah, I think that distinction between a plausible explanation and trusted knowledge is really important. It’s easy for something to sound right, especially when an AI explains it confidently, so it's definitely a good idea to have that review step.
I’m really curious to see what people contribute too. I think the little things people figure out along the way could end up being some of the most useful stuff in there.
Absolutely — the smaller-model stuff sounds like exactly the kind of thing that could be valuable there.
Compatibility issues are often a perfect example of knowledge that is painful to discover once, but incredibly useful when someone else can find the answer instead of repeating the same experiment. And the fact that you had to work around them is probably more interesting than a generic “this model works with X” statement — the constraints and the actual workaround are what make the knowledge reusable.
So if you dig through your notes and find a couple of those “why does this work that way?” moments, I'd definitely be interested in seeing them. 😄
And yes, I think that's the core distinction: the AI can help turn those experiences into something structured and reusable, but someone still needs to decide whether the resulting explanation actually deserves to become shared knowledge.
Those little discoveries may well end up being the most valuable part of the corpus precisely because nobody thinks they're worth writing down at the time.
Yeah, exactly! I think the constraints and workarounds are usually the most useful part too. A generic “this model works” doesn’t tell you much when you’ve spent three hours trying to figure out why it doesn’t work on your setup.
I’ve got some notes from a recent experiment that could be a good fit. I might dig through them and see what I can pull together. I like that the MCP can help with the structuring part, because that’s usually the bit that makes me put off writing things down.
Really looking forward to seeing how this grows!
Exactly — and I think that's one of the less obvious problems Shared Knowledge is trying to solve.
The frustrating part is that the useful information is often already there in someone's notes, terminal history, or “three hours of figuring out why this doesn't work” — but turning that into a proper piece of documentation feels like a second, completely different task.
If the MCP can take the messy experience and help structure and generalize it, without requiring the contributor to become a technical writer, then the barrier to sharing becomes much lower.
So definitely dig through those notes when you get a chance. I'd much rather see a rough contribution that can be refined through the workflow than have another useful workaround disappear into someone's project folder. 😄
And I'm curious to see what comes out of your experiment too!
The next thing I'd want as a reader is a small "tested under" block: dependency versions, a minimal input, expected output, and the date someone actually reran it. That can stay in Markdown alongside the solution, without retaining the private conversation.
Your optional-dependency example is a good candidate: can a second person reproduce the import failure and then verify the fix in a clean environment? A merged article and an independently reproduced fix are different kinds of evidence; both are useful, but I'd label them separately.
Would you consider letting the next reader contribute a reproduction result to the existing article rather than another solution? That could make the smallest useful contribution "I checked this on version X; here's what changed," not writing a whole new post.
I like the idea of recording independent reproduction, but I think there is an important constraint here: we can't simply accumulate individual experiences alongside the original solution.
The goal is to synthesize knowledge, not to build a collection of personalized installation stories. If several people independently solve the same problem, the useful result should become something like “Installing n8n on Fedora 18+” or “Installing n8n on Debian / Ubuntu”, rather than a collection of “how Pascal did it”, “how X did it”, etc.
So I agree that an independent reproduction is valuable evidence, but I think that evidence should feed back into the synthesis rather than become another public artifact on its own.
That also means the MCP would need to distinguish between an experience, the synthesized knowledge extracted from multiple experiences, and new evidence that can confirm or challenge that synthesis.
That's actually a rather interesting consequence of the model: the contribution doesn't necessarily produce another article. It can improve an existing piece of shared knowledge.
Yes, that distinction improves what I was suggesting: reproduction should support a shared procedure, not generate another installation article.
I'd keep a compact evidence record attached to the revision it tested: environment, result, and date. The synthesis can then state its supported environments and any unresolved contradictions. A failure on a different OS shouldn't automatically invalidate the procedure for environments where it still works.
The interesting editorial decision is whether new evidence changes the procedure, narrows its scope, or leaves an open question. Would you have a maintainer review those changes, or let the MCP propose a revision with the conflicting evidence attached?
Great project, Pascal, as usual! And I really appreciate the practical, common-sense approach to AI, especially in the middle of all the current AI paranoia. 😄
Thank you, Sylwia! 😄
And coming from you, “as usual” probably means more than you realize. We’ve been around quite a few AI discussions together by now, so I’m glad that this practical, common-sense approach still comes through.
I think there’s a middle ground that often gets lost: neither “AI will solve everything” nor “AI is the source of everything that’s wrong with software and society.” Just build things, see what actually works, understand where it fails, and make sensible decisions from there.
And yes, there is quite enough AI paranoia around at the moment to keep us busy. 😄
Respect for dropping Gemini eligibility to keep the architecture model-agnostic. That's the same kind of scope call I had to make this weekend (cut ElevenLabs entirely rather than force it in for a prize category). The os.environ.get() empty-string-vs-missing-key bug is a good catch too, that exact gotcha gets everyone eventually.
Thank you — and having read your Ajo Chain submission, I think I understand the parallel much better now.
We ended up making almost the same kind of scope decision, for different technologies and for slightly different reasons, but with the same underlying principle: don't let the prize category dictate the architecture.
In my case, keeping Gemini in the critical path would have contradicted the model-agnostic design I was aiming for. In yours, keeping ElevenLabs would have meant spending more time forcing an integration that wasn't essential to the actual product. In both cases, the category became less important than the integrity of the project.
And I particularly appreciate the comparison because that's exactly what I tried to preserve in my article: not a polished account where every technology ends up working perfectly, but the actual reasoning, failures and scope decisions that shaped the final architecture.
Also, apparently the empty-string
os.environ.get()trap is now officially a shared experience. 😄"Don't just ask AI, give back to it" is a great framing for the challenge. Turning personal troubleshooting notes into shared MCP tools is exactly the kind of knowledge compounding the ecosystem needs. We took a similar angle on the server side: making an MCP server something a developer can build in one annotated Java class, so the cost of "sharing" drops to near zero. Nice work.
Thank you! And I like the parallel with what you did on the server side.
I think we're attacking the same problem from two different directions: if contributing knowledge requires a significant amount of extra work, people will naturally keep it to themselves. Your annotated Java class makes the cost of creating an MCP server almost disappear; my goal is to make the cost of turning an already-solved problem into shared knowledge similarly small.
That's really what I meant by “Don't just ask AI, give back to it”. The useful contribution doesn't have to be another piece of work created from scratch — ideally, it should be something that emerges naturally from the work you're already doing.
The interesting part, for me, is what happens once those small contributions start compounding. That's where the MCP becomes more than just another way of calling an AI model.
Wow! Bloody well done!
The explicit human-review gate is the part I’d keep even as the workflow grows. Id also record the source conversation and the final diff with each PR, so a useful extraction stays easy to audit later.
I definitely agree about keeping the human-review gate as the workflow grows. For me, that's a structural part of the architecture, not something to remove once the process becomes more mature.
The audit trail is an interesting point, but I would be very reluctant to retain the source conversation itself. One of the explicit boundaries of the project is that the conversation remains private while the extracted knowledge may become shareable.
Anonymising the conversation before storing it could reduce the risk, but it doesn't eliminate it. There is always a possibility of re-identification through context or information that the anonymisation process failed to catch. And in some cases, the sensitive information isn't even something that can simply be anonymised.
So I'd rather keep the provenance and the approved diff where possible, without turning the private conversation into a persistent artifact. The audit trail should help us understand and verify the knowledge, without creating a back door to the conversation that produced it.
That's a constraint I'll probably explore further as the project evolves.
The ElevenLabs Voice Library trap got me too, same weekend. Mine surfaced as a
402 "Free users cannot use library voices" rather than your invalid_uid, which
was at least readable, but the cause was identical: a voice ID copied out of the
web interface that a free account cannot reach through the API.
Worth flagging for your self-hosted path specifically. "Add the voice to My
Voices" is a manual setup step, and anyone cloning your repo with their own key
hits that wall before they get their first MP3. I gave up on hardcoding a voice
in the end. On a 400, 402 or 404, the code calls /v2/voices, picks one the account
actually has, prefers a British one, retries and remembers the answer. One extra
request, once, and a setup instruction nobody reads disappears.
On Markdown not being built for speech, I came at that from the other end, and it
might save you a step. I stopped sending the document to the TTS engine at all.
The generated text is full of bullet lists, and they read aloud terribly, so the
audio path picks five fields and drops everything else: what the gap is, what the
role exists to change, the time commitment, and who they want to hear from. No
responsibilities list, no skills list. The useful part was that it forced a
decision about what somebody listening actually needs, and it turned out not to
be the whole article. Your narration script step might end up being less about
inserting pauses than about deciding what to leave out.
That's a really useful data point, especially because it confirms the exact distinction I was documenting.
I actually don't think the self-hosted path needs a dynamic voice fallback, though. The intended setup is simpler: go to ElevenLabs → Voice Lab → My Voices, choose a voice that is available to your account/API, then configure the three values explicitly: API key, voice ID and model ID.
The important trap is that a voice being visible and usable in the Voice Library doesn't necessarily mean that its ID is available through the API on a Free plan. That's exactly what caused my misleading
invalid_uiderror. Adding the voice to My Voices changes that entitlement, which is why the same API call starts working. That's also what I documented in the knowledge article.So I wouldn't want the code to silently pick another voice if the configured one isn't available. That would make the setup appear to work while quietly changing one of the user's configuration choices.
Your point does reinforce something useful, though: the setup instructions need to make the Voice Library → My Voices distinction very explicit. That's probably more valuable than trying to make the code guess what the user intended.
And I really like your second point about the audio representation. I think that's going to require a more fundamental rethink than just making Markdown TTS-friendly. The canonical Markdown and the spoken representation probably need to be treated as two different artifacts with two different purposes.
great job
Thanks! Really appreciate it! 🙏
great project pascal
Thank you! Really appreciate it! 🙏
Cover image looks really good!!
Nice write-up!! :D
Thanks! Cover is chatGPT generated on a Claude prompt.
What a good idea 💡