Skip to content

Commit 3e1bf0c

Browse files
authored
[codex] Add Yemot telephone systems skill (#14)
* Add comprehensive Yemot telephony skill * Refine skill catalog naming and icon * Finalize Yemot telephone systems skill
1 parent b4866ad commit 3e1bf0c

178 files changed

Lines changed: 66164 additions & 12 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Release Yemot telephony skill
2+
3+
on:
4+
push:
5+
tags:
6+
- "yemot-telephony-v*"
7+
workflow_dispatch:
8+
inputs:
9+
tag:
10+
description: "Release tag, for example yemot-telephony-v0.1.0"
11+
required: true
12+
type: string
13+
14+
permissions:
15+
contents: write
16+
17+
jobs:
18+
validate-package-release:
19+
runs-on: windows-latest
20+
env:
21+
RELEASE_TAG: ${{ github.event_name == 'push' && github.ref_name || inputs.tag }}
22+
GH_TOKEN: ${{ github.token }}
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- uses: actions/setup-python@v5
27+
with:
28+
python-version: "3.12"
29+
30+
- name: Install site dependency
31+
run: python -m pip install markdown2
32+
33+
- name: Validate skill and snapshot
34+
shell: pwsh
35+
run: |
36+
python skills/yemot-telephony/scripts/validate_snapshot.py
37+
python -m unittest discover -s skills/yemot-telephony/tests -p "test_*.py" -v
38+
python tests/test_build.py -v
39+
python build.py
40+
41+
- name: Package skill
42+
shell: pwsh
43+
run: ./scripts/package-yemot-telephony.ps1 -OutputPath ./dist/yemot-telephony.zip
44+
45+
- name: Create or update GitHub Release
46+
shell: pwsh
47+
run: |
48+
$displayVersion = $env:RELEASE_TAG -replace '^yemot-telephony-', ''
49+
gh release view $env:RELEASE_TAG 2>$null
50+
if ($LASTEXITCODE -ne 0) {
51+
gh release create $env:RELEASE_TAG --title "ימות המשיח — מערכות טלפוניות $displayVersion" --generate-notes
52+
}
53+
gh release upload $env:RELEASE_TAG ./dist/yemot-telephony.zip --clobber

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
__pycache__/
22
tools/GEMINI.md
33
repomix-output.md
4+
dist/

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
אוסף כלים שימושיים וקלי משקל. נוצרו כדי לפתור בעיות קטנות במהירות.
44

5+
## סקילים
6+
7+
- [ימות המשיח — מערכות טלפוניות](skills/yemot-telephony/) - סקיל מקיף ומתועד לבניית מערכות IVR, חיבורי API ו-SIP בימות המשיח, כולל תיעוד רשמי מלא וחיפוש מקומי
8+
59
## כלי דפדפן
610

711
- [מחולל פודקאסטים](tools/podcast_generator.html) - כלי פשוט ליצירת פודקאסטים כולל תסריט ותוכן באמצעות ג'מיני.
@@ -24,4 +28,4 @@
2428
רוב הכלים נכתבו באמצעות **Vibe Code**, והם נועדו לשימוש כמות שהם.
2529
כל אחד מוזמן לשפר, להתאים אותם לצרכיו המדויקים, ולשתף בחזרה.
2630

27-
**וויב קוד הוא העתיד של התכנות.**
31+
**וויב קוד הוא העתיד של התכנות.**

‎build.py‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,20 @@
5858
DOWNLOAD_RELEASE_BUTTON_TEMPLATE = ' <a href="https://github.com/{user}/{repo}/releases/latest/download/{zip_name}"><i data-feather="archive"></i> הורד ZIP</a>'
5959

6060

61+
def classify_tool_section(title):
62+
"""Return the rendering type and Feather icon for a README section."""
63+
title_lower = title.lower()
64+
if 'דפדפן' in title_lower:
65+
return 'web', 'monitor'
66+
if 'scripts' in title_lower or 'סקריפטים' in title_lower:
67+
return 'script', 'code'
68+
if 'extension' in title_lower or 'תוספי' in title_lower:
69+
return 'extension', 'package'
70+
if 'skill' in title_lower or 'סקיל' in title_lower:
71+
return 'skill', 'zap'
72+
return 'other', 'tool'
73+
74+
6175
def generate_tool_html(line, tool_type):
6276
"""מקבל שורה וסוג כלי, ומייצר את ה-HTML המתאים."""
6377
match = TOOL_PATTERN.match(line.strip())
@@ -85,7 +99,7 @@ def generate_tool_html(line, tool_type):
8599
)
86100

