feat: optional name field, AI-optimized descriptions, auto-name generation (v1.4.0)

[Puma7]

Summary

This PR improves the BookStack node for AI agent / MCP usage by making the name field optional on Create operations and significantly improving all tool descriptions so that LLMs can use the BookStack tools correctly and token-efficiently.

Key changes:

• Optional name on Create: The name field is no longer required for Page, Book, Chapter, and Shelf creation. When omitted, the node auto-generates a name from the content (markdown headings, first text line, description, or timestamp fallback).
• AI-optimized tool descriptions: Every field description has been rewritten so that an LLM knows exactly what each tool does, what parameters to provide, what the response contains, and when to use which operation.
• Token-efficient navigation strategy: Descriptions guide AI agents to use Search first (returns only IDs and previews), then Get by ID for full content - preventing catastrophic token usage on large BookStack instances.
• Markdown-first approach: Descriptions recommend markdown over HTML (~3x fewer tokens) and warn against setting both simultaneously.
• Archive-first best practice: Node description suggests moving content to an Archive shelf instead of permanent deletion.
• QA documentation: Added KNOWN_ISSUES.md (20 pre-existing issues documented), updated CLAUDE.md (project knowledge base for AI-assisted development), and comprehensive CHANGELOG.md.

Files changed:

• nodes/Bookstack/Bookstack.node.ts — auto-name generation logic (generateFallbackName, decodeHtmlEntities), updated node description
• nodes/Bookstack/descriptions/*.ts — all 9 description files updated with improved field descriptions and consistent action texts
• CLAUDE.md — new project knowledge base for LLM-assisted development
• KNOWN_ISSUES.md — 20 pre-existing issues documented during QA audit
• CHANGELOG.md — complete v1.4.0 changelog
• package.json — version bump to 1.4.0

Important: Testing status & recommendation

⚠️ This PR has been tested in a local development environment (pnpm run dev via Docker) but NOT yet in a production n8n instance.

I was unable to test this in my live n8n environment directly. The changes work correctly in the dev environment (TypeScript compiles, node loads, operations are visible in the UI), but I strongly recommend the following before merging to main:

1. Test in a real n8n instance with an actual BookStack connection:

   • Create a page without providing a name → verify auto-generated name
   • Create a page with a name → verify it still works as before (no regression)
   • Test Global Search → verify results return correctly
   • Test as an AI Agent tool → verify LLM receives and understands the descriptions

2. Consider publishing as a beta/pre-release version first (e.g., 1.4.0-beta.1 on npm) so users can test before it becomes the default. If n8n community nodes support pre-release tags, this would allow early adopters to opt in via npm install n8n-nodes-bookstack@beta while the stable version remains on 1.3.0.

3. No breaking changes were introduced — all existing workflows that provide a name on Create will continue to work identically. The only behavioral difference is that omitting the name now succeeds (with auto-generation) instead of being blocked by the UI.

Motivation

When using BookStack as an AI Agent tool via MCP in n8n, the AI was forced to ask the user for a name on every Create operation because name was marked as required. This broke the automated workflow where an AI agent should be able to create, organize, and manage BookStack content autonomously (e.g., receiving notes via webhook, searching for the right location, and filing them automatically).

The improved descriptions also ensure that any LLM using these tools knows:

• The BookStack hierarchy (Shelves > Books > Chapters > Pages)
• How to search efficiently (Global Search first, then Get by ID)
• How to move content (Update with new parent IDs)
• That markdown is preferred over HTML for token efficiency
• What each API response contains
• That delete is permanent and cascading

QA audit results

Three independent automated QA audits were performed covering:

• Every execution path through the node
• All field descriptions for LLM correctness (simulated 10 real tasks)
• All supporting files (API helpers, credentials, config, documentation)

Result: 0 critical issues, 0 regressions from v1.4.0 changes. 20 pre-existing issues were found and documented in KNOWN_ISSUES.md (none introduced by this PR).

Hope to her from you :)

[Puma7]

I ran into a practical issue when using the BookStack node as an AI agent tool via MCP in n8n:
the name field was marked as required on all Create operations, which forced the LLM to
always ask me for a name instead of just generating one automatically from the content.
This basically broke the autonomous workflow I was trying to build (webhook → AI reads content
→ AI organizes it in the right place).

So I went ahead and made name optional with an auto-generation fallback, and while I was at
it, Claude (the AI assistant I used for development) flagged quite a few additional improvements
and pre-existing issues. I tried to keep the PR as focused as possible, but it naturally grew
a bit since the descriptions needed a proper overhaul for AI agent usage.

Key changes:

• name optional on Create with auto-generation from content
• All descriptions rewritten for LLM tool-use clarity
• Tags now support name:value pairs (was a pre-existing gap)
• Added CLAUDE.md, KNOWN_ISSUES.md (27 documented issues, mostly pre-existing)

Important: This has been tested in a local dev environment (Docker + pnpm run dev)
and everything works as expected, but I have NOT tested it in a production n8n instance yet.
I'd strongly recommend testing this as a beta before merging to main. If there's a way to
publish a pre-release version (e.g. 1.4.0-beta.1) on npm, that would be ideal so users
can opt in for testing.

Happy to discuss any of the changes or adjust things if needed!

[daviserez]

lgtm

[Puma7]

Suggested workflow for this PR

1. Merge the PR
2. Set version to 1.4.0-beta.1 and publish with npm publish --tag beta
3. Testers install via npm install n8n-nodes-bookstack@beta in their n8n environment
4. After successful testing, set version to 1.4.0 and npm publish (becomes stable)

Optional: automate with GitHub Actions

If you'd like to automate this in the future, you can add a GitHub Actions workflow that automatically publishes to npm when you create a GitHub Release:

• Release tagged v1.4.0-beta.1 → publishes to npm with --tag beta
• Release tagged v1.4.0 → publishes to npm as latest

This way you'd never have to run npm publish manually — just create a release on GitHub and the CI handles the rest.

More details on dist-tags: https://docs.npmjs.com/adding-dist-tags-to-packages

n8n's GUI "Update" button only checks the latest tag, so stabel users won't accidentally get pushed a beta — they have to explicitly choose it.

[lucaguindani]

Hello @Puma7, thanks for your PR and your interest in this community node!

Unfortunately I do not agree with @daviserez review. I have a few thoughts before we can consider merging.

Multiple features in a single PR

This PR bundles several independent changes together. Each PR should ideally be limited to a single feature or concern to ensure clarity, easier review, and better traceability. I'd suggest splitting this into three separate PRs:

1. Make name optional on Create with auto-generation fallback
2. Improve descriptions for clarity
3. Add name:value support for tags

Also, please do not bump the version number in package.json, this will be done upon release.

1. Make name optional on Create

Rather than removing required: true, which silently changes the UI behaviour for manual users, I'd suggest a cleaner alternative that keeps it.

N8n field default values support expressions, so you can pre-populate the field with a timestamp so it always has a valid non-empty value, while keeping required: true. For instance:

{
    displayName: 'Name',
    name: 'name',
    type: 'string',
    required: true,
    displayOptions: { show: { resource: ['page'], operation: ['create'] } },
    default: '=page-{{$now.toFormat("yyyyMMdd-HHmmss")}}',
    description: 'Page title (max 255 chars). Defaults to the current timestamp.',
}

This way:

• Manual users always see a pre-filled value and are never surprised by an auto-generated name they didn't notice
• The field contract (required: true) is preserved
• No content-extraction logic is needed

The content-extraction approach in the PR (generateFallbackName, decodeHtmlEntities) adds complexity for a problem that is better solved at the field level. If an AI agent or user doesn't provide a name, a timestamp is seems sufficient. Reverse-engineering a title from HTML/markdown content seems fragile and redundant when the caller already knows what the content is about.

2. Improve descriptions for clarity

Improving descriptions and action labels is welcome. However, descriptions should remain useful to all users of the node, not just those using it with an AI agent. References to LLMs, tokens, or AI-specific strategies (e.g. "save tokens", "AI should generate", etc.) should be rephrased in neutral terms that are equally helpful in a manual or automated workflow context.

3. Tags name:value support

This is a clean, self-contained improvement, happy to merge it as a standalone PR.

---

Thanks again for the thorough write-up and the KNOWN_ISSUES.md, that's genuinely appreciated. Happy to review follow-up PRs once split.

[Puma7]

Quick question: Do you know why the name field specifically doesn't show the
"✦ Defined automatically by the model" button when the node is used as an AI agent tool?

All other fields (Book ID, Chapter ID, Markdown Content, Tags) show it, but name
doesn't — both in the original v1.3.0 (with required: true) and in my fork (without
required: true). The behavior is identical in both versions.

I'm wondering if n8n internally excludes parameters literally named name from the
$fromAI() feature, or if there's something else going on. This was the original
motivation for the PR — I wanted the AI agent to generate page titles automatically,
but couldn't find a way to enable it on the name field.

I’ll take a look at the best way to split the PR.

[Puma7]

Update: Found the root cause — n8n doesn't show the $fromAI button for fields named "name"

I did some testing and I think I found the actual issue. It seems like n8n internally
excludes fields with the parameter name name from the "✦ Defined automatically by the
model" feature. This isn't related to required: true — I tested with and without it,
and the button never appears on the name field.

To verify this, I added a second field called page_title with identical configuration
(same type, same displayOptions, no required: true). The $fromAI button immediately
appeared on it:

As you can see:

• Page Title (AI) → ✦ button available ✅
• Name → no ✦ button ✗ (same as before)

So the issue appears to be an n8n framework limitation specifically with the parameter
name name. This might be worth raising as a bug/feature request on the n8n repo.

The question: how should we handle this?

Right now my fork has both fields, where page_title overrides name if set. But having
two fields for the same thing is not ideal UX. I see a few options:

Option A: Add page_title as a second field (current state in my fork)

• Pro: No breaking change, existing workflows using name still work
• Con: Two fields for the same purpose, confusing for users

Option B: Rename the original field from name to something like title

• Pro: Clean, single field, $fromAI button would work
• Con: Breaking change — existing workflows that set name would stop working

Option C: Keep only name and accept the n8n limitation

• Pro: No extra complexity
• Con: AI agents can't generate page titles via $fromAI

What would be your preferred approach? I'm happy to adjust the PR accordingly.

Update 1:

Just checked if renaming from name to test name works and it worked.
@lucaguindani waiting for your advice on Option A+B+C

[lucaguindani]

Thanks for digging into this, that's a really useful finding and it explains the original motivation for the PR much better.

This does look like an n8n framework limitation. The parameter name is likely reserved or excluded from the $fromAI() feature internally. I'd recommend opening an issue on the n8n repository to confirm whether this is a bug or an intentional limitation before we decide how to handle it on our side.

On your three options:

• Option A (two fields) - not acceptable, as you noted it creates confusing UX for all users
• Option B (rename name -> title) - this would be a big breaking change for existing workflows, so it's off the table for now
• Option C (keep name and accept the limitation) - this is the right approach until we have clarity from n8n

So for now, I think option C is the way to go. If n8n confirms it's a bug and fixes it, no change is needed on our side. If they consider it a limitation with a recommended workaround, we can revisit at that point.

[Puma7]

@lucaguindani
Quick update: I've opened an issue on the n8n repo to clarify the name field limitation:
n8n-io/n8n#28261

I'll wait for n8n's response before making any further changes here. Once we know if it's a bug they'll fix or a permanent limitation, we can decide on the best approach for this node.

Thanks for your patience and the helpful feedback on the PR!

[lucaguindani]

Looks like the issue was fixed by n8n (n8n-io/n8n#28763). Should be available in the next releases !

@Puma7 I'll closed this PR since no change is needed on our end, but you're welcome to make a new one for the tags name:value feature 🙂

[Puma7]

Looks like the issue was fixed by n8n (n8n-io/n8n#28763). Should be available in the next releases !

@Puma7 I'll closed this PR since no change is needed on our end, but you're welcome to make a new one for the tags name:value feature 🙂

@lucaguindani
Hi,

thanks again for the clarification and for closing the loop on this. It is great to hear that n8n has fixed the name field issue on their side.

I will definitely keep looking at your BookStack integration, because I still find the overall direction very interesting. My broader use case is a bit bigger than “books” in the classic sense: I am thinking more about long-term life documentation and practical knowledge management.

For example, there are all kinds of small but important pieces of information you may want to preserve over many years, such as where a certain power cable runs in a house, which cross-sections were used, what was changed over time, family-related information, technical notes, procedures, and so on. The same idea also applies to companies that want to store operational knowledge in a structured and durable way.

My original concept was to have an “inbox” where you can throw information at an AI, and the AI then sorts it into the right place in BookStack automatically. In that sense, BookStack looked very attractive as a human-readable knowledge base.

After more testing, though, I am no longer fully sure whether BookStack is the ideal long-term foundation for that kind of workflow. My current impression is that for reliable later retrieval, especially with AI, you probably need a proper RAG or hybrid search layer rather than trying to query the BookStack database more directly through an agent. Also, writing new information back into BookStack in a token-efficient way is not trivial, because in many cases you are effectively replacing or resubmitting whole pages instead of appending or patching very precisely.

That is why I increasingly understand why many people prefer a simpler markdown-on-filesystem approach: it is easier to version, easier to patch line-by-line, and often easier to integrate into AI workflows. Still, I have not reached a final conclusion yet. I think a lot of people are currently exploring the same question: what is the simplest and most durable way to store knowledge over decades so that both humans and AI systems can find and use it well?

So I am not at the end of that journey yet, but I am very curious to see how this ecosystem evolves. BookStack may still be part of that picture, even if perhaps not as the only layer.

Thanks again for your feedback and for maintaining the project.