Wiznote

• WIZNOTE_BASE_URL — base URL of the WizNote server, for example https://notes.example.com
• WIZNOTE_USER — WizNote login user ID or email
• WIZNOTE_PASSWORD — WizNote password
• category_root — the top-level WizNote category path to sync under, for example /team/docs/
• repo_root — local repository root used for mirror output

You can pass credentials explicitly or set environment variables.

Available Helpers

Support files live in the same directory:

• wiznote_cli.py
• wiznote_helper.py

Key functions:

• load_credentials(...)
• login(...)
• fetch_note_list(...)
• fetch_note_html(...)
• create_note(...)
• save_note(...)
• normalize_category_root(...)
• resolve_category(...)
• mirror_output_path(...)
• extract_html_body(...)

Quick Reference

1. Import the helpers

from pathlib import Path
import sys

SKILL_DIR = Path("/path/to/wiznote")
sys.path.insert(0, str(SKILL_DIR))

import wiznote_cli as cli
import wiznote_helper as helper

2. Configure credentials

Environment variables:

export WIZNOTE_BASE_URL="https://notes.example.com"
export WIZNOTE_USER="[email protected]"
export WIZNOTE_PASSWORD="your-password"

Or pass them directly:

creds = cli.load_credentials(
    base_url="https://notes.example.com",
    user="[email protected]",
    password="your-password",
)

3. Login once and reuse the session

creds = cli.load_credentials()
login = cli.login(creds)

4. Resolve the category root and target category

category_root = helper.normalize_category_root("/team/docs/")
category = helper.resolve_category(category_root, "plans/")

5. List notes in a category

payload = cli.fetch_note_list(
    base_url=login.kb_server,
    kb_guid=login.kb_guid,
    token=login.token,
    category=category,
)

6. Download note HTML

html = cli.fetch_note_html(
    base_url=login.kb_server,
    kb_guid=login.kb_guid,
    doc_guid="<doc-guid>",
    token=login.token,
)
body = helper.extract_html_body(html)

7. Create or update a note

create_note(...) and save_note(...) expect HTML, not Markdown. Convert local Markdown before upload.

result = cli.create_note(
    base_url=login.kb_server,
    kb_guid=login.kb_guid,
    token=login.token,
    title="Project Design",
    category=category,
    html="<h1>Project Design</h1><p>...</p>",
)

8. Build the mirror path safely

mirror_path = helper.mirror_output_path(
    repo_root=Path("/path/to/repo"),
    category_root=category_root,
    category=category,
    title="Project Design",
)

Operating Pattern

1. Set WIZNOTE_BASE_URL, WIZNOTE_USER, and WIZNOTE_PASSWORD, or pass them explicitly.
2. Normalize your chosen category root with normalize_category_root(category_root).
3. Log in once and reuse login.token, login.kb_server, and login.kb_guid.
4. For reads: resolve the target category, list notes, choose the target note, download HTML, then mirror locally if needed.
5. For writes: prepare HTML, create or update the note in WizNote first, then refresh the local mirror.
6. Re-list the category after each write to verify the note exists.

Setup Steps For New Users

1. Copy this wiznote/ directory into your repo or your Claude skills directory.
2. Install Python 3.
3. If you need Markdown-to-HTML conversion, install a Markdown library such as markdown:

   python3 -m pip install markdown
   

4. Confirm your WizNote server is reachable from the Python runtime you plan to use.
5. Set the three required environment variables or pass credentials explicitly.
6. Choose a category root like /team/docs/ and keep all synced notes under it.
7. Test login and note listing before doing bulk writes.

Mirror Rules

• Canonical source: WizNote.
• Local repo copy: mirror.
• Mirror destination must be produced by mirror_output_path(repo_root, category_root, category, title).
• Reject paths outside the configured category root.

Common Mistakes

• Leaving private values in the published skill. Keep server URLs, usernames, passwords, and local home paths out of the shared copy.
• Writing only to the repo mirror. Update WizNote first when the user wants centralized maintenance.
• Uploading raw Markdown to create_note(...). Convert to HTML first.
• Building target categories manually without validation. Use normalize_category_root(...) and resolve_category(...).
• Building local paths from raw titles. Use mirror_output_path(...) to avoid path escape issues.
• Logging in for every note. Reuse one authenticated session for the batch.