87101
action_buttons = []
88-
if tool_type == 'extension':
102+
if tool_type in {'extension', 'skill'}:
89103
action_buttons.append(DOWNLOAD_RELEASE_BUTTON_TEMPLATE.format(
90104
user=GITHUB_USERNAME, repo=GITHUB_REPO_NAME, zip_name=f"{tool_id}.zip"
91105
))
@@ -138,15 +152,7 @@ def main():
138152
tool_lines = [line for line in content.split('\n') if TOOL_PATTERN.match(line.strip())]
139153

140154
if tool_lines: # אם זהו קטע כלים
141-
title_lower = title.lower()
142-
if 'דפדפן' in title_lower:
143-
tool_type, icon = 'web', 'monitor'
144-
elif 'scripts' in title_lower or 'סקריפטים' in title_lower:
145-
tool_type, icon = 'script', 'code'
146-
elif 'extension' in title_lower or 'תוספי' in title_lower:
147-
tool_type, icon = 'extension', 'package'
148-
else:
149-
tool_type, icon = 'other', 'tool'
155+
tool_type, icon = classify_tool_section(title)
150156

151157
final_content_html += f"\n<h2><i data-feather='{icon}'></i> {title}</h2>\n"
152158

@@ -172,4 +178,4 @@ def main():
172178
print(f"\nBuild complete! `{OUTPUT_FILE}` has been generated successfully.")
173179

