Feedback: tighten vana-connect contributor workflow and docs

[callumflack]

Why I am opening this

This PR is a discussion vehicle, not a code/docs patch proposal. The branch only contains an empty commit so the feedback can live in the PR description rather than in the repo.

While building and validating the Claude connector, I found the overall connector model strong, but I also hit enough ambiguity in the skill/docs/runtime story that I think it is worth aligning as a team before we add more connectors.

What worked well

• the overall connector shape is good: research, implement, validate, register
• the guidance to inspect the live product instead of guessing was correct and important
• the page API reference was useful in practice
• the validator did real work as a quality gate

What was confusing or not good enough

1. Too many overlapping workflows

In practice I found multiple paths described as if they were all current:

• vana sources
• vana connect
• node run-connector.cjs ...
• skills/vana-connect/scripts/run-connector.cjs ...
• references to ~/.dataconnect/...

That makes it hard to know which workflow is actually canonical for contributors working inside this repo today.

2. Runtime/path drift

Some docs still refer to ~/.dataconnect, but on my machine the live runtime state, logs, and results were under ~/.vana. That mismatch affects setup, validation, and debugging.

3. Validator command drift

I ran into multiple validator entrypoints:

• node scripts/validate-connector.cjs ...
• node skills/vana-connect/scripts/validate.cjs ...
• docs that still mention node scripts/validate.cjs ...

This is unnecessarily confusing.

4. Local repo discovery through vana is under-documented

One of the most important practical discoveries was that vana can discover connectors from this repo when run from the repo root because it finds registry.json. That behavior mattered a lot and should be stated more clearly.

5. Standalone runner guidance felt stale for the actual repo workflow

In the real Claude build loop, the reliable path was the CLI:

• vana connect claude --json --no-input

The older runner-centric guidance was not the path that got the connector over the line.

6. README feels behind reality

The root README still reads like an older runner-centric architecture in places, while the skill points toward a CLI-first flow.

7. Validator gotchas are not documented clearly enough

I hit a validator behavior where nullable fields listed as required were effectively treated as missing in output validation. That is the kind of thing contributors should not have to discover the hard way.

8. Manual-login-first should be described more explicitly as acceptable

The docs talk a lot about credential flows, but they do not say strongly enough that a connector can still be valid and mergeable if it is manual-login-first because auth is brittle, CAPTCHA-heavy, or tied to third-party providers.

What I had to learn by doing

• the live Claude app used authenticated APIs that were not discoverable from the skill alone
• the correct local execution path was the vana CLI, not the older standalone runner guidance
• the runtime state was under ~/.vana, not ~/.dataconnect
• the local repo could act as a source registry for vana when run from this checkout
• the validator had stricter/stranger behavior than the docs implied

What I would improve

1. Make one workflow canonical

For contributors working in this repo, the docs should state a single primary path such as:

• use vana sources --json
• use vana connect <platform> --json --no-input
• use node scripts/validate-connector.cjs ...
• use node skills/vana-connect/scripts/register.cjs ...

Everything else should be described as secondary, legacy, or debugging-only if that is the case.

2. Add a short current-architecture section

This should explain:

• what the current CLI is
• how local repo discovery works
• where runtime state and logs live
• how results are stored
• when the connector is being pulled from the repo versus a cached location

3. Unify validator guidance

Pick one validator command to recommend in the main workflow and explain when the others are relevant.

4. Add a short known-gotchas section

For example:

• nullable + required schema behavior
• need to re-register after connector edits
• browser session reuse can hide auth problems
• manual login is often acceptable
• real platform inspection beats remembered product knowledge

5. Update the README to match the actual contributor path

If the intended flow is now CLI-first, the README should reflect that more directly.

6. Add a what-good-looks-like checklist for connector PRs

For example:

• connector works against a real account
• structure validation passes
• output validation passes
• scopes are meaningful
• PR explains tradeoffs and follow-ups
• unrelated repo/tooling churn is avoided unless necessary

7. Be more explicit about acceptable auth tradeoffs

The docs should say plainly that a connector can still be valid and mergeable if:

• it is manual-login-first
• auth automation is deferred to a follow-up
• the data extraction itself is strong and validated

Question for the team

Would it make sense to tighten the skill/docs around a single contributor workflow now, before adding many more connectors, so contributors spend less time reconciling multiple mental models?

[github-actions]

Schema Health Check — Non-blocking inherited issues

41/47 scopes consistent | 6 inherited Gateway gap(s) | no new blocking issues in this PR