ߛߓߍ ߞߏ ߢߊ (Cultural Code Comments)

# Python package
pip install nko-comments

# CLI tool
nko-comment suggest my_code.py

# VS Code extension
cd vscode-extension
npm install && npm run compile
vsce package
code --install-extension nko-cultural-comments-0.8.0.vsix

# LSP Server (Gen 8!) — Works with Neovim, Emacs, Helix, Sublime Text
cd lsp-server
npm install && npm run build
npm link  # Makes nko-cultural-lsp available globally

# ߓߊ ߕߍ ߥߊ߫ ߞߐ ߝߍ߬
# "The river doesn't go backwards"
# Once an error is handled, we move forward—never retry blindly.
def process_with_recovery(data):
    try:
        return transform(data)
    except TransformError as e:
        log_error(e)
        return fallback(data)  # Flow forward, not back

# Suggest proverbs for a file
$ nko-comment suggest api.py

Found 4 wisdom moments:

Line 23 (async/await pattern):
  ߢߍߥߟߊ ߦߋ ߣߡߊ — "Patience is wisdom"

Line 47 (collaborative function):
  ߓߟߏ ߞߋߟߋ߲ ߕߍ ߓߎ߬ߙߎ ߕߊ — "One hand cannot grab flour"

# Auto-insert cultural comments
$ nko-comment insert api.py --interactive

## API Design Philosophy

> ߞߎ߲ ߞߋߟߋ߲ ߕߍ ߜߊ߬ߙߊ ߕߊ
> *"One head doesn't carry the roof"*

Our API is designed for composition. No single endpoint does everything.
Each service carries part of the load—together, they shelter the system.

from nko_comments import CulturalComments

cc = CulturalComments()

# Get wisdom for a concept
wisdom = cc.for_concept("error-handling")
print(wisdom.nko)      # ߓߊ ߕߍ ߥߊ߫ ߞߐ ߝߍ߬
print(wisdom.meaning)  # The river doesn't go backwards
print(wisdom.applied)  # Handle errors, then move forward

# Analyze code for cultural comment opportunities
suggestions = cc.analyze_file("my_code.py")
for s in suggestions:
    print(f"Line {s.line}: {s.proverb.nko}")
    print(f"  Why: {s.rationale}")

# Generate docstring with cultural wisdom
docstring = cc.generate_docstring(
    function_name="distributed_consensus",
    concept="collaboration"
)

cd Desktop/nko-code-comments/git-hooks

# Install for current repository
./install.sh

# Install globally for all repositories
./install.sh --global

# .github/workflows/cultural-comments.yml
name: Cultural Code Comments

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  wisdom:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nko-comments/cultural-comments-action@v1
        with:
          github-[sensitive field redacted]
          comment-style: both  # inline|summary|both

cd dashboard
npm install
npm start
# Opens http://localhost:3847

# Python
from dashboard.client.reporter import WisdomReporter

reporter = WisdomReporter('http://localhost:3847')
reporter.report(
    file_path='api.py',
    concept='async',
    proverb_nko='ߢߍߥߟߊ ߦߋ ߣߡߊ',
    proverb_english='Patience is wisdom',
    line_number=42
)

# Git post-commit hook
python -m dashboard.client.reporter post-commit

NKO_DASHBOARD_URL=http://localhost:3847  # Dashboard URL
PORT=3847                                  # Server port

cd lsp-server
npm install && npm run build
npm link  # Installs nko-cultural-lsp globally

-- Neovim example
lspconfig.nko_cultural.setup({})
-- Then: <leader>nw to insert wisdom, <leader>nr for random proverb

cc.add_proverb(
    nko="ߖߐ߬ߙߌ ߦߋ ߛߌ߲ߘߌ ߛߓߍ",
    latin="jori ye sindi sebe",
    english="Testing is the writing of knowledge",
    concept="testing",
    applied="Tests are documentation that proves understanding"
)

cd ai-wisdom-engine

# Analyze a code file
./nko-wisdom analyze my_code.py

# Get random wisdom
./nko-wisdom random

# Browse by category
./nko-wisdom categories
./nko-wisdom category async

# Start REST API server
./nko-wisdom serve 8420

# Generate LLM prompt for deep analysis
./nko-wisdom prompt my_code.py

# Random wisdom
curl http://localhost:8420/random

# List all proverbs
curl http://localhost:8420/proverbs

# Get by category
curl http://localhost:8420/category/async

# Suggest for code
curl -X POST http://localhost:8420/suggest \
  -H "Content-Type: application/json" \
  -d '{"code": "async def fetch_data(): await api.get()", "language": "python"}'

# Deep analysis
curl -X POST http://localhost:8420/analyze \
  -H "Content-Type: application/json" \
  -d '{"code": "try: ... except: ...", "language": "python"}'

from llm_integration import LLMWisdomIntegration

integration = LLMWisdomIntegration()

# Generate analysis prompt for Claude/GPT
prompt = integration.generate_analysis_prompt(code, "python")

# Generate teaching prompt for a specific proverb
teaching = integration.generate_teaching_prompt("ߢߍߥߟߊ ߦߋ ߣߡߊ")

# Get plugin config for editor integrations
config = integration.create_plugin_config()

cd pedagogy
python3 nko-pedagogy kata list               # Browse katas
python3 nko-pedagogy kata start river-flow    # Begin a kata
python3 nko-pedagogy kata hint river-flow 0   # Get a hint
python3 nko-pedagogy kata complete river-flow # Unlock wisdom
python3 nko-pedagogy kata journal             # View unlocked wisdom

python3 nko-pedagogy bridge map                    # Full wisdom map
python3 nko-pedagogy bridge bridge error-handling   # See parallels
python3 nko-pedagogy bridge culture Japanese        # Filter by culture
python3 nko-pedagogy bridge comment async --lang rust  # Generate multi-cultural comment

python3 nko-pedagogy tutorial list                     # Browse tutorials
python3 nko-pedagogy tutorial preview resilient-api     # Preview in terminal
python3 nko-pedagogy tutorial generate resilient-api    # Save as Markdown
python3 nko-pedagogy tutorial generate resilient-api -f notebook  # Jupyter notebook