174180
if __name__ == "__main__":
175-
main()
181+
main()
Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Yemot Telephony Skill Implementation Plan
2+
3+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Checked items are complete; unchecked items remain pending.
4+
5+
**Goal:** Build, validate and publish-ready package a comprehensive Yemot Hamashiach telephony skill while keeping the website integration to one concise catalog card.
6+
7+
**Architecture:** A lean `SKILL.md` routes agents to curated references or readable generated Markdown topics. Refresh, search, validation and packaging scripts make the large external documentation set maintainable without loading it all into context.
8+
9+
**Tech Stack:** Markdown, YAML, Python 3 standard library, PowerShell 7, existing Python/markdown2 site builder, GitHub Actions.
10+
11+
## Current Implementation Status (2026-07-10)
12+
13+
- The complete readable snapshot is implemented and validated: 157 topics, 607 selected posts and 158 Markdown documents.
14+
- `source-manifest.json` is intentionally retained as machine-readable provenance and coverage data. The refresher generates it, the validator requires it, and the release workflow validates it.
15+
- The public display name is `ימות המשיח — מערכות טלפוניות`; the stable technical slug remains `yemot-telephony`.
16+
- The website remains a compact catalog. Its `סקילים` section appears first and exposes only ZIP download and source actions.
17+
- The initial release target is `yemot-telephony-v0.1.0`, reflecting an early-development SemVer release.
18+
- Repository publication status is authoritative in GitHub history; the final unchecked items below intentionally preserve the pre-publication gate recorded by this plan.
19+
20+
## Global Constraints
21+
22+
- Put the skill at `skills/yemot-telephony/`.
23+
- Keep detailed documentation inside the skill, not on the website.
24+
- Use only official Yemot-hosted sources as authoritative documentation; label community replies.
25+
- Do not store live credentials or personal data.
26+
- Perform repository integration and release actions only after validation.
27+
28+
---
29+
30+
### Task 1: Build the documentation corpus pipeline
31+
32+
**Files:**
33+
- Create: `skills/yemot-telephony/scripts/refresh_docs.py`
34+
- Create: `skills/yemot-telephony/scripts/search_docs.py`
35+
- Create: `skills/yemot-telephony/scripts/validate_snapshot.py`
36+
- Create: `skills/yemot-telephony/tests/test_scripts.py`
37+
38+
**Interfaces:**
39+
- `refresh_docs.py --output-dir PATH` produces `snapshot/*.md`, `source-manifest.json` and `source-index.md`.
40+
- `search_docs.py QUERY --snapshot-dir PATH --limit N` prints ranked source-backed Markdown matches with file and source URLs.
41+
- `validate_snapshot.py --references-dir PATH` exits nonzero for invalid or incomplete snapshots.
42+
43+
- [x] Write tests for normalization, post-link resolution, ranking, redaction-safe output and schema validation.
44+
- [x] Run `python -m unittest skills/yemot-telephony/tests/test_scripts.py -v` and confirm the missing modules fail.
45+
- [x] Implement the three standard-library scripts with retry, pagination, deterministic Markdown rendering, bounded file sizes, atomic output and Netfree-aware errors.
46+
- [x] Re-run the unit tests and confirm they pass.
47+
48+
### Task 2: Generate and audit the complete snapshot
49+
50+
**Files:**
51+
- Create: `skills/yemot-telephony/references/snapshot/*.md`
52+
- Create: `skills/yemot-telephony/references/source-manifest.json`
53+
- Create: `skills/yemot-telephony/references/source-index.md`
54+
55+
**Interfaces:**
56+
- Every topic document contains stable topic metadata and post sections with author/authority labels, timestamps, source URLs and complete normalized content. Files above the configured limit are split at Markdown boundaries.
57+
58+
- [x] Run the refresher against the official forum index, API topic and API forum.
59+
- [x] Retry or explicitly record unresolved and inaccessible source links.
60+
- [x] Validate minimum topic/post coverage, unique record IDs, non-empty content and HTTPS source URLs.
61+
- [x] Search representative terms: `type=api`, `recording_and_entering_data`, `CreateSipAccount`, `X-Yemot-CallID`, `queue_api_send` and `M1000`.
62+
63+
### Task 3: Author the skill and curated guidance
64+
65+
**Files:**
66+
- Create: `skills/yemot-telephony/SKILL.md`
67+
- Create: `skills/yemot-telephony/agents/openai.yaml`
68+
- Create: `skills/yemot-telephony/references/concepts-and-workflow.md`
69+
- Create: `skills/yemot-telephony/references/api-and-integrations.md`
70+
- Create: `skills/yemot-telephony/references/practical-recipes.md`
71+
72+
**Interfaces:**
73+
- `SKILL.md` tells agents exactly which reference or search command to use for each task class.
74+
- Curated files contain stable mental models, security practices, implementation sequences and concise tested examples; parameter exhaustiveness remains in the corpus.
75+
76+
- [x] Initialize the skill with the official `init_skill.py` and generated UI strings.
77+
- [x] Replace scaffold placeholders with concise imperative instructions and source hierarchy rules.
78+
- [x] Add practical examples for a basic menu, API extension, management API call and SIP/WebRTC setup without real credentials.
79+
- [x] Run `quick_validate.py` and scan for placeholders, duplicated guidance and unsafe example secrets.
80+
81+
### Task 4: Add minimal catalog and release packaging
82+
83+
**Files:**
84+
- Modify: `README.md`
85+
- Modify: `build.py`
86+
- Modify: `index.html` (generated)
87+
- Create: `scripts/package-yemot-telephony.ps1`
88+
- Create: `.github/workflows/release-yemot-telephony.yml`
89+
- Create: `tests/test_build.py`
90+
91+
**Interfaces:**
92+
- A README section containing `סקיל` is rendered as a skill card with latest-release download and source actions.
93+
- `scripts/package-yemot-telephony.ps1 -OutputPath PATH` creates `yemot-telephony.zip` with a top-level skill folder.
94+
95+
- [x] Write a build test proving the card exposes exactly download and source actions.
96+
- [x] Extend the builder with a dedicated `skill` type and run the test to green.
97+
- [x] Add the concise README entry and regenerate `index.html` with `python build.py`.
98+
- [x] Add deterministic packaging and tag/manual GitHub Actions workflow.
99+
- [x] Build the archive locally and inspect its file list.
100+
101+
### Task 5: Final verification and repository integration
102+
103+
**Files:**
104+
- Verify all files changed by Tasks 1-4.
105+
106+
**Interfaces:**
107+
- The full verification command set is reproducible from a clean checkout.
108+
109+
- [x] Run all Python unit tests, corpus validation, skill validation and the site build.
110+
- [x] Confirm `git diff --check` and scan the final diff for secrets and unrelated changes.
111+
- [x] Confirm the website contains no detailed Yemot documentation.
112+
- [ ] Commit the complete focused change only after every check passes.
113+
- [ ] Push the feature branch and create a release/tag only if the release asset workflow and repository state are ready.
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Yemot Telephony Skill Design
2+
3+
## Goal
4+
5+
Add a repository-hosted Codex skill that gives agents practical, source-backed knowledge for building and operating Yemot Hamashiach telephone systems and telephone integrations. Keep the NH Local website a lightweight project catalog with a short download entry only.
6+
7+
## Scope
8+
9+
The skill covers:
10+
11+
- IVR system structure, extensions, paths, files, messages, identification and shared settings.
12+
- Content, recording, playback, live broadcast, routing, queues, campaigns, data collection, sales, payments, messaging and administration modules.
13+
- The interactive `api` extension protocol used to connect a phone call to an external web application.
14+
- The management API at `https://www.call2all.co.il/ym/api/`, including authentication, files, campaigns, calls, tasks and SIP account management.
15+
- SIP, UDP, secure WebSocket and WebRTC integration details documented by Yemot.
16+
- Troubleshooting, security, validation and production rollout practices.
17+
18+
The source snapshot is based on the official Yemot website and the two Yemot-hosted documentation forums. Community replies remain searchable but are labelled separately from source posts and administrator-authored material.
19+
20+
## Architecture
21+
22+
Create `skills/yemot-telephony/` with a concise routing-oriented `SKILL.md`, UI metadata, focused curated references, a readable Markdown documentation snapshot, and deterministic maintenance/search scripts.
23+
24+
Store the full snapshot as one generated Markdown document per source topic under `references/snapshot/`. Preserve direct topic/post URLs, topic/post identifiers, author/authority labels, timestamps and normalized technical content. Split exceptional files at Markdown boundaries so no reference file becomes costly to inspect. Do not duplicate the original rendered HTML. Agents may use ordinary `rg` or `scripts/search_docs.py`, and humans can review changes directly in Git.
25+
26+
`scripts/refresh_docs.py` rebuilds the snapshot from the official NodeBB APIs, follows the central documentation index, includes the management API and SIP topics, paginates long topics, retries transient failures and writes a coverage manifest. Generate deterministic topic files whose contents do not change merely because a refresh was run. A validator checks structure, uniqueness, HTTPS source URLs, file-size limits and minimum coverage.
27+
28+
## Website Integration
29+
30+
Add a single `סקילים` section to `README.md`. Extend `build.py` with a skill item type whose actions are only:
31+
32+
- Download the latest `yemot-telephony.zip` release asset.
33+
- Open the skill source folder on GitHub.
34+
35+
No Yemot documentation, search interface or dedicated documentation page is added to the website.
36+
37+
## Release Packaging
38+
39+
Add a deterministic PowerShell packaging script and a GitHub Actions workflow triggered by a `yemot-telephony-v*` tag or manual dispatch. The archive contains only the skill directory under a top-level `yemot-telephony/` folder and excludes caches. Publishing an actual GitHub Release is deferred until all local validation succeeds.
40+
41+
## Safety and Freshness
42+
43+
- Never embed real system numbers, passwords, API tokens, caller IDs or customer data in examples.
44+
- Prefer POST for credentials and sensitive parameters; redact secrets from logs and URLs.
45+
- Treat billing, caller-ID authorization, SIP availability, limits and prices as volatile and verify them against linked sources before production use.
46+
- Preserve the retrieval timestamp and direct source URL for every corpus record.
47+
- Report HTTP 418 or certificate failures as possible Netfree filtering and keep the previous valid snapshot intact on refresh failure.
48+
49+
## Implemented Decisions (2026-07-10)
50+
51+
- Keep `source-manifest.json`: it is operational metadata used by refresh, validation and release automation, not a duplicate documentation payload.
52+
- Keep these Superpowers planning documents in the repository for future maintenance history; exclude them from the distributable skill ZIP.
53+
- Use `ימות המשיח — מערכות טלפוניות` as the human-facing name and retain `yemot-telephony` for stable machine paths, release assets and tags.
54+
- Place the concise `סקילים` catalog section before other project categories.
55+
- Start at `v0.1.0` because the skill is in initial development. Publish it as the latest normal GitHub Release so the website's stable `releases/latest/download/yemot-telephony.zip` link remains valid.
56+
57+
## Verification
58+
59+
- Validate skill metadata with the official `quick_validate.py`.
60+
- Run corpus schema and coverage validation.
61+
- Exercise search against representative IVR, API-module, management-API and SIP queries.
62+
- Rebuild `index.html` and confirm the catalog contains only the concise skill card.
63+
- Build the ZIP twice and compare its file list and checksums where timestamps permit.
64+
- Check links and inspect the final Git diff before any commit, push or release.

