fix(api): address PR #460 code review issues (75-score)

- Return 404 instead of 500 when GetByPath fails in DownloadArtifact
- Thread UserKEK through learning space creation so default skills are encrypted
- Update docs for encryption-aware SDK behavior (download fallback, raw_content)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: GenerQAQ

docs/content/docs/(guides)/store/(features)/skill.mdx

@@ -130,20 +130,38 @@ for (const fileInfo of skillDetails.fileIndex || []) {
 result = client.skills.get_file(skill_id=skill.id, file_path="SKILL.md")
 print(result.content.raw)
 
-# Binary files return a URL instead
+# Binary files return a URL or base64-encoded content
 result = client.skills.get_file(skill_id=skill.id, file_path="images/diagram.png")
-print(result.url)
+if result.raw_content:
+    # Encryption enabled — binary content returned as base64
+    import base64
+    data = base64.b64decode(result.raw_content)
+elif result.url:
+    # No encryption — presigned URL for direct download
+    print(result.url)
 ```
 
 ```typescript title="TypeScript"
 const fileResult = await client.skills.getFile({ skillId: skill.id, filePath: "SKILL.md" });
 console.log(fileResult.content?.raw);
 
-// Binary files return a URL instead
+// Binary files return a URL or base64-encoded content
 const imageResult = await client.skills.getFile({ skillId: skill.id, filePath: "images/diagram.png" });
-console.log(imageResult.url);
+if (imageResult.raw_content) {
+    // Encryption enabled — binary content returned as base64
+    const buffer = Buffer.from(imageResult.raw_content, 'base64');
+} else if (imageResult.url) {
+    // No encryption — presigned URL for direct download
+    console.log(imageResult.url);
+}
 ```
 </CodeGroup>
+
+The SDK uses a 3-way fallback when downloading skill files:
+1. **`content.raw`** — text content, returned inline
+2. **`raw_content`** — base64-encoded binary content (when envelope encryption is enabled)
+3. **`url`** — presigned S3 URL for direct download (when encryption is off)
+
 </Step>
 
 <Step title="Delete skill">

docs/content/docs/(guides)/tool/(features)/disk_tools.mdx

@@ -135,6 +135,10 @@ while (true) {
 {"filename": "report.pdf", "file_path": "/", "expire": 3600}
 ```
 
+<Note>
+When **envelope encryption** is enabled on the project, presigned URLs cannot be generated because files are encrypted at rest with a per-project key. In this case the tool returns a message directing the LLM to use the API download endpoint instead.
+</Note>
+
 ### grep_disk
 
 Search file contents with regex:

docs/content/docs/(guides)/tool/(features)/skill_tools.mdx

@@ -133,6 +133,10 @@ Returns: Skill ID, description, and file index with MIME types.
 
 Returns: File content (text) or presigned URL (binary).
 
+<Note>
+When **envelope encryption** is enabled, binary files are returned as base64-encoded content (`raw_content` field) instead of a presigned URL, since encrypted objects cannot be served directly from S3. The tool presents the content inline to the LLM regardless of delivery method.
+</Note>
+
 <Warning>
 **Read-only:** These tools can only read skill content. To execute skill scripts, use [Sandbox Tools](/tool/bash_tools#mounting-agent-skills).
 </Warning>

src/server/api/go/internal/modules/handler/artifact.go

@@ -252,7 +252,7 @@ func (h *ArtifactHandler) GetArtifact(c *gin.Context) {
 
 	artifact, err := h.svc.GetByPath(c.Request.Context(), diskID, filePath, filename)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, serializer.DBErr("", err))
+		c.JSON(http.StatusNotFound, serializer.DBErr("artifact not found", err))
 		return
 	}
 
@@ -330,7 +330,7 @@ func (h *ArtifactHandler) DownloadArtifact(c *gin.Context) {
 
 	artifact, err := h.svc.GetByPath(c.Request.Context(), diskID, filePath, filename)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, serializer.DBErr("", err))
+		c.JSON(http.StatusNotFound, serializer.DBErr("artifact not found", err))
 		return
 	}
 

src/server/api/go/internal/modules/handler/learning_space.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
+	"github.com/memodb-io/Acontext/internal/middleware"
 	"github.com/memodb-io/Acontext/internal/modules/model"
 	"github.com/memodb-io/Acontext/internal/modules/serializer"
 	"github.com/memodb-io/Acontext/internal/modules/service"
@@ -112,6 +113,7 @@ func (h *LearningSpaceHandler) Create(c *gin.Context) {
 		ProjectID: project.ID,
 		UserID:    userID,
 		Meta:      req.Meta,
+		UserKEK:   middleware.GetUserKEK(c),
 	})
 	if err != nil {
 		h.handleErr(c, err)

src/server/api/go/internal/modules/service/learning_space.go

@@ -54,6 +54,7 @@ type CreateLearningSpaceInput struct {
 	ProjectID uuid.UUID
 	UserID    *uuid.UUID
 	Meta      map[string]interface{}
+	UserKEK   []byte // optional: for envelope encryption of default skill files
 }
 
 type UpdateLearningSpaceInput struct {
@@ -155,7 +156,7 @@ func (s *learningSpaceService) Create(ctx context.Context, in CreateLearningSpac
 	if err := s.lsRepo.Create(ctx, ls); err != nil {
 		return nil, fmt.Errorf("create learning space: %w", err)
 	}
-	if err := s.initDefaultSkills(ctx, ls); err != nil {
+	if err := s.initDefaultSkills(ctx, ls, in.UserKEK); err != nil {
 		return nil, err
 	}
 	return ls, nil
@@ -164,7 +165,7 @@ func (s *learningSpaceService) Create(ctx context.Context, in CreateLearningSpac
 // initDefaultSkills creates the default skills from embedded templates and
 // links them to the given learning space. On failure it performs best-effort
 // cleanup of any resources already created (skills, disks, the space itself).
-func (s *learningSpaceService) initDefaultSkills(ctx context.Context, ls *model.LearningSpace) (retErr error) {
+func (s *learningSpaceService) initDefaultSkills(ctx context.Context, ls *model.LearningSpace, userKEK []byte) (retErr error) {
 	var createdSkills []*model.AgentSkills
 	defer func() {
 		if retErr == nil {
@@ -195,6 +196,7 @@ func (s *learningSpaceService) initDefaultSkills(ctx context.Context, ls *model.
 			ProjectID: ls.ProjectID,
 			UserID:    ls.UserID,
 			Content:   content,
+			UserKEK:   userKEK,
 		})
 		if err != nil {
 			return fmt.Errorf("create skill from template %s: %w", tmplPath, err)