NcfPackageSources Beginner Quickstart (60 Minutes)

Scope: current NcfPackageSources version
This is a source-repository quickstart, not a prerequisite for Template-based development. It was checked against the development line on 2026-07-27.

1. What You Will Finish With This Guide

If this is your first time touching NCF source code, this guide gets you from zero to usable in about 60 minutes:

• Clone and build NcfPackageSources.
• Run the simulated host site Senparc.Web.
• Complete first-time installation, admin login, and module enablement.
• Validate a minimum AI / RAG flow.
• Know where to troubleshoot first when errors appear.

2. Prerequisites Checklist

Item	Requirement	How to Verify
OS	Windows / macOS / Linux	-
.NET SDK	10.0 (aligned with the current simulated site and XNCF template)	dotnet --version
Git	Able to clone repositories	git --version
Browser	Chrome / Edge / Safari	-
Local port	5000 (HTTP) is available	Check Now listening on in startup logs
Database	Start with default SQLite	No extra install needed

If your environment is not ready yet:

• Development Environment
• Get NCF Template Source Code

3. Minute 0-10: Clone and Confirm Commit

git clone https://github.com/NeuCharFramework/NcfPackageSources.git
cd NcfPackageSources
git rev-parse --short HEAD

Expected result:

• A short SHA is printed. Record it in issue reports and validation notes.

4. Minute 10-20: Restore and Build

dotnet restore src/NcfPackageSources_Include_NcfSimulatedSite.sln
dotnet build src/NcfPackageSources_Include_NcfSimulatedSite.sln

Expected result:

• restore completes without blocking errors.
• build ends with Build succeeded..

5. Minute 20-30: Run the Simulated Host Site

dotnet run --project tools/NcfSimulatedSite/Senparc.Web/Senparc.Web.csproj --launch-profile http

Expected result:

• Logs include Now listening on.
• With the command above, it should include http://localhost:5000.

Then open: http://localhost:5000

For the local HTTPS profile, use --launch-profile https and open https://localhost:5111. https://localhost:5001 belongs to the Docker profile and is not the normal dotnet run default.

On first run, seeing the installer is expected.

6. Minute 30-40: Complete Installer and Admin Login

Recommended order:

1. Finish the installer wizard. Reference: Installation
2. Sign in as administrator. Reference: Admin Login
3. Open admin backend and verify left menu loads. Reference: Admin Backend

Expected result:

• You can enter the admin homepage.
• Module management is accessible.

7. Minute 40-50: Enable Minimum AI / RAG Module Set

First-time installation already preselects AIKernel, PromptRange, AgentsManager, and MCP (together with Administrator and XncfBuilder). Verify the confirmation list and complete installation. If you cancelled earlier, install and enable them from Module Management.

The RAG loop additionally requires:

• Senparc.Xncf.KnowledgeBase

This section uses the following module combination:

• Senparc.Xncf.AIKernel
• Senparc.Xncf.PromptRange
• Senparc.Xncf.AgentsManager
• Senparc.Xncf.KnowledgeBase (not selected by default)
• Senparc.Xncf.MCP (only when validating MCP routing)

Reference: Module Management

Expected result:

• Module status shows installed/enabled (or equivalent labels).
• Corresponding admin menu entries are visible and openable.

8. Minute 50-60: Run a Minimum End-to-End Validation

Use the smallest possible action chain:

1. Configure available models in AIKernel (at least one chat model, preferably one embedding model too).
2. Create one PromptCode in PromptRange.
3. Import a test document in KnowledgeBase and run embedding.
4. Run recall test in KnowledgeBase and confirm matched chunks are returned.
5. (Optional) Create an Agent template in AgentsManager that references PromptCode and run a test.

Expected result:

• Embedding task completes.
• Recall test returns valid chunks.
• Agent test no longer fails with “model not configured”.

9. Troubleshooting Matrix (Check This First)

Symptom	Common Cause	Fix
dotnet command not found	SDK missing or PATH not refreshed	Install/repair .NET SDK, reopen terminal, run dotnet --info
restore fails (timeout/source unavailable)	Network or NuGet feed issue	Verify network, retry dotnet restore, switch NuGet source if needed
build fails (SDK mismatch)	Local SDK is too old	Upgrade to .NET 10 SDK, rerun dotnet build
Startup port conflict	5000 or 5111 already used	Change the profile in tools/NcfSimulatedSite/Senparc.Web/Properties/launchSettings.json or specify a URL explicitly
Installer page keeps showing	Initial install not finished or DB init failed	Redo installer flow and inspect startup logs
Module menu not visible after install	Module not enabled or insufficient permission	Recheck module state and admin role permissions
Function count is 0	Missing [FunctionRender] or scan miss	Check AppService annotations and restart app
MCP route returns 404	EnableMcpServer disabled or not registered	Check module Register config and startup registration path
AppService returns 401/403	Auth policy not satisfied	Check login state, AdminOnly policy, Bearer/Cookie auth context
KnowledgeBase embedding fails	Embedding model not configured	Configure embedding model in AIKernel first

10. Troubleshooting Priority (Use This Order)

1. Module state: verify installed + enabled first.
2. Function / MCP registration: then verify scan registration results.
3. Auth and logs: only then inspect 401/403, policy, and runtime logs.

Following this order avoids getting lost in low-value log details.

11. Common Beginner Mistakes

• Mistake 1: using IXncfRegister.Functions to understand Function registration.
  Current mechanism is [FunctionRender] on AppService methods.

• Mistake 2: treating “installed” as “ready”.
  You usually still need enablement, permissions, and configuration.

• Mistake 3: jumping into logs first.
  Without checking module state and config, logs become noisy and misleading.

• Mistake 4: assuming AI errors are code bugs first.
  In many cases the root cause is model/key/quota/network configuration.

12. Next-Step Roadmap (By Role)

• Beginner: NcfPackageSources Overview -> NCF Capability Source Deep Dive -> NCF FAQ

• Module developer: XNCF Overview -> Develop XNCF -> Core Interface IXncfRegister

• AI application developer: NCF Capability Source Deep Dive -> MCP Module Docs -> module pages for AIKernel / PromptRange / AgentsManager / KnowledgeBase

• Operations / release engineer: DatabasePlant Docs -> Windows Deployment / Docker Deployment

13. Open-Source Collaboration Entry Points

• Framework-level issues (template/install/upgrade): use NCF Issues first.
  https://github.com/NeuCharFramework/NCF/issues

• Core package source issues (base libs/module register/runtime behavior): use NcfPackageSources Issues/PRs.
  https://github.com/NeuCharFramework/NcfPackageSources/issues

Question-asking tips that dramatically improve response speed:

1. Include commit SHA (or release tag).
2. Include minimum reproducible steps (3-8 steps).
3. Include key logs (after desensitization).
4. State expected result vs actual result clearly.