‎index.html‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,24 @@ <h1><img src="favicon.png" alt="" class="favicon-title" aria-hidden="true" /> א
211211

212212
<p>אוסף כלים שימושיים וקלי משקל. נוצרו כדי לפתור בעיות קטנות במהירות.</p>
213213

214+
<h2><i data-feather='zap'></i> סקילים</h2>
215+
216+
<div class="tool-item" id="yemot-telephony">
217+
<div class="tool-main-content">
218+
<a href="#yemot-telephony" class="link-icon" onclick="copyDirectLink(this, event)" title="העתק קישור ישיר">
219+
<i data-feather="link"></i>
220+
</a>
221+
<div class="tool-info">
222+
<h3>ימות המשיח — מערכות טלפוניות</h3>
223+
<p>סקיל מקיף ומתועד לבניית מערכות IVR, חיבורי API ו-SIP בימות המשיח, כולל תיעוד רשמי מלא וחיפוש מקומי</p>
224+
</div>
225+
</div>
226+
<div class="tool-actions">
227+
<a href="https://github.com/nhlocal/tools/releases/latest/download/yemot-telephony.zip"><i data-feather="archive"></i> הורד ZIP</a>
228+
<a href="https://github.com/nhlocal/tools/tree/main/skills/yemot-telephony/"><i data-feather="github"></i> קוד מקור</a>
229+
</div>
230+
</div>
231+
214232
<h2><i data-feather='monitor'></i> כלי דפדפן</h2>
215233

216234
<div class="tool-item" id="podcast_generator">

0 commit comments

Comments
 (0)